feat: add tags support

packages/cypress/cypress/e2e/argosScreenshot.cy.ts

@@ -28,4 +28,11 @@ describe("argosScreenshot", () => {
     cy.visit("cypress/pages/index.html");
     cy.argosScreenshot("threshold-option", { threshold: 0.2 });
   });
+
+  it("supports tags option", () => {
+    cy.visit("cypress/pages/index.html");
+    cy.argosScreenshot("tags-option", {
+      tag: ["snapshot-tag"],
+    });
+  });
 });

packages/cypress/docs/index.mdx

@@ -102,6 +102,7 @@ module.exports = defineConfig({
 - `options.stabilize.waitForAriaBusy`: Wait for the `aria-busy` attribute to be removed from the document. Default to `true`.
 - `options.stabilize.waitForFonts`: Wait for fonts to be loaded. Default to `true`.
 - `options.stabilize.waitForImages`: Wait for images to be loaded. Default to `true`.
+- `options.tag`: Tag or array of tags to attach to the screenshot for filtering in Argos.
 
 ## Helper Attributes for Visual Testing
 

packages/cypress/src/support.ts

@@ -43,6 +43,11 @@ type ArgosScreenshotOptions = Partial<
    * @default true
    */
   stabilize?: boolean | StabilizationPluginOptions;
+
+  /**
+   * Tag or array of tags to attach to the screenshot.
+   */
+  tag?: string | string[];
 };
 
 declare global {
@@ -172,7 +177,7 @@ Cypress.Commands.add(
   "argosScreenshot",
   { prevSubject: ["optional", "element", "window", "document"] },
   (subject, name, options = {}) => {
-    const { viewports, argosCSS: _argosCSS, ...cypressOptions } = options;
+    const { viewports, argosCSS: _argosCSS, tag, ...cypressOptions } = options;
     if (!name) {
       throw new Error("The `name` argument is required.");
     }
@@ -243,6 +248,10 @@ Cypress.Commands.add(
 
         metadata.transient = {};
 
+        if (tag) {
+          metadata.tags = Array.isArray(tag) ? tag : [tag];
+        }
+
         if (options.threshold !== undefined) {
           validateThreshold(options.threshold);
           metadata.transient.threshold = options.threshold;

packages/playwright/docs/index.mdx

@@ -315,6 +315,9 @@ Each ARIA snapshot counts as an additional screenshot for billing.
 - `options.stabilize.waitForImages`: Wait for images to be loaded. Default to `true`.
 - `options.beforeScreenshot`: Run a function before taking the screenshot. When using viewports, this function will run before taking sreenshots on each viewport.
 - `options.afterScreenshot`: Run a function after taking the screenshot. When using viewports, this function will run after taking sreenshots on each viewport.
+- `options.tag`: Tag or array of tags to attach to the screenshot for filtering in Argos.
+
+Playwright test tags (from `test.describe` or `test` annotations) are automatically captured in the metadata.
 
 Unlike [Playwright's `screenshot` method](https://playwright.dev/docs/api/class-page#page-screenshot), set `fullPage` option to `true` by default. Feel free to override this option if you prefer partial screenshots of your pages.
 

packages/playwright/e2e.spec.ts

@@ -183,6 +183,20 @@ test.describe("#argosScreenshot", () => {
       });
     });
   });
+
+  test.describe("with tags", () => {
+    test("works", async ({ page }) => {
+      await argosScreenshot(page, "tags-option", {
+        tag: ["snapshot-tag"],
+      });
+    });
+  });
+
+  test.describe("with Playwright test tags", { tag: ["@on-describe"] }, () => {
+    test("captures test tags", { tag: "@on-test" }, async ({ page }) => {
+      await argosScreenshot(page, "playwright-test-tags");
+    });
+  });
 });
 
 test.describe("#argosAriaSnapshot", () => {

packages/playwright/src/metadata.ts

@@ -163,6 +163,7 @@ export async function getTestMetadata(
     id: testInfo.testId,
     title: testInfo.title,
     titlePath: testInfo.titlePath,
+    tags: testInfo.tags.length > 0 ? testInfo.tags : undefined,
     retry: testInfo.retry,
     retries: testInfo.project.retries,
     repeat: testInfo.repeatEachIndex,
@@ -184,6 +185,7 @@ export async function getTestMetadataFromTestCase(
   const testMetadata: ScreenshotMetadata["test"] = {
     title: testCase.title,
     titlePath: testCase.titlePath(),
+    tags: testCase.tags.length > 0 ? testCase.tags : undefined,
     retry: testResult.retry,
     retries: testCase.retries,
     repeat: testCase.repeatEachIndex,

packages/playwright/src/screenshot.ts

@@ -93,6 +93,11 @@ export type ArgosScreenshotOptions = {
    */
   root?: string;
 
+  /**
+   * Tag or array of tags to attach to the screenshot.
+   */
+  tag?: string | string[];
+
   /**
    * Wait for the UI to stabilize before taking the screenshot.
    * Set to `false` to disable stabilization.
@@ -200,6 +205,10 @@ export async function argosScreenshot(
       useArgosReporter,
     });
 
+    if (options.tag) {
+      metadata.tags = Array.isArray(options.tag) ? options.tag : [options.tag];
+    }
+
     if (options.threshold !== undefined) {
       validateThreshold(options.threshold);
       metadata.transient.threshold = options.threshold;

packages/puppeteer/docs/index.mdx

@@ -69,6 +69,7 @@ Screenshots are stored in `screenshots/argos` folder, relative to current direct
 - `options.stabilize.waitForAriaBusy`: Wait for the `aria-busy` attribute to be removed from the document. Default to `true`.
 - `options.stabilize.waitForFonts`: Wait for fonts to be loaded. Default to `true`.
 - `options.stabilize.waitForImages`: Wait for images to be loaded. Default to `true`.
+- `options.tag`: Tag or array of tags to attach to the screenshot for filtering in Argos.
 
 Unlike [Puppeteer's `screenshot` method](https://playwright.dev/docs/api/class-page#page-screenshot), `argosScreenshot` set `fullPage` option to `true` by default. Feel free to override this option if you prefer partial screenshots of your pages.
 

packages/puppeteer/src/index.ts

@@ -76,6 +76,11 @@ export type ArgosScreenshotOptions = Omit<
    * @default true
    */
   stabilize?: boolean | StabilizationPluginOptions;
+
+  /**
+   * Tag or array of tags to attach to the screenshot.
+   */
+  tag?: string | string[];
 };
 
 async function getPuppeteerVersion(): Promise<string> {
@@ -310,6 +315,10 @@ export async function argosScreenshot(
 
     metadata.transient = {};
 
+    if (options?.tag) {
+      metadata.tags = Array.isArray(options.tag) ? options.tag : [options.tag];
+    }
+
     if (options?.threshold !== undefined) {
       validateThreshold(options.threshold);
       metadata.transient.threshold = options.threshold;

packages/puppeteer/test.spec.js

@@ -127,6 +127,12 @@ describe("argosScreenshot", () => {
     });
   });
 
+  it("supports tags option", async () => {
+    await argosScreenshot(page, "tags-option", {
+      tag: ["snapshot-tag"],
+    });
+  });
+
   describe("with cjs version", () => {
     it("works", async () => {
       await argosScreenshotCjs(page, "cjs");

packages/util/src/metadata.ts

@@ -13,6 +13,8 @@ export type ScreenshotMetadata = {
   colorScheme?: ("light" | "dark") | null;
   /** @description The media type when the screenshot was taken */
   mediaType?: ("screen" | "print") | null;
+  /** @description Tags associated with the screenshot */
+  tags?: string[];
   test?:
     | ({
         /** @description The unique identifier of the test */
@@ -21,6 +23,8 @@ export type ScreenshotMetadata = {
         title: string;
         /** @description The path of titles leading to the test */
         titlePath: string[];
+        /** @description Tags associated with the test */
+        tags?: string[];
         /** @description The number of retries for the test */
         retries?: number | null;
         /** @description The current retry count */