Skip to navigation
Schemas

annotation

A visual annotation drawn onto a screenshot or recording. Each annotation names exactly one type (outline, arrow, badge, callout, blur, or text), and the type’s value is the target it points at: an element (a selector/display-text string or a detailed find object) or a fixed position in the capture. id, track, transition, and duration describe behavior over time — they apply to recordings and are inert in still screenshots, so the same annotation means the same thing in both.

Referenced In

Fields

FieldTypeDescriptionDefault
outlineone of:
- string
- object(Target by element (detailed))
- object(Target by position)		Optional. Draw a box around the target.—
arrowone of:
- string
- object(Target by element (detailed))
- object(Target by position)		Optional. Point an arrow at the target.—
badgeone of:
- string
- object(Target by element (detailed))
- object(Target by position)		Optional. Mark the target with a small numbered or lettered marker. Set the marker’s characters with label.—
calloutone of:
- string
- object(Target by element (detailed))
- object(Target by position)		Optional. Label the target with a text box and a leader line. Set the text with label.—
blurone of:
- string
- object(Target by element (detailed))
- object(Target by position)		Optional. Obscure the target to redact sensitive information. Pair with all to redact every match rather than the first.—
textone of:
- string
- object(Target by element (detailed))
- object(Target by position)		Optional. Place a standalone text box. Set the text with label.—
labelstringOptional. Text to display. Required by badge, callout, and text; ignored by the other types.—
idstringOptional. Handle for this annotation, so a later annotate step can update or clear it. Only meaningful for annotations added by an annotate step; ignored on screenshot annotations, which live only for the capture.

Pattern: ^[A-Za-z0-9_-]+$		—
styleobject(Annotation style)Optional. Visual overrides for this annotation. Anything unset falls back to the resolved annotationDefaults theme (test, then spec, then config), then to the built-in theme.—
positionone of:
- string
- object(Annotation point)
- object(Annotation offset)		Optional. Where to place the annotation relative to its target. Accepts a named region, an absolute point, or an offset that nudges the default placement.—
trackbooleanOptional. If true, the annotation follows its element as the page scrolls or reflows. Applies to recordings; inert in still screenshots, which capture a single moment.—
transitionobject(Annotation transition)Optional. How the annotation enters and leaves. Applies to recordings; inert in still screenshots, which render the settled state.—
durationnumberOptional. Milliseconds to display the annotation before it clears itself. Omit to display it until an annotate step clears it. Applies to recordings; inert in still screenshots.

Minimum: 0		—
allbooleanOptional. If true, annotates every element matching the target instead of only the first. Most useful with blur, where redacting only the first match can leave sensitive content visible.—

Examples

{
  "outline": "#submit-button"
}
{
  "badge": "#expiry",
  "label": "2"
}
{
  "callout": {
    "elementTestId": "cvv-input"
  },
  "label": "Never stored — sent straight to the payment processor",
  "position": "right",
  "style": {
    "maxWidth": 240,
    "fontSize": 13
  }
}
{
  "arrow": {
    "elementAttribute": {
      "data-state": "invalid"
    }
  },
  "position": "bottom-left"
}
{
  "text": {
    "position": "top-right"
  },
  "label": "Demo environment — sample data",
  "style": {
    "background": "#0F172A",
    "color": "#FDE047",
    "padding": 8,
    "opacity": 0.9
  }
}
{
  "id": "redact-api-keys",
  "blur": {
    "elementAttribute": {
      "data-sensitive": true
    }
  },
  "all": true,
  "track": true,
  "style": {
    "intensity": 22
  },
  "transition": {
    "enter": "none"
  }
}
{
  "callout": {
    "elementTestId": "dashboard-loaded",
    "timeout": 15000
  },
  "label": "Your dashboard, once the first sync finishes"
}
{
  "id": "usage-highlight",
  "outline": {
    "elementClass": [
      "form-field",
      "/^billing-/"
    ]
  },
  "duration": 3500,
  "transition": {
    "enter": "draw",
    "exit": "fade",
    "durationMs": 400
  }
}