![\"Argos\"](\"https://raw.githubusercontent.com/argos-ci/argos/main/resources/logos/github-readme-logo-dark.png\"){kind=logo}
\n \n \n \n
The open source visual testing platform for AI-native engineering teams.
\n\n# Official Argos Vitest integration\n\n[](https://www.npmjs.com/package/@argos-ci/vitest)\n[](https://www.npmjs.com/package/@argos-ci/vitest)\n[](https://www.npmjs.com/package/@argos-ci/vitest)\n\nCapture Argos screenshots directly from your [Vitest browser tests](https://vitest.dev/guide/browser/).\n\nVisit the [Vitest SDK documentation](https://argos-ci.com/docs/reference/vitest) for guides, API and more.\n\n## Installation\n\nInstall the package:\n\n```sh\nnpm install --save-dev @argos-ci/vitest\n```\n\n`argosSnapshot` runs in any Vitest test — browser or Node — and needs nothing else.\n\nTo capture screenshots with `argosScreenshot`, run your tests in\n[Vitest browser mode](https://vitest.dev/guide/browser/) with the\n[Playwright provider](https://vitest.dev/guide/browser/playwright) and install the\nfollowing peer dependencies:\n\n```sh\nnpm install --save-dev vitest @vitest/browser @vitest/browser-playwright playwright\n```\n\n## Usage\n\nRegister the plugin in your Vitest config:\n\n```ts\n// vitest.config.ts\nimport { defineConfig } from \"vitest/config\";\nimport { playwright } from \"@vitest/browser-playwright\";\nimport { argosVitestPlugin } from \"@argos-ci/vitest/plugin\";\n\nexport default defineConfig({\n plugins: [\n argosVitestPlugin({\n // Upload the screenshots to Argos at the end of the run.\n uploadToArgos: process.env.CI === \"true\",\n }),\n ],\n test: {\n browser: {\n enabled: true,\n headless: true,\n provider: playwright(),\n instances: [{ browser: \"chromium\" }],\n },\n },\n});\n```\n\nThen take screenshots from your browser tests:\n\n```ts\nimport { test } from \"vitest\";\nimport { render } from \"vitest-browser-react\";\nimport { argosScreenshot } from \"@argos-ci/vitest\";\nimport { Button } from \"./Button\";\n\ntest(\"Button\", async () => {\n render();\n await argosScreenshot(\"button\");\n});\n```\n\n### Automatic naming\n\nThe name is optional. When omitted, Argos derives one from the current test,\nmimicking [Vitest snapshots](https://vitest.dev/guide/snapshot). Several unnamed\ncaptures in the same test get an incrementing counter so they stay unique:\n\n```ts\ntest(\"Button\", async () => {\n render();\n await argosScreenshot(); // -> \"src/Button.test.tsx > Button 1\"\n await argosScreenshot(); // -> \"src/Button.test.tsx > Button 2\"\n});\n```\n\nUnlike Vitest — which keeps a per-file `.snap`, so its keys only need to be\nunique within a file — Argos names are **global** across the build. The\ngenerated name therefore includes the test file path, so two tests with the same\ntitle in different files never collide.\n\n## Snapshots\n\n`argosSnapshot` captures a snapshot of any value — not just a screenshot — and\nuploads it to Argos to diff across builds, mimicking\n[Vitest snapshots](https://vitest.dev/guide/snapshot). Unlike `argosScreenshot`,\nit does not need a browser and works in **both** browser and Node tests.\n\nThe value comes first; the name is optional. Omit it to auto-name the snapshot\nfrom the current test (like screenshots above), or pass `options.name` to set it\nexplicitly:\n\n```ts\nimport { test } from \"vitest\";\nimport { argosSnapshot } from \"@argos-ci/vitest\";\n\ntest(\"API response\", async () => {\n const user = await fetchUser();\n // Objects are serialized with `@vitest/pretty-format`, strings are written\n // verbatim.\n await argosSnapshot(user); // -> \"src/user.test.ts > API response 1\"\n await argosSnapshot(user, { name: \"user\" }); // explicit name\n});\n```\n\nUse the `extension` option to control how Argos renders and diffs the snapshot,\nand `tag` to attach tags:\n\n```ts\nawait argosSnapshot(JSON.stringify(config, null, 2), {\n name: \"config\",\n extension: \".json\",\n tag: \"config\",\n});\n```\n\nScreenshots and snapshots are both written to the `./snapshots` directory by\ndefault (configurable via the plugin `root` option) and uploaded by the reporter\nwhen `uploadToArgos` is enabled.\n\n## Links\n\n- [Official SDK Docs](https://argos-ci.com/docs/reference/vitest)\n- [Quickstart](https://argos-ci.com/docs/quickstart/vitest-quickstart)\n- [Discord](https://argos-ci.com/discord)\n","readmeFilename":"README.md"}