Testcase example added

Author: 0hsn

docs/assets/testcase-eximg-01.png

@@ -13,37 +13,114 @@ Case-wise more example can be found in [https://github.com/chkware/cli](https://
 
 [Testcase specification document reference](/references/testcase-reference)
 
-Testcase is an experimental feature, in _`PRE_ALPHA`_ stage.
+### A minimal Testcase with in-file request
 
-### Testcase with in-file request
+```yaml
+---
+version: 'default:testcase:0.7.2'
+
+request:
+  url: "https://reqres.in/api/users"
+  method: POST
+  body[json]: {
+    'name': My Name,
+    'job': My Job,
+  }
+
+spec:
+  asserts:
+    - {type: AssertEqual, actual: $_response.code, expected: 201}
+    - {type: AssertIsMap, actual: $_response.body}
+```
+
+The above testcase spec. doc define a request that makes a `POST` call to `https://reqres.in/api/users` URL with a body `{"name": "My Name", "job": "My Job"}`.
+
+After the request server responses with following:
+
+![reqres.in response](../assets/testcase-eximg-01.png)
+
+On the `asserts`, we are asserting that
+
+- The response code is 201, or the resource was created
+- The response if a map / dictionary
+
+Assertion [reference with examples](/references/testcase-reference#assertions) can be found here.
+
+### A minimal Testcase with out-file request
+
+A http spec. doc can be written on separate file, that does same as above request. Let's call it `same-request.chk`. The http spec. doc by default exposes `$_response` object.
 
 ```yaml
+# file: same-request.chk
+---
+version: 'default:http:0.7.2'
+
+request:
+  url: "https://reqres.in/api/users"
+  method: POST
+  body[json]: {
+    'name': My Name,
+    'job': My Job,
+  }
+```
+
+Now we can point out above file to execute before make assertions like below (assuming both file lives on same directory).
+
+```yaml
+# file: same-testcase.chk
 ---
 version: 'default:testcase:0.7.2'
 
+spec:
+  execute:
+    file: "./same-request.chk"
+  asserts:
+    - {type: AssertEqual, actual: $_response.code, expected: 201}
+    - {type: AssertIsMap, actual: $_response.body}
+```
+
+Please notice the `$_response` in the testcase doc. This variable is available after the request gets executed as local variable.
+
+### A Testcase with out-file request passing data
+
+To pass data from a testcase spec. doc to a http spec. doc, we first need to add some variables. These variables can also have some default value. Say in the following case, we defined `name` and `job` variables with default value. So, if no value passed these values will be passed to server as part of request body.
+
+```yaml
+# file: same-request.chk
+---
+version: 'default:http:0.7.2'
+
 variables:
-  Name: 'Morpheus'
-  Job: 'leader'
-  Response: ~
-  Server: https://reqres.in/api/v1
+  name: My Name
+  job: My Job
 
 request:
-  url: "{$Server}/users"
+  url: "https://reqres.in/api/users"
   method: POST
   body[json]: {
-    'name': $Name,
-    'job': $Job,
+    'name': $name,
+    'job': $job,
   }
-  return: ~
+```
+
+Now we can point out which value we want to pass using `with` statement in `execute` block.
+
+```yaml
+# file: same-testcase.chk
+---
+version: 'default:testcase:0.7.2'
 
 spec:
   execute:
-    file: ~
-    result: $Response
-
+    file: "./same-request.chk"
+    with:
+      name: Her Name
+      job: Her Job
   asserts:
-    - {type: AssertEqual, actual: $Response.code, expected: 201}
-    - {type: AssertIsMap, actual: $Response.body}
+    - {type: AssertEqual, actual: $_response.code, expected: 201}
+    - {type: AssertIsMap, actual: $_response.body}
 ```
 
-Assertion [reference with examples](/references/testcase-reference#assertions) can be found here.
+Please notice that if we do not set a `with` then request will be sent with default value.
+
+Assertion [reference with examples](/references/testcase-reference#assertions) can be found here.

docs/examples/testcase-examples.md

@@ -56,7 +56,7 @@ expose:
 ```yaml
 # file: some-request.chk
 ---
-version: 'default:testcase:0.7.2'
+version: 'default:http:0.7.2'
 
 variables:
   Name: 'Morpheus'

docs/references/testcase-reference.md

@@ -55,7 +55,7 @@ Let's continue to test our [_XKCD.com JSON API http client_](/tutorials/http-cli
 
   Let us go through the testcase spec. we wrote. If you call the API `https://xkcd.com/614/info.0.json` in any Firefox, the response will be shown like this:
 
-  ![CHKware](../assets/http-resp-xkcdcom.png)
+  ![xkcd.com response](../assets/http-resp-xkcdcom.png)
 
   Please notice that the response contains node `num` and `year` on it. Thus on the spec. in `asserts` we are doing three assertions.
   - If response we got, has code 200; otherwise whether the response was successful.