merge

docs/md/_toc.md

@@ -1,7 +1,96 @@
 [Home](/)
+<<<<<<< Updated upstream
 [Getting Started](/docs/getting-started)
 [Basic Concepts](/docs/basic-concepts)
 [CLI](/docs/cli)
 [Features](/docs/features)
 [Reporters](/docs/reporters)
 [Examples](/docs/examples)
+=======
+
+> :Collapse label=Getting Started
+>
+> [Installation](/docs/getting-started/installation)
+> [REST API](/docs/getting-started/rest-api)
+> [GraphQL](/docs/getting-started/graphql)
+
+> :Collapse label=Basics
+>
+> [Overview](/docs/basics/overview)
+> [Meta](/docs/basics/meta)
+> [Config](/docs/basics/config)
+> [Specs](/docs/basics/specs)
+
+> :Collapse label=Request
+>
+> [Request Basics](/docs/request/request-basics)
+> [Headers](/docs/request/headers)
+> [Cookies](/docs/request/cookies)
+> [Query Parameters](/docs/request/query-parameters)
+> [Path Parameters](/docs/request/path-parameters)
+>
+> > :Collapse label=Payload Body
+> >
+> > [JSON Body](/docs/request/payload-body/json-body)
+> > [Binary Data](/docs/request/payload-body/binary-data)
+> > [URL Encoded Form Data](/docs/request/payload-body/url-encoded-form-data)
+> > [Multi-Part Form Data](/docs/request/payload-body/multi-part-form-data)
+>
+> [File Uploads](/docs/request/file-uploads)
+> [Additional Options](/docs/request/additional-options)
+
+> :Collapse label=Response Validation
+>
+> [Overview](/docs/response-validation/overview)
+>
+> > :Collapse label=Assertions
+> >
+> > [Exact Value](/docs/response-validation/overview#exact-value)
+> > [Regular Expression](/docs/response-validation/overview#regular-expression)
+> > [Exact Value](/docs/response-validation/overview#exact-value)
+> > [Custom JS Validator](/docs/response-validation/overview#custom-validator)
+>
+> [Status Code](/docs/response-validation/status-code)
+> [Headers & Cookies](/docs/response-validation/overview#general-assertions)
+>
+> > :Collapse label=Body
+> >
+> > [Overview](/docs/response-validation/body/overview)
+> > [Exact Value](/docs/response-validation/body/overview#exact-value)
+> > [Regular Expression](/docs/response-validation/body/overview#regular-expression)
+> > [JSON Path](/docs/response-validation/body/overview#json-path)
+> > [JSON Schema Inline](/docs/response-validation/body/json-schema-inline)
+> > [JSON Schema File](/docs/response-validation/body/json-schema-file)
+> > [Swagger / Open API](/docs/response-validation/body/swagger-open-api)
+
+> :Collapse label=Hooks & JS
+>
+> [Overview](/docs/hooks/overview)
+> [JS Inline Functions](/docs/hooks/overview#js-inline-functions)
+> [JS Async Inline Functions](/docs/hooks/overview#js-async-inline-functions)
+> [JS Modules](/docs/hooks/overview#js-modules)
+>
+> > :Collapse label=Types of Hooks
+> >
+> > [before_each](/docs/hooks/types#before_all)
+> > [before_each](/docs/hooks/types#after_all)
+> > [before_each](/docs/hooks/types#before_each)
+> > [after_each](/docs/hooks/types#after_each)
+> > [before_test](/docs/hooks/types#before_test)
+> > [after_test](/docs/hooks/types#after_test)
+> > [custom_configuration](/docs/hooks/types#custom_configuration)
+
+> :Collapse label=DRY & Reusing Specs
+>
+> [Overview](/docs/reusing-specs/overview)
+> [Looping](/docs/reusing-specs/looping)
+> [Yaml Anchors](/docs/reusing-specs/yaml-anchors)
+> [Run Existing Spec](/docs/reusing-specs/run-spec-in-js)
+
+> :Collapse label=Command Line Interface (CLI)
+>
+> [Debugging](/docs/cli/debugging)
+> [Running Suites in Parallel](/docs/cli/running-suites-parallel)
+> [Reporters](/docs/cli/reporters)
+> [Options](/docs/cli/options)
+>>>>>>> Stashed changes

docs/md/docs/basics/overview.md

@@ -0,0 +1,28 @@
+# Spec Overview & Basic Concepts
+
+## The High-level View
+
+REST-EZ's lets you test HTTP-based APIs without code. It aims to make API testing easy, free, and fast for everyone.
+
+Write your API test specs in YAML. We call each YAML file a test **suite**.
+
+You also have the option to [write Javascript](/docs/hooks/overview).
+
+If needed, you can [use external files & npm modules](/docs/hooks/js-modules).
+
+## Required Sections
+
+A test suite has three required sections:
+
+- [meta](/docs/basics/meta)
+- [configuration](/docs/basics/config)
+- [specs](/docs/basics/specs)
+
+## Optional Sections
+
+Optional sections are:
+
+- [hooks](/docs/hooks/overview)
+- [spec_dependencies](/docs/reusing-specs/run-spec-in-js#spec_dependencies)
+
+> :ToCPrevNext

docs/md/docs/hooks/overview.md

@@ -0,0 +1,26 @@
+# Hooks & JS
+
+- [JS Inline Functions](#js-inline-functions)
+- [JS Async Inline Functions](#js-async-inline-functions)
+- [JS Modules](#js-modules)
+- [Types of Hooks](/docs/hooks/types#types-of-hooks)
+  - [before_all](/docs/hooks/types#before_all)
+  - [after_all](/docs/hooks/types#after_all)
+  - [before_each](/docs/hooks/types#before_each)
+  - [after_each](/docs/hooks/types#after_each)
+  - [before_test](/docs/hooks/types#before_test)
+  - [after_test](/docs/hooks/types#after_test)
+  - [custom_configuration](/docs/hooks/types#custom_configuration)
+
+## JS Inline Functions
+
+<br><br>
+
+## JS Async Inline Functions
+
+<br><br>
+
+## JS Modules
+
+<br><br>
+

docs/md/docs/hooks/types.md

@@ -0,0 +1,35 @@
+# Types of Hooks
+
+## Suite-Level
+
+### before_all
+
+<br><br>
+
+### after_all
+
+<br><br>
+
+### before_each
+
+<br><br>
+
+### after_each
+
+<br><br>
+
+### custom_configuration
+
+<br><br>
+
+## Spec-Level
+
+<br><br>
+
+### before_test
+
+<br><br>
+
+### after_test
+
+<br><br>

docs/md/docs/reusing-specs/looping.md

@@ -0,0 +1,158 @@
+# Looping
+
+You can use the loop construct to loop through a list of items, each item generating a test.
+
+When the `loop` property is specified, that spec will be run once for each item provided with the `this.loopItem` available in the lifecycle hooks (`before_test` and `after_test`).
+
+The list of items can be specified in spec beforehand or you can specify a custom JS function which returns a list of items.
+
+## Static Loop
+
+Here's how a static loop is specified, `type` is static and loop list is mapped to `static` field as list of items.
+
+```yaml | specs/star-wars-static-loop.yml
+meta:
+  name: Star Wars static loop
+configuration:
+  scheme: https
+  host: swapi.dev
+specs:
+  - name: fetch each character
+    loop:
+      type: static
+      static:
+        - 1 # Luke Skywalker
+        - 4 # Darth Vader
+    before_test:
+      run_type: inline
+      inline:
+        function: !!js/function >
+          function() {
+            this.test.path_params = { userId : this.loopItem };
+          }
+    request:
+      path: /api/people/{userId}/  # <--- runs twice: once as "/api/people/1/" and once as "/api/people/4"
+      method: get
+    response:
+      status_code: 200
+      json_data:
+        - path: $.gender
+          value: male
+```
+
+**See also:** [Example: Suite Using Loops](https://github.com/blossomfinance/rest-ez/blob/3f7b2f4fe69e77b4faaeefcf20ec0aa98863af51/test/cli/src/suites/loop.suite.yml)
+
+<br><br>
+
+## Dynamic Loop Using JS
+
+Here's how a static loop is specified, `type` is static and loop list is mapped to `static` field as list of items.
+
+```yaml | specs/star-wars-dynamic-loop.yml
+meta:
+  name: Star Wars dynamic loop
+configuration:
+  scheme: https
+  host: swapi.dev
+specs:
+  - name: fetch each character
+    loop:
+      type: dynamic
+      dynamic:
+        run_type: inline
+        inline:
+          function: !!js/function  >
+            function() {
+              var generatePositiveInt = (max) => {
+                return Math.floor(Math.random() * max) + 1;
+              };
+              var runTimes = generatePositiveInt(10);
+              var items = [];
+              while (items.length < runTimes) {
+                items.push(generatePositiveInt());
+              }
+              return runTimes;
+            }
+    before_test:
+      run_type: inline
+      inline:
+        function: !!js/function >
+          function() {
+            this.test.path_params = { userId : this.loopItem };
+          }
+    request:
+      path: /api/people/{userId}/  # <--- runs random {n} times with random ID between 1 to 100
+      method: get
+    response:
+      status_code: 200
+```
+
+**See also:** [Example: Suite Using Loops](https://github.com/blossomfinance/rest-ez/blob/3f7b2f4fe69e77b4faaeefcf20ec0aa98863af51/test/cli/src/suites/loop.suite.yml)
+
+<br><br>
+
+## Accessing Suite
+
+Your dynamic loop can also utilize existing data saved on the `this.suite` context:
+
+```yaml | star-wars-suite-w-previous-data.yml
+meta:
+  name: Star Wars dynamic suite with previous data
+configuration:
+  scheme: https
+  host: swapi.dev
+specs:
+  - name: fetch a movie
+    request:
+      path: /api/films/1/
+      method: get
+    after_test:
+      run_type: inline
+      inline:
+        function: !!js/function >
+          function () {
+            const film = JSON.parse(this.response.body);
+            this.suite.characters = film.characters;
+          }
+    response:
+      status_code: 200
+  - name: fetch each character for the first film
+    loop:
+      type: dynamic
+      dynamic:
+        run_type: inline
+        inline:
+          # transform the list of URLs into a list of IDs
+          function: !!js/function  >
+            function() {
+              return this.suite.characters.map((url) => {
+                var matches = url.match(/\/api\/people\/(\d+)\//);
+                return matches[1];
+              });
+            }
+    before_test:
+      run_type: inline
+      inline:
+        function: !!js/function >
+          function() {
+            this.test.path_params = { userId : this.loopItem };
+          }
+    request:
+      path: /api/people/{userId}/
+      method: get
+    response:
+      status_code: 200
+    after_test:
+      run_type: inline
+      inline:
+        function: !!js/function >
+          function() {
+            var character = JSON.parse(this.response.body);
+            console.log(character);
+          }
+```
+
+<br><br>
+
+
+> :ToCPrevNext

docs/md/docs/reusing-specs/overview.md

@@ -0,0 +1,9 @@
+# Reusing Specs & DRY Techniques
+
+REST-EZ has several features aimed at code re-use:
+
+> [Looping](/docs/reusing-specs/looping)
+> [Yaml Anchors](/docs/reusing-specs/yaml-anchors)
+> [Run Existing Spec](/docs/reusing-specs/run-spec-in-js)
+> [Run Spec from Other Suite](/docs/reusing-specs/intersuite-spec-deps)
+