doc: add more examples to collection runner (#237)

* doc: example csv use for collection runner

* fix: add sdk changes

* fix: add title

* fix: minor change

---------

Co-authored-by: George He <[email protected]>

docs/insomnia/collection-runner.md

@@ -23,6 +23,41 @@ To do this, upload a custom CSV or JSON file. The variables detected from these
 
 ![collection run preview data](/assets/images/collection-runner-preview-data.png)
 
+#### Example: CSV
+
+You can setup variables by the name they have on the sample data file of your choice, for example:
+
+```csv
+Title,ReleaseYear,Developer
+Command & Conquer: Tiberian Dawn,1995,Westwood Studios
+Command & Conquer: Red Alert,1996,Westwood Studios
+Command & Conquer: Tiberian Sun,1999,Westwood Studios
+Command & Conquer: Red Alert 2,2000,Westwood Studios
+...
+```
+
+Means that anywhere on your requests you can setup `Title`, `ReleaseYear` and `Developer`, like:
+
+![example template var](/assets/images/example-collection-runner-setup-templatevar.png)
+
+And when running the collection runner they will be replaced in place.
+
+![example collection run variables results](/assets/images/example-result-collection-runner-variables.png)
+
+{:.alert .alert-primary}
+**Note**: It is also allowed to reference values from CSV or JSON in the same manner as referencing [environment variables](/insomnia/environment-variables/). And variables from data files will take precedence over [environment variables](/insomnia/environment-variables/).
+
+
+#### Example: JSON
+
+JSON also works with runner, this is an example:
+```json
+[
+    {"id": 1, "deviceName": "device1" },
+    {"id": 2, "deviceName": "device2" }
+]
+```
+
 ## Test Results in the Collection Tab
 
 With the Collection Runner, we have also introduced a new **Test Results** section.
@@ -38,6 +73,50 @@ The **Test Results** section is also available when you run tests for an individ
 {:.alert .alert-primary}
 **Note**: The test results shown in the Requests and in the Collection Runner are not to be confused with [Insomnia's Unit Testing feature](/insomnia/unit-testing).
 
+## Work with Runner in Scripts
+
+The collection runner exposes several interfaces which help you to work with it in scripts.
+
+### Get Information of the Active Request
+
+The `insomnia.execution.location` and `insomnia.execution.location.current` exposes the path of the active request and the last element of path, for example:
+
+```javascript
+// Let's assume that the active request is located in: TopRequestGroup/RequestGroup/Request1
+
+console.log(insomnia.execution.location);
+// It will output: ["TopRequestGroup", "RequestGroup`", "Request1"]
+
+console.log(insomnia.execution.location.current);
+// It will output: Request1
+```
+
+### Skip the Current Request
+The `insomnia.execution.skipRequest` allows to skip the current active request in the pre-request script, for example, in the [pre-request scripts](/insomnia/pre-request-script):
+
+```javascript
+// The runner will skip the current request and move to the next one (if exists)
+insomnia.execution.skipRequest();
+```
+
+### Dynamically Set the Next Request
+
+The `insomnia.execution.setNextRequest` accepts request id or request name as the next request. Currently you are able to call it in the [pre-request script](/insomnia/pre-request-script), for example:
+
+```javascript
+// The runner will move to the specified request (if exists), by skipping some requests
+insomnia.execution.setNextRequest("requestName");
+```
+
+```javascript
+// Request id is also supported
+insomnia.execution.setNextRequest("req_23590845293c4005b2127e211369f069");
+```
+This allows to dynamically change the workflow.
+
+### Abort the Execution
+
+The `insomnia.execution.setNextRequest` can be used to redirect to a request for teardown, so that the exeuction will be ended.
 
 ## Run with CLI