Updated references and added runCode

Author: hawkeyexl

.scripts/buildSchemaReferences.js

@@ -18,6 +18,7 @@ async function main() {
     "goTo_v2",
     "httpRequest_v2",
     "runShell_v2",
+    "runCode_v2",
     "saveScreenshot_v2",
     "setVariables_v2",
     "startRecording_v2",

docs/references/schemas/config.md

@@ -10,28 +10,28 @@ Field | Type | Description | Default
 defaultCommand | string |  Optional. Default command to run when no command is specified.<br/><br/>Accepted values: `runTests`, `runCoverage` | 
 input | One of<br/>-&nbsp;string<br/>-&nbsp;array of strings |  Optional. Path(s) to test specifications and documentation source files. May be paths to specific files or to directories to scan for files. | `.`
 output | string |  Optional. Path of the of the file or directory in which to store the output of Doc Detective commands. If a file path is specified, the output is written to that file. If a file of that name already exists, Doc Detective creates appends an integer to the result file name. If a directory path is specified, the output file name is dependent on the command being run. | `.`
-recursive | boolean |  Optional. If `true` searches `input`, `setup`, and `cleanup` paths recursively for test specifications and source files. | `true`
+recursive | boolean |  Optional. If `true` searches `input`, `setup`, and `cleanup` paths recursively for test specificaions and source files. | `true`
 relativePathBase | string |  Optional. Whether paths should be interpreted as relative to the current working directory (`cwd`) or to the file in which they're specified (`file`).<br/><br/>Accepted values: `cwd`, `file` | `cwd`
 envVariables | string |  Optional. Path to a `.env` file to load before performing a Doc Detective operation. | 
 runTests | object |  Optional. Options for running tests. When running tests, values set here override general configuration options. | 
 runTests.input | One of<br/>-&nbsp;string<br/>-&nbsp;array of strings |  Optional. Path(s) to test specifications and documentation source files. May be paths to specific files or to directories to scan for files. | 
 runTests.output | string |  Optional. Path of the of the file or directory in which to store the output of Doc Detective commands. If a file path is specified, the output is written to that file. If a file of that name already exists, Doc Detective creates appends an integer to the result file name. If a directory path is specified, the output file name is dependent on the command being run. | `.`
 runTests.setup | One of<br/>-&nbsp;string<br/>-&nbsp;array of strings |  Optional. Path(s) to test specifications to perform before those specified by `input`. Useful for setting up testing environments. | 
 runTests.cleanup | One of<br/>-&nbsp;string<br/>-&nbsp;array of strings |  Optional. Path(s) to test specifications to perform after those specified by `input`. Useful for cleaning up testing environments. | 
-runTests.recursive | boolean |  Optional. If `true` searches `input`, `setup`, and `cleanup` paths recursively for test specifications and source files. | 
+runTests.recursive | boolean |  Optional. If `true` searches `input`, `setup`, and `cleanup` paths recursively for test specificaions and source files. | 
 runTests.detectSteps | boolean |  Optional. Whether or not to detect steps in input files based on markup regex. | `false`
 runTests.mediaDirectory | string |  Optional. DEPRECATED. | `.`
 runTests.downloadDirectory | string |  Optional. Path of the directory in which to store downloaded files. | `.`
 runTests.contexts | array of object([context](/docs/references/schemas/context)) |  Optional. Application/platform sets to run tests in. If no contexts are specified but a context is required by one or more tests, Doc Detective attempts to identify a supported context in the current environment and run tests against it. | ``[{"app":{"name":"firefox","options":{"width":1200,"height":800,"headless":true}},"platforms":["linux","mac","windows"]}]``
-runCoverage | object |  Optional. Options for performing test coverage analysis on documentation source files. When performing coverage analysis, values set here override general configuration options. | 
+runCoverage | object |  Optional. Options for performing test coverage analysis on documentation source files.  When performing coveration analysis, values set here override general configuration options. | 
 runCoverage.input | One of<br/>-&nbsp;string<br/>-&nbsp;array of strings |  Optional. Path(s) to test specifications and documentation source files. May be paths to specific files or to directories to scan for files. | 
 runCoverage.output | string |  Optional. Path of the of the file or directory in which to store the output of Doc Detective commands. If a file path is specified, the output is written to that file. If a file of that name already exists, Doc Detective creates appends an integer to the result file name. If a directory path is specified, the output file name is dependent on the command being run. | `.`
-runCoverage.recursive | boolean |  Optional. If `true` searches `input`, `setup`, and `cleanup` paths recursively for test specifications and source files. | 
+runCoverage.recursive | boolean |  Optional. If `true` searches `input`, `setup`, and `cleanup` paths recursively for test specificaions and source files. | 
 runCoverage.markup | array of strings |  Optional. Markup types to include when performing this operation. If no markup types are specified, the operation includes all markup types as defined in `fileTypes`. | ``["onscreenText","emphasis","image","hyperlink","codeInline","codeBlock","interaction"]``
-suggestTests | object |  Optional. Options for suggesting tests based on documentation source files. When suggesting tests, values set here override general configuration options. | 
+suggestTests | object |  Optional. Options for suggesting tests based on documentation source files.  When suggesting tests, values set here override general condiguration options. | 
 suggestTests.input | One of<br/>-&nbsp;string<br/>-&nbsp;array of strings |  Optional. Path(s) to test specifications and documentation source files. May be paths to specific files or to directories to scan for files. | 
 suggestTests.output | string |  Optional. Path of the of the file or directory in which to store the output of Doc Detective commands. If a file path is specified, the output is written to that file. If a file of that name already exists, Doc Detective creates appends an integer to the result file name. If a directory path is specified, the output file name is dependent on the command being run. | `.`
-suggestTests.recursive | boolean |  Optional. If `true` searches `input`, `setup`, and `cleanup` paths recursively for test specifications and source files. | 
+suggestTests.recursive | boolean |  Optional. If `true` searches `input`, `setup`, and `cleanup` paths recursively for test specificaions and source files. | 
 suggestTests.markup | array of strings |  Optional. Markup types to include when performing this operation. If no markup types are specified, the operation includes all markup types as defined in `fileTypes`. | ``["onscreenText","emphasis","image","hyperlink","codeInline","codeBlock","interaction"]``
 fileTypes | array of objects |  Optional. Information on supported file types and how to parse the markup within them. | []
 fileTypes.name | string |  Optional. Name of the file type. | 
@@ -49,6 +49,7 @@ fileTypes.markup.actions | array of <br/>- strings<br/>- objects<br/>-&nbsp;obje
 fileTypes.markup.actions.name | string |  Required. Name of the action.<br/><br/>Accepted values: `checkLink`, `find`, `goTo`, `httpRequest`, `runShell`, `saveScreenshot`, `setVariables`, `startRecording`, `stopRecording`, `typeKeys`, `wait` | 
 fileTypes.markup.actions.params | object |  Optional. Parameters for the action. | 
 integrations | object |  Optional. Options for connecting to external services. | 
+integrations.openApi | array of undefineds |  Optional. undefined | 
 telemetry | object |  Optional. Options around sending telemetry for Doc Detective usage. | ``{"send":true}``
 telemetry.send | boolean |  Required. If `true`, sends Doc Detective telemetry. | `true`
 telemetry.userId | string |  Optional. Identifier for the organization, group, or individual running Doc Detective. | 
@@ -99,6 +100,21 @@ logLevel | string |  Optional. Amount of detail to output when performing an ope
 }
 ```
 
+```json
+{
+  "integrations": {
+    "openApi": [
+      {
+        "name": "Acme",
+        "descriptionPath": "https://www.acme.com/openapi.json",
+        "server": "https://api.acme.com",
+        "mockResponse": true
+      }
+    ]
+  }
+}
+```
+
 ```json
 {
   "envVariables": "",

docs/references/schemas/context.md

@@ -15,6 +15,8 @@ app.path | string |  Optional. Absolute path or command for the application. If
 app.options | object |  Optional. Options to pass to the app. Only works when `name` is `firefox` or `chrome`. | 
 app.options.width | integer |  Optional. Width of the window in pixels. | 
 app.options.height | integer |  Optional. Height of the window in pixels. | 
+app.options.viewport_height | integer |  Optional. Height of the viewport in pixels. Overrides `height`. | 
+app.options.viewport_width | integer |  Optional. Width of the viewport in pixels. Overrides `width`. | 
 app.options.headless | boolean |  Optional. If `true`, runs the browser in headless mode. Not supported by Safari. | 
 app.options.driverPath | string |  Optional. Path to the browser driver. If not specified, defaults to internally managed dependencies. | 
 platforms | array of strings |  Required. Supported platforms for the application. | 
@@ -32,6 +34,21 @@ platforms | array of strings |  Required. Supported platforms for the applicatio
 }
 ```
 
+```json
+{
+  "app": {
+    "name": "chrome",
+    "options": {
+      "viewport_width": 800,
+      "viewport_height": 600
+    }
+  },
+  "platforms": [
+    "linux"
+  ]
+}
+```
+
 ```json
 {
   "app": {

docs/references/schemas/find.md

@@ -14,7 +14,7 @@ selector | string |  Required. Selector that uniquely identifies the element. |
 timeout | integer |  Optional. Max duration in milliseconds to wait for the element to exist. | `5000`
 matchText | string |  Optional. Text that the element should contain. If the element doesn't contain the text, the step fails. Accepts both strings an regular expressions. To use a regular expression, the expression should start and end with a `/`. For example, `/search/`. | 
 moveTo | [object Object] |  Optional. Move to the element. If the element isn't visible, it's scrolled into view. Only runs the if the test is being recorded. | `false`
-click | boolean |  Optional. Click the element. | `false`
+click | One of<br/>-&nbsp;boolean<br/>-&nbsp;object |  Optional. Click the element. | 
 typeKeys | One of<br/>-&nbsp;string<br/>-&nbsp;object |  Optional. Type keys after finding the element. Either a string or an object with a `keys` field as defined in [`typeKeys`](typeKeys). To type in the element, make the element active with the `click` parameter. | 
 setVariables | array of objects |  Optional. Extract environment variables from the element's text. | ``[]``
 setVariables.name | string |  Required. Name of the environment variable to set. | 
@@ -41,6 +41,16 @@ setVariables.regex | string |  Required. Regex to extract the environment variab
 }
 ```
 
+```json
+{
+  "action": "find",
+  "selector": "[title=Search]",
+  "click": {
+    "button": "right"
+  }
+}
+```
+
 ```json
 {
   "action": "find",

docs/references/schemas/httpRequest.md

@@ -9,8 +9,9 @@ Field | Type | Description | Default
 :-- | :-- | :-- | :--
 id | string |  Optional. ID of the step. | Generated UUID
 description | string |  Optional. Description of the step. | 
-action | string |  Required. Action to perform. | 
-url | string |  Required. URL for the HTTP request. | 
+action | string |  Required. Aciton to perform. | 
+url | string |  Optional. URL for the HTTP request. | 
+openApi | undefined |  Optional. undefined | 
 statusCodes | array of integers |  Optional. Accepted status codes. If the specified URL returns a code other than what is specified here, the action fails. | ``[200]``
 method | string |  Optional. Method of the HTTP request<br/><br/>Accepted values: `get`, `put`, `post`, `patch`, `delete` | `get`
 timeout | integer |  Optional. Timeout for the HTTP request, in milliseconds. | `60000`
@@ -121,3 +122,67 @@ envsFromResponseData.jqFilter | string |  Required. jq filter to apply to the re
   "overwrite": "byVariation"
 }
 ```
+
+```json
+{
+  "action": "httpRequest",
+  "openApi": {
+    "name": "Reqres",
+    "operationId": "getUserById"
+  },
+  "requestParams": {
+    "id": 123
+  }
+}
+```
+
+```json
+{
+  "action": "httpRequest",
+  "openApi": {
+    "descriptionPath": "https://api.example.com/openapi.json",
+    "operationId": "getUserById"
+  },
+  "requestParams": {
+    "id": 123
+  }
+}
+```
+
+```json
+{
+  "action": "httpRequest",
+  "openApi": {
+    "descriptionPath": "https://api.example.com/openapi.json",
+    "operationId": "createUser",
+    "useExample": "both"
+  }
+}
+```
+
+```json
+{
+  "action": "httpRequest",
+  "openApi": {
+    "descriptionPath": "https://api.example.com/openapi.json",
+    "operationId": "updateUser",
+    "useExample": "request",
+    "exampleKey": "acme"
+  }
+}
+```
+
+```json
+{
+  "action": "httpRequest",
+  "openApi": {
+    "descriptionPath": "https://api.example.com/openapi.json",
+    "operationId": "updateUser",
+    "useExample": "request",
+    "exampleKey": "acme",
+    "requestHeaders": {
+      "Authorization": "Bearer $TOKEN"
+    }
+  }
+}
+```

docs/references/schemas/runCode.md

@@ -0,0 +1,82 @@
+
+# runCode
+
+Assemble and run code.
+
+## Fields
+
+Field | Type | Description | Default
+:-- | :-- | :-- | :--
+id | string |  Optional. ID of the step. | Generated UUID
+description | string |  Optional. Description of the step. | 
+action | string |  Required. The action to perform. | 
+language | string |  Required. Language of the code to run. If not specified, the code is run in the shell.<br/><br/>Accepted values: `python`, `bash`, `javascript` | 
+code | string |  Required. Code to run. | 
+args | array of strings |  Optional. Arguments for the command. | ``[]``
+workingDirectory | string |  Optional. Working directory for the command. | `.`
+exitCodes | array of integers |  Optional. Expected exit codes of the command. If the command's actual exit code isn't in this list, the step fails. | ``[0]``
+output | string |  Optional. Content expected in the command's output. If the expected content can't be found in the command's output (either stdout or stderr), the step fails. Supports strings and regular expressions. To use a regular expression, the string must start and end with a forward slash, like in `/^hello-world.*/`. | 
+savePath | string |  Optional. File path to save the command's output, relative to `saveDirectory`. | 
+saveDirectory | string |  Optional. Directory to save the command's output. If the directory doesn't exist, creates the directory. If not specified, the directory is your media directory. | 
+maxVariation | integer |  Optional. Allowed variation in percentage of text different between the current output and previously saved output. If the difference between the current output and the previous output is greater than `maxVariation`, the step fails. If output doesn't exist at `savePath`, this value is ignored. | `0`
+overwrite | string |  Optional. If `true`, overwrites the existing output at `savePath` if it exists.
+If `byVariation`, overwrites the existing output at `savePath` if the difference between the new output and the existing output is greater than `maxVariation`.<br/><br/>Accepted values: `true`, `false`, `byVariation` | `false`
+timeout | integer |  Optional. Max time in milliseconds the command is allowed to run. If the command runs longer than this, the step fails. | `60000`
+setVariables | array of objects |  Optional. Extract environment variables from the command's output. | ``[]``
+setVariables.name | string |  Required. Name of the environment variable to set. | 
+setVariables.regex | string |  Required. Regex to extract the environment variable from the command's output. | 
+outputs | object |  Optional. Outputs from step processes and user-defined expressions. Use the `outputs` object to reference outputs in subsequent steps. If a user-defined output matches the key for a step-defined output, the user-defined output takes precedence. | 
+outputs.stdout | string |  Optional. Standard output of the command. | 
+outputs.stderr | string |  Optional. Standard error of the command. | 
+outputs.exitCode | integer |  Optional. Exit code of the command. | 
+
+## Examples
+
+```json
+{
+  "action": "runCode",
+  "language": "javascript",
+  "code": "console.log('Hello, ${process.env.USER}!');"
+}
+```
+
+```json
+{
+  "action": "runCode",
+  "language": "bash",
+  "code": "docker run hello-world",
+  "timeout": 20000,
+  "exitCodes": [
+    0
+  ],
+  "output": "Hello from Docker!"
+}
+```
+
+```json
+{
+  "action": "runCode",
+  "language": "javascript",
+  "code": "return false",
+  "exitCodes": [
+    1
+  ]
+}
+```
+
+```json
+{
+  "action": "runCode",
+  "language": "python",
+  "code": "print('Hello from Python')",
+  "workingDirectory": ".",
+  "exitCodes": [
+    0
+  ],
+  "output": "Hello from Python!",
+  "savePath": "python-output.txt",
+  "saveDirectory": "output",
+  "maxVariation": 10,
+  "overwrite": "byVariation"
+}
+```

docs/references/schemas/saveScreenshot.md

@@ -12,9 +12,12 @@ description | string |  Optional. Description of the step. |
 action | string |  Required. The action to perform. | 
 path | string |  Optional. File path of the PNG file, relative to `directory`. If not specified, the file name is the ID of the step. | 
 directory | string |  Optional. Directory of the PNG file. If the directory doesn't exist, creates the directory. | 
-maxVariation | number | Optional. Allowed variation in percentage of pixels between the new screenshot and the existing screenshot at `path`. If the difference between the new screenshot and the existing screenshot is greater than `maxVariation`, the step fails. If a screenshot doesn't exist at `path`, the system ignores this value. | `5`
+maxVariation | number |  Optional. Allowed variation in percentage of pixels between the new screenshot and the exisitng screenshot at `path`. If the difference between the new screenshot and the existing screenshot is greater than `maxVariation`, the step fails. If a screenshot doesn't exist at `path`, this value is ignored. | `5`
 overwrite | string |  Optional. If `true`, overwrites the existing screenshot at `path` if it exists.
 If `byVariation`, overwrites the existing screenshot at `path` if the difference between the new screenshot and the existing screenshot is greater than `maxVariation`.<br/><br/>Accepted values: `true`, `false`, `byVariation` | `false`
+crop | object |  Optional. Crops the screenshot. | 
+crop.selector | string |  Required. Selector of the element to crop the image to. | 
+crop.padding | One of<br/>-&nbsp;number<br/>-&nbsp;object |  Optional. undefined | 
 
 ## Examples
 
@@ -48,3 +51,43 @@ If `byVariation`, overwrites the existing screenshot at `path` if the difference
   "overwrite": "byVariation"
 }
 ```
+
+```json
+{
+  "action": "saveScreenshot",
+  "path": "results.png",
+  "directory": "static/images",
+  "crop": {
+    "selector": "#element"
+  }
+}
+```
+
+```json
+{
+  "action": "saveScreenshot",
+  "path": "results.png",
+  "directory": "static/images",
+  "crop": {
+    "selector": "#element",
+    "padding": 10
+  }
+}
+```
+
+```json
+{
+  "action": "saveScreenshot",
+  "path": "results.png",
+  "directory": "static/images",
+  "crop": {
+    "selector": "#element",
+    "padding": {
+      "top": 10,
+      "right": 20,
+      "bottom": 30,
+      "left": 40
+    }
+  }
+}
+```