Skip to content

Commit 3128294

Browse files
authored
Merge pull request #344 from argos-ci/greg/arg-460-create-an-automatic-mode-for-snapshots
feat(vitest): automatic naming, test metadata, shard detection & `snapshots` output dir
2 parents 686b6fa + 69db44d commit 3128294

19 files changed

Lines changed: 819 additions & 71 deletions

‎packages/vitest/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,4 @@
1+
/snapshots/
12
/screenshots/
3+
/.vitest-attachments/
4+
/e2e/__screenshots__/

‎packages/vitest/README.md‎

Lines changed: 30 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -80,13 +80,36 @@ test("Button", async () => {
8080
});
8181
```
8282

83+
### Automatic naming
84+
85+
The name is optional. When omitted, Argos derives one from the current test,
86+
mimicking [Vitest snapshots](https://vitest.dev/guide/snapshot). Several unnamed
87+
captures in the same test get an incrementing counter so they stay unique:
88+
89+
```ts
90+
test("Button", async () => {
91+
render(<Button>Click me</Button>);
92+
await argosScreenshot(); // -> "src/Button.test.tsx > Button 1"
93+
await argosScreenshot(); // -> "src/Button.test.tsx > Button 2"
94+
});
95+
```
96+
97+
Unlike Vitest — which keeps a per-file `.snap`, so its keys only need to be
98+
unique within a file — Argos names are **global** across the build. The
99+
generated name therefore includes the test file path, so two tests with the same
100+
title in different files never collide.
101+
83102
## Snapshots
84103

85104
`argosSnapshot` captures a snapshot of any value — not just a screenshot — and
86105
uploads it to Argos to diff across builds, mimicking
87106
[Vitest snapshots](https://vitest.dev/guide/snapshot). Unlike `argosScreenshot`,
88107
it does not need a browser and works in **both** browser and Node tests.
89108

109+
The value comes first; the name is optional. Omit it to auto-name the snapshot
110+
from the current test (like screenshots above), or pass `options.name` to set it
111+
explicitly:
112+
90113
```ts
91114
import { test } from "vitest";
92115
import { argosSnapshot } from "@argos-ci/vitest";
@@ -95,22 +118,25 @@ test("API response", async () => {
95118
const user = await fetchUser();
96119
// Objects are serialized with `@vitest/pretty-format`, strings are written
97120
// verbatim.
98-
await argosSnapshot("user", user);
121+
await argosSnapshot(user); // -> "src/user.test.ts > API response 1"
122+
await argosSnapshot(user, { name: "user" }); // explicit name
99123
});
100124
```
101125

102126
Use the `extension` option to control how Argos renders and diffs the snapshot,
103127
and `tag` to attach tags:
104128

105129
```ts
106-
await argosSnapshot("config", JSON.stringify(config, null, 2), {
130+
await argosSnapshot(JSON.stringify(config, null, 2), {
131+
name: "config",
107132
extension: ".json",
108133
tag: "config",
109134
});
110135
```
111136

112-
Snapshots are written to the same folder as screenshots and uploaded by the
113-
reporter when `uploadToArgos` is enabled.
137+
Screenshots and snapshots are both written to the `./snapshots` directory by
138+
default (configurable via the plugin `root` option) and uploaded by the reporter
139+
when `uploadToArgos` is enabled.
114140

115141
## Links
116142

‎packages/vitest/e2e/screenshot.test.ts‎

Lines changed: 87 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -54,10 +54,56 @@ test("captures a rendered element with the Argos Vitest SDK metadata", async ()
5454
expect(attachments.length).toBe(2);
5555

5656
// The whole point of the package: the screenshot is attributed to this SDK
57-
// and to the Playwright provider (proves setMetadataConfig propagated).
57+
// and to Vitest as the automation library (proves setMetadataConfig
58+
// propagated).
5859
const metadata = await readMetadata(attachments);
5960
expect(metadata.sdk.name).toBe("@argos-ci/vitest");
60-
expect(metadata.automationLibrary.name).toBe("@vitest/browser-playwright");
61+
expect(metadata.automationLibrary.name).toBe("vitest");
62+
});
63+
64+
test("attaches the Vitest test metadata to the screenshot", async () => {
65+
mount(`<div style="padding:20px">Metadata</div>`);
66+
const attachments = await argosScreenshot("with-metadata");
67+
const metadata = await readMetadata(attachments);
68+
69+
// Test metadata (injected from the Vitest test context, since Playwright's
70+
// own testInfo is absent in a Vitest run).
71+
expect(metadata.test.id).toBeTruthy();
72+
expect(metadata.test.title).toBe(
73+
"attaches the Vitest test metadata to the screenshot",
74+
);
75+
expect(metadata.test.titlePath).toEqual([
76+
"e2e/screenshot.test.ts",
77+
"attaches the Vitest test metadata to the screenshot",
78+
]);
79+
// `location.file` is resolved relative to the git repository on the Node side.
80+
expect(metadata.test.location.file).toContain(
81+
"packages/vitest/e2e/screenshot.test.ts",
82+
);
83+
// `includeTaskLocation` (enabled by the plugin) provides real line/column.
84+
expect(metadata.test.location.line).toBeGreaterThan(0);
85+
expect(metadata.test.location.column).toBeGreaterThan(0);
86+
87+
// Browser-derived metadata comes for free through the Playwright SDK.
88+
expect(metadata.browser.name).toBe("chromium");
89+
expect(typeof metadata.url).toBe("string");
90+
expect(["light", "dark"]).toContain(metadata.colorScheme);
91+
expect(metadata.mediaType).toBe("screen");
92+
});
93+
94+
test("auto-names a screenshot from the current test", async () => {
95+
mount(
96+
`<div style="padding:40px;background:#22c55e;color:#fff;font:700 32px sans-serif;">Auto</div>`,
97+
);
98+
// No name: it is derived from the current test + a per-test counter, so the
99+
// file lands under the test title with a ` 1` suffix.
100+
const attachments = await argosScreenshot();
101+
expect(attachments.length).toBe(2);
102+
103+
const screenshot = attachments.find((a) => a.path.endsWith(".png"));
104+
expect(screenshot).toBeDefined();
105+
expect(screenshot!.path).toContain("auto-names a screenshot");
106+
expect(screenshot!.path).toContain(" 1.png");
61107
});
62108

63109
test("captures a specific element via a selector", async () => {
@@ -115,15 +161,20 @@ test("grows the iframe to capture content wider than the viewport", async () =>
115161
test("writes a value snapshot that the reporter can upload", async () => {
116162
// `argosSnapshot` works without a browser, but here we exercise the browser
117163
// RPC path: the value is serialized in the browser, written on the node side.
118-
const attachments = await argosSnapshot("payload", {
119-
id: 1,
120-
name: "Argos",
121-
tags: ["a", "b"],
122-
});
164+
const attachments = await argosSnapshot(
165+
{
166+
id: 1,
167+
name: "Argos",
168+
tags: ["a", "b"],
169+
},
170+
{ name: "payload" },
171+
);
123172
// The snapshot file + its metadata attachment.
124173
expect(attachments.length).toBe(2);
125174

126-
const snapshot = attachments.find((a) => a.path.endsWith(".snapshot.txt"));
175+
const snapshot = attachments.find((a) =>
176+
a.path.endsWith("payload.snapshot.txt"),
177+
);
127178
expect(snapshot).toBeDefined();
128179
// The value is serialized with pretty-format, ready for Argos to diff.
129180
const content = await server.commands.readFile(snapshot!.path);
@@ -135,8 +186,35 @@ test("writes a value snapshot that the reporter can upload", async () => {
135186
expect(parsed.sdk.name).toBe("@argos-ci/vitest");
136187
});
137188

189+
test("attaches the Vitest test metadata to the snapshot", async () => {
190+
const attachments = await argosSnapshot(
191+
{ hello: "world" },
192+
{ name: "snapshot-metadata" },
193+
);
194+
const metadata = attachments.find((a) => a.path.endsWith(".argos.json"));
195+
expect(metadata).toBeDefined();
196+
const parsed = JSON.parse(await server.commands.readFile(metadata!.path));
197+
198+
// Snapshots have no browser, so Vitest is the automation library, but they
199+
// still carry the test metadata.
200+
expect(parsed.automationLibrary.name).toBe("vitest");
201+
expect(parsed.test.id).toBeTruthy();
202+
expect(parsed.test.title).toBe(
203+
"attaches the Vitest test metadata to the snapshot",
204+
);
205+
expect(parsed.test.titlePath).toEqual([
206+
"e2e/screenshot.test.ts",
207+
"attaches the Vitest test metadata to the snapshot",
208+
]);
209+
// `location.file` is resolved relative to the git repository on the Node side.
210+
expect(parsed.test.location.file).toContain(
211+
"packages/vitest/e2e/screenshot.test.ts",
212+
);
213+
});
214+
138215
test("writes a snapshot with a custom extension", async () => {
139-
const attachments = await argosSnapshot("config", '{"enabled":true}', {
216+
const attachments = await argosSnapshot('{"enabled":true}', {
217+
name: "config",
140218
extension: ".json",
141219
});
142220
const snapshot = attachments.find((a) => a.path.endsWith(".snapshot.json"));
Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
import { expect, it } from "vitest";
2+
import { TestRunner } from "vitest";
3+
import { resolveAutoName } from "./auto-name";
4+
5+
it("returns an explicit name verbatim", async () => {
6+
await expect(resolveAutoName("button")).resolves.toBe("button");
7+
});
8+
9+
it("generates a name from the current test with a per-test counter", async () => {
10+
const testName = TestRunner.getCurrentTest()?.fullName;
11+
expect(testName).toBeTruthy();
12+
13+
// Each auto-named capture in the same test gets an incrementing counter,
14+
// mimicking Vitest's `${testName} ${count}` snapshot naming.
15+
await expect(resolveAutoName()).resolves.toBe(`${testName} 1`);
16+
await expect(resolveAutoName()).resolves.toBe(`${testName} 2`);
17+
});
18+
19+
it("restarts the counter for each test", async () => {
20+
const testName = TestRunner.getCurrentTest()?.fullName;
21+
// A different test task, so the counter starts over at 1.
22+
await expect(resolveAutoName()).resolves.toBe(`${testName} 1`);
23+
});
24+
25+
it("includes the test file path so names are unique across files", async () => {
26+
const file = TestRunner.getCurrentTest()?.file?.name;
27+
expect(file).toBe("src/auto-name.test.ts");
28+
// Argos names are global across the build (unlike Vitest's per-file `.snap`),
29+
// so the file path is part of the auto-generated name.
30+
await expect(resolveAutoName()).resolves.toContain(`${file} > `);
31+
});
32+
33+
// A test title long enough that the auto-generated name would overflow the
34+
// filesystem's 255-char limit once extensions are appended.
35+
it(`truncates names that would overflow the filename limit ${"x".repeat(300)}`, async () => {
36+
const test = TestRunner.getCurrentTest();
37+
const reservedLength = 25;
38+
const name = await resolveAutoName(undefined, { reservedLength });
39+
40+
// The whole filename (name + reserved suffix) fits within the limit.
41+
expect(name.length).toBeLessThanOrEqual(255 - reservedLength);
42+
// The unique test id is kept so truncated names from different tests never
43+
// collide, and the counter is preserved at the end.
44+
expect(name).toContain(test!.id);
45+
expect(name.endsWith(" 1")).toBe(true);
46+
});

‎packages/vitest/src/auto-name.ts‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
import { getCurrentTest } from "./test-context";
2+
3+
/**
4+
* Maximum length of a single filename component on common filesystems (ext4,
5+
* APFS, NTFS all cap at 255 bytes/chars).
6+
*/
7+
const MAX_FILENAME_LENGTH = 255;
8+
9+
/**
10+
* Per-test counter used to generate unique automatic names, keyed by the
11+
* current test task. A `WeakMap` lets the entries be garbage-collected with the
12+
* test tasks, so nothing leaks across files or runs.
13+
*/
14+
const counters = new WeakMap<object, number>();
15+
16+
/**
17+
* Truncate `text` to `length` characters, replacing the tail with an ellipsis.
18+
*/
19+
function truncate(text: string, length: number): string {
20+
if (text.length <= length) {
21+
return text;
22+
}
23+
return `${text.slice(0, Math.max(0, length - 1))}…`;
24+
}
25+
26+
/**
27+
* Resolve the name of a screenshot or snapshot.
28+
*
29+
* When an explicit `name` is provided, it is returned as-is. Otherwise a name
30+
* is generated automatically from the current Vitest test, mimicking
31+
* {@link https://vitest.dev/guide/snapshot Vitest's own snapshot naming}:
32+
* `` `${test.fullName} ${count}` ``, where `count` increments per test so
33+
* several auto-named captures in the same test stay unique.
34+
*
35+
* Unlike Vitest — which stores snapshots in a per-file `.snap`, so its keys only
36+
* need to be unique within a file — Argos names are global across the whole
37+
* build. The name therefore includes the test file path so two tests with the
38+
* same title in different files do not collide. Vitest's `fullName` already
39+
* starts with the file path; we prepend it defensively in case that changes.
40+
*
41+
* The name is kept short enough that the final filename — including the
42+
* extension(s) the caller appends (e.g. `.snapshot.txt`, ` vw-800.png`) and the
43+
* `.argos.json` metadata sidecar — fits within {@link MAX_FILENAME_LENGTH}.
44+
* Mirroring the Playwright SDK, when the readable name would overflow we fall
45+
* back to the test id (short and unique) so truncated names never collide, then
46+
* keep as much of the readable name as fits.
47+
*
48+
* Must only be called once we know we are running inside Vitest (the caller
49+
* checks `checkIsVitestEnv` first).
50+
*
51+
* @param name - Explicit name, or `undefined`/empty to auto-generate one.
52+
* @param options.reservedLength - Number of characters the caller appends after
53+
* the returned name when building the filename (extensions + metadata
54+
* suffix), reserved so the whole filename stays within the limit.
55+
* @returns The resolved, non-empty name.
56+
*/
57+
export async function resolveAutoName(
58+
name?: string,
59+
options: { reservedLength?: number } = {},
60+
): Promise<string> {
61+
if (name) {
62+
return name;
63+
}
64+
65+
const test = await getCurrentTest();
66+
if (!test) {
67+
throw new Error(
68+
"Argos could not generate an automatic name because it is not running " +
69+
"inside a Vitest test. Pass an explicit `name` argument.",
70+
);
71+
}
72+
73+
const count = (counters.get(test) ?? 0) + 1;
74+
counters.set(test, count);
75+
76+
const file = test.file?.name;
77+
const fullName =
78+
file && !test.fullName.startsWith(file)
79+
? `${file} > ${test.fullName}`
80+
: test.fullName;
81+
82+
// Reserve room for the trailing counter and the caller's suffix, then keep
83+
// the whole name within the filesystem limit. The counter always survives
84+
// (appended after truncation) so per-test captures stay unique; when the
85+
// readable name overflows, the unique test id is prepended so truncated names
86+
// from different tests never collide.
87+
const suffix = ` ${count}`;
88+
const maxBase =
89+
MAX_FILENAME_LENGTH - (options.reservedLength ?? 0) - suffix.length;
90+
const base =
91+
fullName.length > maxBase
92+
? truncate(`${test.id} ${fullName}`, maxBase)
93+
: fullName;
94+
return `${base}${suffix}`;
95+
}

‎packages/vitest/src/command.test.ts‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -86,9 +86,7 @@ describe("createArgosScreenshotCommand", () => {
8686
name: "@argos-ci/vitest",
8787
version: "0.0.0-test",
8888
});
89-
expect(metadata.playwrightLibraries).toContain(
90-
"@vitest/browser-playwright",
91-
);
89+
expect(metadata.playwrightLibraries).toContain("vitest");
9290
});
9391

9492
it("takes one screenshot per viewport with viewport-suffixed names", async () => {

‎packages/vitest/src/command.ts‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ import type {
1010
VitestScreenshotOptions,
1111
} from "./options";
1212
import { resetTesterScale, setIframeViewportSize } from "./iframe";
13+
import type { TestMetadata } from "./metadata";
1314
import { screenshotFrame } from "./screenshot";
1415
import { getArgosVitestVersion } from "./version";
1516

@@ -20,6 +21,7 @@ import { getArgosVitestVersion } from "./version";
2021
export type ArgosScreenshotCommandArgs = [
2122
name: string,
2223
options?: VitestScreenshotOptions,
24+
test?: TestMetadata,
2325
];
2426

2527
/**
@@ -33,7 +35,7 @@ export type ArgosScreenshotCommandArgs = [
3335
export const createArgosScreenshotCommand = (
3436
pluginOptions: ArgosVitestPluginOptions = {},
3537
): BrowserCommand<ArgosScreenshotCommandArgs> => {
36-
return async (ctx, name, options) => {
38+
return async (ctx, name, options, test) => {
3739
if (!name) {
3840
throw new Error("The `name` argument is required.");
3941
}
@@ -48,8 +50,15 @@ export const createArgosScreenshotCommand = (
4850
const setMetadata = (viewport?: ViewportSize) => {
4951
DO_NOT_USE_setMetadataConfig({
5052
sdk: { name: "@argos-ci/vitest", version },
51-
playwrightLibraries: ["@vitest/browser-playwright"],
53+
// Report Vitest as the automation library (not the underlying
54+
// `@vitest/browser-playwright` provider), so screenshots match the
55+
// `vitest` automation library used by `argosSnapshot`.
56+
playwrightLibraries: ["vitest"],
5257
viewport,
58+
// Injected so the Playwright SDK attaches the Vitest test metadata
59+
// (Playwright's own `testInfo` is absent here). It resolves
60+
// `location.file` relative to the git repository.
61+
test,
5362
});
5463
};
5564

0 commit comments

Comments
 (0)