Skip to navigation
Test your docsUI proceduresScreenshots

Annotate screenshots

Mark up an image as part of capturing it. Doc Detective composites annotations into the screenshot, so you can point at fields, number steps, and redact sensitive information in a single capture. New to capturing screenshots? Start with Capture screenshots.

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.
  • A page with the target elements you want to annotate.

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.

Annotate screenshots

The screenshot.annotations option marks up an image as part of capturing it. Doc Detective composites annotations into the image and never touches the page under test. An annotated screenshot therefore can’t disturb a running test or leak into a recording.

There are six annotation types:

  • outline: a box around the target.
  • arrow: an arrow pointing at the target.
  • badge: a small marker showing label, for numbered steps.
  • callout: a text box with a leader line, showing label.
  • blur: a blur over the target, to redact sensitive information.
  • text: a standalone text box, showing label.

Each annotation names one type, and the type’s value is its target. A target takes one of three forms. It can be a string, meaning a selector or display text, the same as crop. It can be an object, using the same element-finding fields as find. It can also be a position, either a named region like top-right or a { "x": …, "y": … } point. Shared options include label, position, style, and all. label is the text a badge, callout, or text shows. position sets where the annotation sits relative to its target. style holds per-annotation visual overrides, and all annotates every matching element instead of only the first.

An object target also takes timeout, the number of milliseconds to wait for its element. Annotations wait 5000 by default. Raise it for anything slower, such as { "outline": { "elementTestId": "dashboard", "timeout": 20000 } }.

This example numbers the fields of a sign-in form and redacts an email address, all in one capture:

{
  "description": "Number the form fields and redact the account email.",
  "screenshot": {
    "path": "./output/sign_in.png",
    "annotations": [
      { "badge": "#username", "label": "1" },
      { "badge": "#password", "label": "2" },
      { "callout": "#submit", "label": "Sends you a one-time code", "position": "right" },
      { "blur": { "selector": ".account-email" }, "all": true }
    ]
  }
}

To redact reliably, set all: true with an object target. A bare blur selector such as { "blur": ".account-email" } blurs only the first match, so any other matches stay readable in an image that looks redacted.

Theme every annotation at once

Set annotationDefaults to style all annotations consistently across a doc set. Set it on the config, a spec, or a test. A test’s theme overrides a spec’s, which overrides the config’s. An individual annotation’s style overrides all of them:

{
  "annotationDefaults": {
    "color": "#E11D48",
    "strokeWidth": 3,
    "fontFamily": "Inter, system-ui, sans-serif",
    "badge": { "background": "#E11D48", "color": "#FFFFFF" },
    "blur": { "intensity": 14 }
  }
}

Base properties apply to every type; a per-type block, such as badge or blur, overrides them for that type.

Because annotations change an image’s pixels, changing a theme or an annotation invalidates any existing reference image you compare against with maxVariation. Refresh the reference after changing annotations.

Annotations also work on native app surfaces. There the native element lookup limits targets to four fields and doesn’t accept all. See the reference for that path. To keep annotations up across steps and navigation so they appear in a recording, use the annotate action instead, covered in Narrate recordings. For the full annotation surface, see Annotations and the annotation-defaults schema.

Verify it works

  • An annotation whose target doesn’t resolve reports FAIL, because Doc Detective has nowhere to put the annotation. If the element is only slow rather than missing, raise its timeout instead of removing the annotation.

Troubleshooting

An annotation turns previously passing comparisons to WARNING

Cause: annotations change the image’s pixels, so an added or restyled annotation makes the new capture differ from a reference image captured without it.

Solution: refresh the reference image after you change annotations or the annotationDefaults theme. For how the comparison behaves, see Detect visual regressions in screenshots.

What’s next