Testcase spec. reference revamp

Author: 0hsn

docs/references/http-reference.md

@@ -302,6 +302,8 @@ request:
 ```
 ### `expose`
 
-`expose` is a sub-block, that can be used to expose local variable of this file to outer scope. For specification document that support http request also have a local variable called `$_response` which holds successful response in parsed format.
+`expose` is a sub-block, that can be used to expose local variable of this file to outer scope.
+
+For http specification document local variable called `$_response` which holds successful response, is available.
 
 See docs on [expose node](/references/variable-reference#expose-node)

docs/references/testcase-reference.md

@@ -8,7 +8,7 @@ title: Testcase specification reference
 - Currently JSON response is only supported type for assertions.
 :::
 
-The Testcase specification format is how anyone express one or more Testcase(s) for a given Http specification. Following is the full reference to write Testcase specification file.
+The _Testcase specification_ format is how anyone express one or more test case(s) for a given _Http specification_. Following is the full reference to write _Testcase specification_ file.
 
 ## Testcase specification
 
@@ -18,14 +18,19 @@ It's also an _**exposable document**_ meaning you can expose local data using `e
 
 ### Reference as example
 
+There are 2 ways Testcase doc can be written. 1) `request` is in-file, 2) `request` in separate http file.
+
+#### 1) `request` is in-file
+
+1st way is to write a `request` (that defines the http request) and `spec` (that defines what to assert) in same file. E.g:
+
 ```yaml
 ---
 version: 'default:testcase:0.7.2'
 
 variables:
   Name: 'Morpheus'
   Job: 'leader'
-  Response: ~
   Server: https://reqres.in/api/v1
 
 request:
@@ -35,20 +40,58 @@ request:
     'name': $Name,
     'job': $Job,
   }
-  return: ~
 
 spec:
-  execute:
-    file: ~
-    with: ~
-    result: $Response
-
   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}
 
 expose:
   - $_assertion_results
+  - $_response
+```
+
+2) `request` in separate http file
+
+```yaml
+# file: some-request.chk
+---
+version: 'default:testcase:0.7.2'
+
+variables:
+  Name: 'Morpheus'
+  Job: 'leader'
+  Server: https://reqres.in/api/v1
+
+request:
+  url: "{$Server}/users"
+  method: POST
+  body[json]: {
+    'name': $Name,
+    'job': $Job,
+  }
+```
+
+and a separate testcase file
+
+```yaml
+# file: some-testcase.chk
+---
+version: 'default:testcase:0.7.2'
+
+spec:
+  execute:
+    file: some-request.chk
+    with:
+      Name: 'Neo'
+      Job: 'The chosen one'
+
+  asserts:
+    - {type: AssertEqual, actual: $_response.code, expected: 201}
+    - {type: AssertIsMap, actual: $_response.body}
+
+expose: ~
+
 ```
 
 ---
@@ -59,11 +102,13 @@ expose:
 
 ### `request`
 
-- _`required`_ if `spec.execute.file` is empty
-- _`optional`_ if `spec.execute.file` if a http specification doc is linked
+- _`required`_ if no external http spec. doc to be linked
+- _`must not`_ if `spec.execute.file` if a http specification doc is linked
 
 `request` is a top-level block that defines a http request. How to write a `request:` block, is [already defined here](/references/http-reference#request-required).
 
+`request` block, and `spec.execute.file` MUST NOT stay on same file. System will throw an error on that case.
+
 ### `variables`
 
 `variables` is a top-level block that defines local variables. These variables are file scoped. How to write a `variables:` block, is [already defined here](/references/variable-reference).
@@ -81,8 +126,7 @@ spec:
 
 `spec.execute` is a sub-block that defines a testcase spec's pre-requisite http request execution before making assertion(s). It has following components:
 
-- `spec.execute.file` is used to point the file that contains http specification to run before assertion. If unavailable, or set to null, then execute current file `request` block.
-  > [TBD] External file not supported now
+- `spec.execute.file` is used to point the file that contains http specification to run before assertion. If unavailable, or set to null, then system executes any `request` block from current file.
 - `spec.execute.with` is used to pass local scoped variables to external linked file on `spec.execute.file` before execution happen. Not supported for locally linked `request` block.
 - `spec.execute.result` is used to store result(s) of the execution. Here we can put a locally scoped variable to receive data to store after request is done.
 
@@ -93,8 +137,10 @@ variables:
 
 spec:
   execute:
-    file: ~
-    with: ~
+    file: some-request.chk
+    with:
+      Name: 'Neo'
+      Job: 'The chosen one'
     result: $Response
 ```
 
@@ -121,6 +167,8 @@ spec:
 
 ### `expose`
 
-`expose` is a sub-block, that can be used to expose local variable of this file to outer scope. For testcase specification document have a local variable called `$_assertion_results` which holds after assertion output.
+`expose` is a sub-block, that can be used to expose local variable of this file to outer scope. 
+
+For testcase specification document local variable called `$_assertion_results` which holds after assertion output, and `$_response` which holds response after request execute, are available.
 
 See docs on [expose node](/references/variable-reference#expose-node)