Screenshot metadata

Attach metadata to screenshots with a companion JSON file to add context on the Argos build page.

Enrich your screenshots in Argos with metadata by adding a companion JSON file. This metadata appears on the build page and helps contextualize how and why a screenshot was generated.

How it works

For each screenshot file, create a metadata file with the same name and the .argos.json suffix:

myscreenshot.png
myscreenshot.png.argos.json

The .argos.json file must be valid JSON following the Argos metadata schema.

If you use an official Argos SDK like @argos-ci/playwright, @argos-ci/cypress, @argos-ci/puppeteer, or @argos-ci/storybook, the SDK generates and uploads this metadata for you. If you don't use an SDK, generate the metadata yourself and upload it with @argos-ci/cli or @argos-ci/core.

Schema autocomplete

To enable autocompletion, type checking, and schema validation in editors like VS Code, add a $schema field at the top of your .argos.json file:

{
  "$schema": "https://api.argos-ci.com/v2/screenshot-metadata.json"
}

Top-level fields

Field	Type	Description
$schema	string?	Ignored. Can be set to get completions, validations, and documentation in some editors.
url	string?	The URL of the page that was screenshotted.
previewUrl	string?	A URL to an accessible preview of the screenshot.
viewport	Viewport?	The viewport dimensions when the screenshot was taken.
colorScheme	"light" | "dark"	The color scheme when the screenshot was taken.
mediaType	"screen" | "print"	The media type when the screenshot was taken.
test	Test?	Information about the test that generated the screenshot.
browser	Browser?	The browser that generated the screenshot.
automationLibrary	Automation library	The automation library that generated the screenshot. (Required)
sdk	SDK	The Argos SDK that generated the screenshot. (Required)
story	Story?	Storybook story metadata.
tags	string[]?	Custom tags to categorize the screenshot.
transient	Transient?	Upload-time instructions, removed from the stored metadata.

Viewport

{
  "width": 1280,
  "height": 720
}

• width (number): Width of the viewport.
• height (number): Height of the viewport.

Test

{
  "id": "test-id",
  "title": "should render homepage correctly",
  "titlePath": ["E2E", "Homepage"],
  "retries": 1,
  "retry": 0,
  "repeat": 0,
  "location": { "file": "tests/homepage.spec.ts", "line": 42, "column": 3 },
  "tags": ["@slow", "@regression"],
  "annotations": [
    {
      "type": "slow",
      "description": "Known performance issue",
      "location": { "file": "tests/homepage.spec.ts", "line": 40, "column": 1 }
    }
  ]
}

• id (string?): The unique identifier of the test.
• title (string): The title of the test.
• titlePath (string[]): The hierarchy of titles leading to the test.
• retries (number?): Number of retries for the test.
• retry (number?): The current retry count.
• repeat (number?): The repeat count for the test.
• location (Location?): Where the test is located in the source code.
• tags (string[]?): Tags associated with the test (e.g. Playwright's test tags).
• annotations (Test annotation[]?): Extra information about the test.

Location

{
  "file": "src/components/Button.tsx",
  "line": 10,
  "column": 5
}

• file (string): The source file.
• line (number): The line number.
• column (number): The column number.

Test annotation

{
  "type": "skip",
  "description": "Flaky test",
  "location": { "file": "tests/button.spec.ts", "line": 12, "column": 1 }
}

• type (string): Type of annotation.
• description (string?): Optional explanation.
• location (Location?): Where the annotation is located in the source code.

Browser

{
  "name": "chromium",
  "version": "112.0.0"
}

• name (string): Browser name.
• version (string): Browser version.

Automation library

{
  "name": "playwright",
  "version": "1.45.0"
}

• name (string): The name of the automation library (e.g. playwright, cypress).
• version (string): The version of the automation library.

SDK

{
  "name": "@argos-ci/playwright",
  "version": "2.0.0"
}

• name (string): The name of the Argos SDK.
• version (string): The version of the Argos SDK.

Story

Storybook story metadata, set by the Argos Storybook SDK.

{
  "id": "button--primary",
  "tags": ["autodocs"],
  "mode": "dark",
  "play": true
}

• id (string): Unique ID of the story.
• tags (string[]?): Tags attached to the story.
• mode (string?): The story mode used for the capture.
• play (boolean?): True if the story has a play function.

Transient

Upload-time instructions consumed by the Argos CLI and SDKs. Unlike the other fields, transient is not stored with the screenshot — the uploader reads it, applies it, and removes it from the metadata.

{
  "transient": {
    "threshold": 0.8,
    "baseName": ["home-variant-b.png", "home.png"],
    "parentName": "folder/my-screenshot.png"
  }
}

• threshold (number?): Sensitivity threshold for this screenshot's comparison, between 0 and 1.
• baseName (string | string[]?): Name(s) used to find the comparison baseline, instead of the screenshot's own name. An array is tried in order and the first name found in the baseline wins, which lets a new screenshot fall back to an existing one. More on fallback baselines.
• parentName (string?): Name of the parent snapshot — used to attach a file to another snapshot, for example an ARIA snapshot to its screenshot.

Complete example

Here's a full example of myscreenshot.png.argos.json:

{
  "url": "https://example.com/home",
  "viewport": { "width": 1280, "height": 720 },
  "colorScheme": "light",
  "mediaType": "screen",
  "tags": ["homepage", "desktop"],
  "test": {
    "title": "renders homepage correctly",
    "titlePath": ["E2E", "Homepage"],
    "tags": ["@regression"],
    "location": { "file": "tests/homepage.spec.ts", "line": 42, "column": 3 }
  },
  "browser": { "name": "chromium", "version": "112.0.0" },
  "automationLibrary": { "name": "playwright", "version": "1.45.0" },
  "sdk": { "name": "@argos-ci/playwright", "version": "2.0.0" }
}

Notes

• Fields marked as required must be included.
• Unknown fields are ignored.
• Each screenshot can have its own metadata file.