@argos-ci/vitest 0.2.3

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2022 Smooth Code
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+<p align="center">
+  <a href="https://argos-ci.com/?utm_source=github&utm_medium=logo" target="_blank">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/argos-ci/argos/main/resources/logos/github-readme-logo-dark.png">
+    <img alt="Argos" src="https://raw.githubusercontent.com/argos-ci/argos/main/resources/logos/github-readme-logo-light.png" width="360" height="70">
+  </picture>
+  </a>
+</p>
+
+<p align="center"><strong>The open source visual testing platform for AI-native engineering teams.</strong></p>
+
+# Official Argos Vitest integration
+
+[![npm version](https://img.shields.io/npm/v/@argos-ci/vitest.svg)](https://www.npmjs.com/package/@argos-ci/vitest)
+[![npm dm](https://img.shields.io/npm/dm/@argos-ci/vitest.svg)](https://www.npmjs.com/package/@argos-ci/vitest)
+[![npm dt](https://img.shields.io/npm/dt/@argos-ci/vitest.svg)](https://www.npmjs.com/package/@argos-ci/vitest)
+
+Capture Argos screenshots directly from your [Vitest browser tests](https://vitest.dev/guide/browser/).
+
+Visit the [Vitest SDK documentation](https://argos-ci.com/docs/sdks-reference/vitest) for guides, API and more.
+
+## Installation
+
+Install the package:
+
+```sh
+npm install --save-dev @argos-ci/vitest
+```
+
+`argosSnapshot` runs in any Vitest test — browser or Node — and needs nothing else.
+
+To capture screenshots with `argosScreenshot`, run your tests in
+[Vitest browser mode](https://vitest.dev/guide/browser/) with the
+[Playwright provider](https://vitest.dev/guide/browser/playwright) and install the
+following peer dependencies:
+
+```sh
+npm install --save-dev vitest @vitest/browser @vitest/browser-playwright playwright
+```
+
+## Usage
+
+Register the plugin in your Vitest config:
+
+```ts
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+import { playwright } from "@vitest/browser-playwright";
+import { argosVitestPlugin } from "@argos-ci/vitest/plugin";
+
+export default defineConfig({
+  plugins: [
+    argosVitestPlugin({
+      // Upload the screenshots to Argos at the end of the run.
+      uploadToArgos: process.env.CI === "true",
+    }),
+  ],
+  test: {
+    browser: {
+      enabled: true,
+      headless: true,
+      provider: playwright(),
+      instances: [{ browser: "chromium" }],
+    },
+  },
+});
+```
+
+Then take screenshots from your browser tests:
+
+```ts
+import { test } from "vitest";
+import { render } from "vitest-browser-react";
+import { argosScreenshot } from "@argos-ci/vitest";
+import { Button } from "./Button";
+
+test("Button", async () => {
+  render(<Button>Click me</Button>);
+  await argosScreenshot("button");
+});
+```
+
+## Snapshots
+
+`argosSnapshot` captures a snapshot of any value — not just a screenshot — and
+uploads it to Argos to diff across builds, mimicking
+[Vitest snapshots](https://vitest.dev/guide/snapshot). Unlike `argosScreenshot`,
+it does not need a browser and works in **both** browser and Node tests.
+
+```ts
+import { test } from "vitest";
+import { argosSnapshot } from "@argos-ci/vitest";
+
+test("API response", async () => {
+  const user = await fetchUser();
+  // Objects are serialized with `@vitest/pretty-format`, strings are written
+  // verbatim.
+  await argosSnapshot("user", user);
+});
+```
+
+Use the `extension` option to control how Argos renders and diffs the snapshot,
+and `tag` to attach tags:
+
+```ts
+await argosSnapshot("config", JSON.stringify(config, null, 2), {
+  extension: ".json",
+  tag: "config",
+});
+```
+
+Snapshots are written to the same folder as screenshots and uploaded by the
+reporter when `uploadToArgos` is enabled.
+
+## Links
+
+- [Official SDK Docs](https://argos-ci.com/docs/sdks-reference/vitest)
+- [Quickstart](https://argos-ci.com/docs/quickstart/vitest-quickstart)
+- [Discord](https://argos-ci.com/discord)

package/dist/index.d.mts

@@ -0,0 +1,175 @@
+import { ArgosAttachment } from "@argos-ci/playwright";
+import { StabilizationPluginOptions, ViewportOption } from "@argos-ci/browser";
+
+//#region src/options.d.ts
+/**
+ * Options passed when calling `argosScreenshot` from a browser test.
+ *
+ * These options cross the Vitest browser/node RPC boundary, so they must be
+ * JSON-serializable. Non-serializable options (`beforeScreenshot`,
+ * `afterScreenshot`, a `Locator`/`ElementHandle` `element`, …) can only be set
+ * on the plugin via {@link ArgosVitestPluginOptions}.
+ */
+interface VitestScreenshotOptions {
+  /**
+   * String selector of the element to take a screenshot of.
+   * A `Locator`/`ElementHandle` cannot be used here because it can't be
+   * serialized across the browser/node boundary — set it on the plugin instead.
+   */
+  element?: string;
+  /**
+   * Viewports to take screenshots of.
+   * Implemented by resizing the Vitest iframe (Playwright's native `viewports`
+   * option does not work on a frame).
+   */
+  viewports?: ViewportOption[];
+  /**
+   * Capture the full page instead of fitting the screenshot to the content.
+   * - `false` (default): the iframe grows to fit the content in both
+   *   dimensions, so nothing is clipped.
+   * - `true`: keep the viewport width and grow the height (Playwright-style
+   *   full page).
+   * @default false
+   */
+  fullPage?: boolean;
+  /**
+   * Custom CSS evaluated during the screenshot process.
+   */
+  argosCSS?: string;
+  /**
+   * Sensitivity threshold between 0 and 1.
+   * The higher the threshold, the less sensitive the diff will be.
+   * @default 0.5
+   */
+  threshold?: number;
+  /**
+   * Tag or array of tags to attach to the screenshot.
+   */
+  tag?: string | string[];
+  /**
+   * Capture an ARIA snapshot along with the screenshot.
+   * @default false
+   */
+  ariaSnapshot?: boolean;
+  /**
+   * Disable hover effects by moving the mouse to the top-left corner.
+   * @default true
+   */
+  disableHover?: boolean;
+  /**
+   * Wait for the UI to stabilize before taking the screenshot.
+   * Set to `false` to disable stabilization or pass an object to customize it.
+   * @default true
+   */
+  stabilize?: boolean | StabilizationPluginOptions;
+}
+/**
+ * Options passed when calling `argosSnapshot`.
+ *
+ * `argosSnapshot` serializes any value to a file that Argos picks up and diffs,
+ * mimicking {@link https://vitest.dev/guide/snapshot Vitest snapshots}. Unlike
+ * `argosScreenshot`, it does not need a browser and works both in Vitest browser
+ * tests and in plain Node tests.
+ *
+ * These options must be JSON-serializable so they can cross the Vitest
+ * browser/node RPC boundary — the only exception is `serialize`, which is
+ * applied on the test side *before* the value is sent to Node.
+ */
+interface VitestSnapshotOptions {
+  /**
+   * Folder where the snapshot is written.
+   *
+   * In Node tests this defaults to `"./screenshots"`. In browser tests it
+   * defaults to the plugin `root` and can be overridden per call.
+   * @default "./screenshots"
+   */
+  root?: string;
+  /**
+   * Extension of the snapshot file. It also determines how Argos renders and
+   * diffs the snapshot (e.g. `.txt`, `.json`, `.yml`, `.html`, `.md`).
+   * @default ".txt"
+   */
+  extension?: string;
+  /**
+   * Tag or array of tags to attach to the snapshot.
+   */
+  tag?: string | string[];
+  /**
+   * Custom serializer used when `content` is not already a string.
+   * Defaults to `@vitest/pretty-format` (the serializer Vitest itself uses).
+   */
+  serialize?: (content: unknown) => string;
+}
+/**
+ * Subset of {@link VitestSnapshotOptions} that can cross the Vitest
+ * browser/node RPC boundary (everything but `serialize`, which is applied
+ * before the value is sent to Node).
+ */
+type SerializableSnapshotOptions = Omit<VitestSnapshotOptions, "serialize">;
+//#endregion
+//#region src/index.d.ts
+declare module "vitest/browser" {
+  interface BrowserCommands {
+    argosScreenshot: (name: string, options?: VitestScreenshotOptions) => Promise<ArgosAttachment[]>;
+    argosSnapshot: (name: string, content: string, options?: SerializableSnapshotOptions) => Promise<ArgosAttachment[]>;
+  }
+}
+/**
+ * Take an Argos screenshot in a Vitest browser test.
+ *
+ * Requires the {@link https://www.npmjs.com/package/@argos-ci/vitest Argos Vitest plugin}
+ * to be registered in your Vitest config.
+ *
+ * @example
+ * ```ts
+ * import { render } from "vitest-browser-react";
+ * import { argosScreenshot } from "@argos-ci/vitest";
+ *
+ * test("Button", async () => {
+ *   render(<Button>Click me</Button>);
+ *   await argosScreenshot("button");
+ * });
+ * ```
+ *
+ * @param name - Unique name of the screenshot.
+ * @param options - Serializable screenshot options.
+ * @returns The attachments captured, or an empty array outside of Vitest.
+ */
+declare function argosScreenshot(name: string, options?: VitestScreenshotOptions): Promise<ArgosAttachment[]>;
+/**
+ * Take an Argos snapshot of any serializable value, mimicking
+ * {@link https://vitest.dev/guide/snapshot Vitest snapshots}.
+ *
+ * Unlike {@link argosScreenshot}, this does not need a browser: it serializes
+ * the value (strings verbatim, everything else via `@vitest/pretty-format`) to a
+ * file that Argos picks up and diffs across builds. It works both in Vitest
+ * browser tests and in plain Node tests.
+ *
+ * @example
+ * ```ts
+ * import { argosSnapshot } from "@argos-ci/vitest";
+ *
+ * test("API response", async () => {
+ *   const data = await fetchUser();
+ *   await argosSnapshot("user", data);
+ * });
+ * ```
+ *
+ * @param name - Unique name of the snapshot.
+ * @param content - The value to snapshot. Strings are written as-is; any other
+ *   value is serialized.
+ * @param options - Snapshot options.
+ * @returns The attachments written, or an empty array outside of Vitest.
+ */
+declare function argosSnapshot(name: string, content: unknown, options?: VitestSnapshotOptions): Promise<ArgosAttachment[]>;
+/**
+ * Check if we are running in a Vitest environment.
+ */
+declare function checkIsVitestEnv(): Promise<boolean>;
+/**
+ * Check if we are running in Vitest browser mode.
+ * Vitest sets this global in the browser runner.
+ */
+declare function checkIsBrowserEnv(): boolean;
+//#endregion
+export { type VitestScreenshotOptions, type VitestSnapshotOptions, argosScreenshot, argosSnapshot, checkIsBrowserEnv, checkIsVitestEnv };