adding documentation for demo / examples

README.md

@@ -52,7 +52,7 @@ And you don't need to create Java objects (or POJO-s) for any of the payloads th
  | [`responseHeaders`](#responseheaders) | [`responseStatus`](#responsestatus) | [`responseTime`](#responsetime)
  **Reusable Functions** | [`call`](#call) | [`karate` object](#the-karate-object)
  **Tips and Tricks** | [Embedded Expressions](#embedded-expressions) | [GraphQL RegEx Example](#graphql--regex-replacement-example) | [Multi-line Comments](#multi-line-comments) | [Cucumber Tags](#cucumber-tags)
- | [Data Driven Tests](#data-driven-tests) | [Auth](#sign-in-example) / [Headers](#http-basic-authentication-example) | [Dynamic Port Numbers](#dynamic-port-numbers) | [Ignore / Vallidate](#ignore-or-validate)
+ | [Data Driven Tests](#data-driven-tests) | [Auth](#sign-in-example) / [Headers](#http-basic-authentication-example) | [Ignore / Vallidate](#ignore-or-validate) | [Examples and Demos](karate-demo)
 
 # Features
 * Java knowledge is not required to write tests
@@ -158,6 +158,8 @@ And assert responseTime < 1000
 And match response == read('test.pdf')
 ```
 
+A set of complete real-life examples can be found here: [Karate Demo](karate-demo)
+
 # Getting Started
 Karate requires [Java](http://www.oracle.com/technetwork/java/javase/downloads/index.html) 8
 and [Maven](http://maven.apache.org) to be installed.

karate-demo/README.md

@@ -0,0 +1,20 @@
+# Karate Demo
+This is a sample [Spring Boot](http://projects.spring.io/spring-boot/) web-application that exposes some functionality as web-service end-points. And includes a set of Karate examples that test these services
+as well as demonstrate various Karate features and best-practices.
+
+| Example | Demonstrates
+----------| --------
+[`greeting.feature`](src/test/java/demo/greeting/greeting.feature) | Simple GET and multiple scenarios in a test
+[`cats.feature`](src/test/java/demo/cats/cats.feature) | Great example of [embedded-expressions](https://github.com/intuit/karate#embedded-expressions) (or JSON / XML templating). Also shows how to set the `Accept` header for getting XML from the server.
+[`kittens.feature`](src/test/java/demo/cats/kittens.feature) | Reading a complex payload expected response [from a file](https://github.com/intuit/karate#reading-files). You can do the same for request payloads as well. Observe how [JSON templating](https://github.com/intuit/karate#embedded-expressions) makes creating dynamic JSON super-easy, look at [line #24](src/test/java/demo/cats/kittens.feature#L24) for example.
+[`upload.feature`](src/test/java/demo/upload/upload.feature) | Multi-part file-upload example, as well as comparing the binary content of a download. Also shows how to assert for expected response headers.
+
+## Best Practices
+| File | Demonstrates
+----------| --------
+[`karate-config.js`](src/test/java/karate-config.js) | Shows how the `demoBaseUrl` property is injected into all the test scripts on startup. Notice how JavaScript allows you to perform simple conditional logic and string manipulation, while still being a 'devops-friendly' plain-text file.
+[`BaseTest.java`](src/test/java/demo/BaseTest.java#L22) | This is specific to Spring Boot, but this code takes care of starting the embedded app-server and dynamically chooses a free port. The chosen port value is passed to the above config routine via a Java `System.setProperty()` call.
+[`TestAll.java`](src/test/java/demo/TestAll.java) | This Java class is strategically placed at the root of the directory structure containing `*.feature` files. The reason will be apparent in the next line.
+[`pom.xml`](pom.xml#L66) | Line 66 shows how the [`maven-surefire-plugin`](http://maven.apache.org/surefire/maven-surefire-plugin/examples/inclusion-exclusion.html) can be configured to point to what is basically your 'test-suite'. Refer to the Karate documentation on how you could choose to select a sub-set of tests using [tags](https://github.com/intuit/karate#cucumber-tags)
+
+

karate-demo/src/main/java/com/intuit/karate/demo/controller/CatsController.java

@@ -63,4 +63,9 @@ public Cat get(@PathVariable int id) {
         return cats.get(id);
     }
 
+    @GetMapping("/{id:.+}/kittens")
+    public Collection<Cat> getKittens(@PathVariable int id) {
+        return cats.get(id).getKittens();
+    }    
+
 }

karate-demo/src/test/java/demo/BaseTest.java

@@ -1,26 +1,3 @@
-/*
- * The MIT License
- *
- * Copyright 2017 pthomas3.
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in
- * all copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
- * THE SOFTWARE.
- */
 package demo;
 
 import com.intuit.karate.junit4.Karate;

karate-demo/src/test/java/demo/TestAll.java

@@ -1,26 +1,3 @@
-/*
- * The MIT License
- *
- * Copyright 2017 Intuit Inc.
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in
- * all copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
- * THE SOFTWARE.
- */
 package demo;
 
 /**

karate-demo/src/test/java/demo/cats/CatsTest.java

@@ -1,34 +1,13 @@
-/*
- * The MIT License
- *
- * Copyright 2017 Intuit Inc.
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in
- * all copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
- * THE SOFTWARE.
- */
 package demo.cats;
 
+import cucumber.api.CucumberOptions;
 import demo.BaseTest;
 
 /**
  *
  * @author pthomas3
  */
+@CucumberOptions(features = "classpath:demo/cats/cats.feature")
 public class CatsTest extends BaseTest {
 
 }

karate-demo/src/test/java/demo/cats/KittensTest.java

@@ -0,0 +1,13 @@
+package demo.cats;
+
+import cucumber.api.CucumberOptions;
+import demo.BaseTest;
+
+/**
+ *
+ * @author pthomas3
+ */
+@CucumberOptions(features = "classpath:demo/cats/kittens.feature")
+public class KittensTest extends BaseTest {
+
+}

karate-demo/src/test/java/demo/cats/billie-expected.json

@@ -0,0 +1,8 @@
+{ 
+  id: '#number',
+  name: 'Billie',
+  kittens: [
+    { id: '#(bob.id)', name: 'Bob' },
+    { id: '#(wild.id)', name: 'Wild' }
+  ]
+}

karate-demo/src/test/java/demo/cats/kittens.feature

@@ -0,0 +1,38 @@
+Feature: cats with kittens
+
+Background:
+* url demoBaseUrl
+
+Scenario: create cat with kittens
+
+    # create bob cat
+    Given path 'cats'
+    And request { name: 'Bob' }
+    When method post
+    Then status 200
+    And def bob = response
+
+    # create wild cat
+    Given path 'cats'
+    And request { name: 'Wild' }    
+    When method post
+    Then status 200
+    And def wild = response
+
+    # create mom cat
+    Given path 'cats'
+    And request { name: 'Billie', kittens: ['#(bob)', '#(wild)'] }
+    When method post
+    Then status 200
+    And match response == read('billie-expected.json')
+    And def billie = response
+
+    # get kittens for billie
+    Given path 'cats', billie.id, 'kittens'
+    When method get
+    Then status 200
+    And match each response == { id: '#number', name: '#string' }
+    And match response contains { id: '#(wild.id)', name: 'Wild' }
+
+
+

karate-demo/src/test/java/demo/greeting/GreetingTest.java

@@ -1,26 +1,3 @@
-/*
- * The MIT License
- *
- * Copyright 2017 Intuit Inc.
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in
- * all copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
- * THE SOFTWARE.
- */
 package demo.greeting;
 
 import demo.BaseTest;

karate-demo/src/test/java/demo/upload/UploadTest.java

@@ -1,26 +1,3 @@
-/*
- * The MIT License
- *
- * Copyright 2017 Intuit Inc.
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in
- * all copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
- * THE SOFTWARE.
- */
 package demo.upload;
 
 import demo.BaseTest;