diff --git a/packages/cypress/cypress/e2e/argosScreenshot.cy.ts b/packages/cypress/cypress/e2e/argosScreenshot.cy.ts index 45b5ba58..1be32ee0 100644 --- a/packages/cypress/cypress/e2e/argosScreenshot.cy.ts +++ b/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"], + }); + }); }); diff --git a/packages/cypress/docs/index.mdx b/packages/cypress/docs/index.mdx index c22cf8c8..450bded6 100644 --- a/packages/cypress/docs/index.mdx +++ b/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 diff --git a/packages/cypress/src/support.ts b/packages/cypress/src/support.ts index 885617de..26518dff 100644 --- a/packages/cypress/src/support.ts +++ b/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; diff --git a/packages/playwright/docs/index.mdx b/packages/playwright/docs/index.mdx index 2d7b4d02..9e34e69b 100644 --- a/packages/playwright/docs/index.mdx +++ b/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. diff --git a/packages/playwright/e2e.spec.ts b/packages/playwright/e2e.spec.ts index f572ca5b..abbeaee5 100644 --- a/packages/playwright/e2e.spec.ts +++ b/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", () => { diff --git a/packages/playwright/src/metadata.ts b/packages/playwright/src/metadata.ts index a330bb31..b22b61cc 100644 --- a/packages/playwright/src/metadata.ts +++ b/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, diff --git a/packages/playwright/src/screenshot.ts b/packages/playwright/src/screenshot.ts index 0cc4d78b..35be9213 100644 --- a/packages/playwright/src/screenshot.ts +++ b/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; diff --git a/packages/puppeteer/docs/index.mdx b/packages/puppeteer/docs/index.mdx index b13c2eeb..2617e954 100644 --- a/packages/puppeteer/docs/index.mdx +++ b/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. diff --git a/packages/puppeteer/src/index.ts b/packages/puppeteer/src/index.ts index 3e29a2f8..dae41082 100644 --- a/packages/puppeteer/src/index.ts +++ b/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 { @@ -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; diff --git a/packages/puppeteer/test.spec.js b/packages/puppeteer/test.spec.js index cf221a0b..e9664569 100644 --- a/packages/puppeteer/test.spec.js +++ b/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"); diff --git a/packages/util/src/metadata.ts b/packages/util/src/metadata.ts index bcfacc53..6729e698 100644 --- a/packages/util/src/metadata.ts +++ b/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 */