specification | Doc Detective

Fields

Field	Type	Description	Default
$schema	string	Optional. JSON Schema for this object. Accepted values: `https://raw.githubusercontent.com/doc-detective/common/refs/heads/main/dist/schemas/spec_v3.schema.json`	—
specId	string	Optional. Unique identifier for the test specification.	—
description	string	Optional. Description of the test specification.	—
specPath	string	Optional. Path to the test specification.	—
contentPath	string	Optional. Path to the content that the specification is associated with.	—
if	one of: - string - array of string	Optional. A condition expression, or an array of expressions combined with logical AND.	—
runOn	array of object(context)	Optional. Contexts to run the test in. Overrides contexts defined at the config and spec levels.	—
openApi	array of unknown	Optional. No description provided.	—
autoScreenshot	boolean	Optional. If `true`, captures a screenshot after every step in this spec’s tests that runs in a browser. Overrides the config-level `autoScreenshot`; individual tests can override this value with their own `autoScreenshot`. When unset, defers to the config level.	—
autoRecord	boolean	Optional. If `true`, records a video of every browser context in this spec’s tests. Overrides the config-level `autoRecord`; individual tests can override this value with their own `autoRecord`. When unset, defers to the config level.	—
annotationDefaults	object(Annotation defaults)	Optional. Default visual theme for annotations in this spec’s tests. Overrides the config-level `annotationDefaults`; individual tests can override this value with their own `annotationDefaults`. When unset, defers to the config level.	—
durationMs	integer	ReadOnly. Total time this specification’s tests took, in milliseconds: the sum of the per-test durations. A sum rather than a wall-clock span, because this spec’s contexts share a concurrent pool with every other spec’s. Present only in test results. System-populated. Minimum: 0	—
tests	array of object(test)	Required. Tests to perform.	—

Examples

{
  "tests": [
    {
      "steps": [
        {
          "checkLink": {
            "url": "https://www.duckduckgo.com"
          }
        }
      ]
    }
  ]
}

{
  "specId": "Do all the things! - Spec",
  "runOn": [
    {
      "platforms": [
        "windows",
        "mac"
      ],
      "browsers": {
        "name": "firefox",
        "window": {},
        "viewport": {}
      }
    }
  ],
  "tests": [
    {
      "testId": "Do all the things! - Test",
      "description": "This test includes nearly every property across all actions.",
      "runOn": [
        {
          "platforms": "linux",
          "browsers": "firefox"
        }
      ],
      "steps": [
        {
          "loadVariables": ".env"
        },
        {
          "runShell": {
            "command": "echo",
            "args": [
              "$USER"
            ],
            "maxVariation": 0,
            "overwrite": "aboveVariation"
          },
          "variables": {}
        },
        {
          "checkLink": {
            "url": "https://www.duckduckgo.com"
          }
        },
        {
          "httpRequest": {
            "method": "post",
            "url": "https://reqres.in/api/users",
            "request": {
              "body": {
                "name": "morpheus",
                "job": "leader"
              }
            },
            "response": {
              "body": {
                "name": "morpheus",
                "job": "leader"
              }
            },
            "statusCodes": [
              200,
              201
            ],
            "maxVariation": 0,
            "overwrite": "aboveVariation"
          },
          "variables": {}
        },
        {
          "goTo": {
            "url": "https://www.duckduckgo.com"
          }
        },
        {
          "find": {
            "selector": "[title=Search]",
            "elementText": "Search",
            "timeout": 10000,
            "moveTo": true,
            "click": true,
            "type": {
              "keys": [
                "shorthair cat"
              ]
            }
          },
          "variables": {}
        },
        {
          "type": {
            "keys": [
              "$ENTER$"
            ]
          }
        },
        {
          "screenshot": {
            "maxVariation": 0,
            "overwrite": "aboveVariation"
          }
        }
      ],
      "detectSteps": true
    }
  ]
}

{
  "specId": "Make a request from an OpenAPI definition",
  "openApi": [
    {
      "descriptionPath": "https://www.acme.com/openapi.json",
      "server": "https://api.acme.com",
      "name": "Acme"
    }
  ],
  "tests": [
    {
      "steps": [
        {
          "httpRequest": {
            "openApi": {
              "operationId": "getUserById",
              "validateAgainstSchema": "both",
              "useExample": "none",
              "exampleKey": ""
            },
            "request": {
              "parameters": {
                "id": 123
              }
            },
            "response": {},
            "maxVariation": 0,
            "overwrite": "aboveVariation"
          },
          "variables": {}
        }
      ]
    }
  ]
}

{
  "annotationDefaults": {
    "color": "#E11D48",
    "strokeWidth": 3,
    "badge": {
      "background": "#E11D48",
      "color": "#FFFFFF"
    }
  },
  "tests": [
    {
      "steps": [
        {
          "screenshot": {
            "path": "a.png",
            "annotations": [
              {
                "outline": "#submit"
              }
            ]
          }
        }
      ]
    }
  ]
}