Skip to navigation
Test your docsUI proceduresScreenshots

Capture screenshots

Doc Detective can capture a screenshot at any point in a test. This guide is the entry point to the Screenshots section. It covers a single capture: the full viewport, a cropped element, or an element with padding. The section’s other guides cover three related capabilities. Detect visual regressions compares a capture against a reference image. Capture screenshots automatically fires after every step. Annotate screenshots marks up an image. Look up every field in the screenshot action reference and the generated screenshot schema. Unlike recording, screenshots capture fine in a headless or CI context.

Before you begin

Make sure you have the following:

  • Doc Detective installed.
  • A page or site to capture. The examples below capture a local page.
  • A directory where you can create a .spec.json file.

The steps in this guide work the same in every authoring style. Write them in a standalone .spec.json, inline in a doc source file, or let Doc Detective detect them from prose.

Capture a screenshot

The screenshot action takes three shapes, from simplest to most controlled.

Set screenshot: true to capture the full viewport with default settings:

capture.spec.json
{
  "tests": [
    {
      "steps": [
        {
          "description": "Capture the full viewport.",
          "screenshot": true
        }
      ]
    }
  ]
}

To choose where the image lands, pass a file path as a string:

{
  "description": "Save the capture to a specific file.",
  "screenshot": "./output/login.png"
}

By default (overwrite: "aboveVariation"), a target path that already holds a file gets compared against the new capture. Doc Detective replaces the file only when the two differ by more than maxVariation, which defaults to 5%. Otherwise it leaves the existing file in place. The Detect visual regressions section covers this behavior in full. Set "overwrite": "true" to always replace the file. Set "overwrite": "false" to keep the existing file and skip the capture, which reports SKIPPED.

For more control, use the object form. Set crop to a CSS selector to capture only that element:

{
  "description": "Capture only the login form.",
  "screenshot": {
    "path": "./output/login.png",
    "crop": "#login-form"
  }
}

crop accepts the same selector grammar as find, meaning a CSS or XPath selector. To disambiguate a selector by its visible text or add breathing room, use the object form of crop:

{
  "description": "Capture the Submit button with padding.",
  "screenshot": {
    "path": "./output/submit.png",
    "crop": {
      "elementText": "Submit",
      "padding": 10
    }
  }
}

padding accepts a single number for all four sides, or an object { "top": …, "right": …, "bottom": …, "left": … } to pad each side independently. For the full list of fields, see the screenshot action reference and the generated screenshot schema.

Verify it works

  • A step that captured an image reports PASS.
  • When the target path already holds a file and you set "overwrite": "false", the step keeps the existing file and reports SKIPPED.

Captures land in the run’s output directory and the per-run artifact tree. To see where they land and how to consume them in CI, see Reporters and artifacts.

What’s next