Skip to content

Commit 1272632

Browse files
gregbergegregberge
authored
Merge pull request #157 from argos-ci/document-screenshot-metadata
feat: document screenshot metadata
2 parents 71cfa41 + e40b41b commit 1272632

1 file changed

Lines changed: 177 additions & 0 deletions

File tree

‎docs/guides/screenshot-metadata.mdx‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
---
2+
slug: /screenshot-metadata
3+
title: Screenshot Metadata
4+
---
5+
6+
# Adding Screenshot Metadata
7+
8+
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.
9+
10+
## How It Works
11+
12+
For each screenshot file, you can create a metadata file with the same name and the `.argos.json` suffix:
13+
14+
```
15+
myscreenshot.png
16+
myscreenshot.png.argos.json
17+
```
18+
19+
The `.argos.json` file must be valid JSON following the Argos metadata schema.
20+
21+
## Schema Autocomplete
22+
23+
To enable autocompletion, type checking, and schema validation in editors like VS Code, you can add a `$schema` field at the top of your `.argos.json` file:
24+
25+
```json
26+
{
27+
"$schema": "https://api.argos-ci.com/v2/screenshot-metadata.json"
28+
}
29+
```
30+
31+
## Top-Level Fields
32+
33+
| Field | Type | Description |
34+
| ------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------- |
35+
| `$schema` | `string?` | Ignored. Can be set to get completions, validations and documentation in some editors. |
36+
| `url` | `string?` | The URL of the page that was screenshotted. |
37+
| `previewUrl` | `string?` | A URL to an accessible preview of the screenshot. |
38+
| `viewport` | [Viewport](#viewport)? | The viewport dimensions when the screenshot was taken. |
39+
| `colorScheme` | `"light" \| "dark" ` | The color scheme when the screenshot was taken. |
40+
| `mediaType` | `"screen" \| "print" ` | The media type when the screenshot was taken. |
41+
| `test` | [Test](#test)? | Information about the test that generated the screenshot. |
42+
| `browser` | [Browser](#browser)? | The browser that generated the screenshot. |
43+
| `automationLibrary` | [Automation Library](#automation-library) | The automation library that generated the screenshot. _(Required)_ |
44+
| `sdk` | [SDK](#sdk) | The Argos SDK that generated the screenshot. _(Required)_ |
45+
46+
## Viewport
47+
48+
```json
49+
{
50+
"width": 1280,
51+
"height": 720
52+
}
53+
```
54+
55+
- `width` (number): Width of the viewport.
56+
- `height` (number): Height of the viewport.
57+
58+
## Test
59+
60+
```json
61+
{
62+
"id": "test-id",
63+
"title": "should render homepage correctly",
64+
"titlePath": ["E2E", "Homepage"],
65+
"retries": 1,
66+
"retry": 0,
67+
"repeat": 0,
68+
"location": { "file": "tests/homepage.spec.ts", "line": 42, "column": 3 },
69+
"annotations": [
70+
{
71+
"type": "slow",
72+
"description": "Known performance issue",
73+
"location": { "file": "tests/homepage.spec.ts", "line": 40, "column": 1 }
74+
}
75+
]
76+
}
77+
```
78+
79+
- `id` (string?): The unique identifier of the test.
80+
- `title` (string): The title of the test.
81+
- `titlePath` (string[]): The hierarchy of titles leading to the test.
82+
- `retries` (number?): Number of retries for the test.
83+
- `retry` (number?): The current retry count.
84+
- `repeat` (number?): The repeat count for the test.
85+
- `location` ([Location](#location)?): Where the test is located in the source code.
86+
- `annotations` ([Test Annotation](#test-annotation)[]?): Extra information about the test.
87+
88+
## Location
89+
90+
```json
91+
{
92+
"file": "src/components/Button.tsx",
93+
"line": 10,
94+
"column": 5
95+
}
96+
```
97+
98+
- `file` (string): The source file.
99+
- `line` (number): The line number.
100+
- `column` (number): The column number.
101+
102+
## Test Annotation
103+
104+
```json
105+
{
106+
"type": "skip",
107+
"description": "Flaky test",
108+
"location": { "file": "tests/button.spec.ts", "line": 12, "column": 1 }
109+
}
110+
```
111+
112+
- `type` (string): Type of annotation.
113+
- `description` (string?): Optional explanation.
114+
- `location` ([Location](#location)?): Where the annotation is located in the source code.
115+
116+
## Browser
117+
118+
```json
119+
{
120+
"name": "chromium",
121+
"version": "112.0.0"
122+
}
123+
```
124+
125+
- `name` (string): Browser name.
126+
- `version` (string): Browser version.
127+
128+
## Automation Library
129+
130+
```json
131+
{
132+
"name": "playwright",
133+
"version": "1.45.0"
134+
}
135+
```
136+
137+
- `name` (string): The name of the automation library (e.g. `playwright`, `cypress`).
138+
- `version` (string): The version of the automation library.
139+
140+
## SDK
141+
142+
```json
143+
{
144+
"name": "@argos-ci/playwright",
145+
"version": "2.0.0"
146+
}
147+
```
148+
149+
- `name` (string): The name of the Argos SDK.
150+
- `version` (string): The version of the Argos SDK.
151+
152+
## Complete Example
153+
154+
Here’s a full example of `myscreenshot.png.argos.json`:
155+
156+
```json
157+
{
158+
"url": "https://example.com/home",
159+
"viewport": { "width": 1280, "height": 720 },
160+
"colorScheme": "light",
161+
"mediaType": "screen",
162+
"test": {
163+
"title": "renders homepage correctly",
164+
"titlePath": ["E2E", "Homepage"],
165+
"location": { "file": "tests/homepage.spec.ts", "line": 42, "column": 3 }
166+
},
167+
"browser": { "name": "chromium", "version": "112.0.0" },
168+
"automationLibrary": { "name": "playwright", "version": "1.45.0" },
169+
"sdk": { "name": "@argos-ci/playwright", "version": "2.0.0" }
170+
}
171+
```
172+
173+
## Notes
174+
175+
- Fields marked as **required** must be included.
176+
- Unknown fields are ignored.
177+
- Each screenshot can have its own metadata file.

0 commit comments

Comments
 (0)