> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.doc-detective.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.doc-detective.com/_mcp/server.

# specification

> Reference for the `specification` schema.

## 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](/reference/schemas/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](/reference/schemas/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](/reference/schemas/test))                      | Required. [Tests](test) to perform.                                                                                                                                                                                                                                                     | —       |

## Examples

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

```json
{
  "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
    }
  ]
}
```

```json
{
  "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": {}
        }
      ]
    }
  ]
}
```

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