[gregberge]

Description

Part of ARG-520. You can now hide, remove or mask dynamic elements straight from argosScreenshot, without adding data-visual-test attributes to the application, in every SDK:

argosScreenshot(page, "dashboard", {
  hide: ["#clock", page.getByTestId("avatar")], // like data-visual-test="transparent": keeps its space
  remove: [".cookie-banner"], // like data-visual-test="removed": takes no space
  mask: ["#map"], // like data-visual-test="blackout": covered with a box
});

SDK	hide / remove	mask (+ maskColor)	data-visual-test helpers
Playwright	selectors or Locators	selectors or Locators (native option, extended)	all
Puppeteer	selectors or ElementHandles	selectors or ElementHandles (new: overlay boxes)	all, blackout new
Cypress	selectors	native blackout (selectors)	all
WebdriverIO	selectors	selectors or rectangles (new: selectors)	all (new)
Vitest	selectors (per-call options)	selectors (per-call options)	all
Storybook	inherited from the Playwright options	inherited	all

How it works:

• hide / remove: a new browser global, __ARGOS__.applyHelper(elements, helper), sets the data-visual-test attribute on the elements each SDK resolved with its own selector engine. The argosHelpers core plugin's beforeEach cleanup restores the original values, including an existing data-visual-test="blackout". Helpers are applied before beforeEach, so plugins that measure layout see the same page as with markup attributes. They are applied again for each viewport. When an element is both hidden and removed, remove wins, whatever the call order.
• mask in Puppeteer, which has no native mask: __ARGOS__.mask(elements, color) draws a top-layer overlay that follows the elements. It works for full-page and element screenshots and above modal dialogs, and the same cleanup removes it.
• WebdriverIO now injects the Argos browser script with only the core plugins (no stabilization waits). The data-visual-test helpers and argosCSS now apply there. Masks are composited onto the PNG with sharp, using element rects scaled by devicePixelRatio. In an Appium native-app context, where no script can run, it captures the screen as before (rectangle masks only), and the options that need a page throw a clear error.

Behavior changes:

• Selectors that match nothing are ignored.
• Playwright: passing mask used to replace the mask on [data-visual-test="blackout"] elements; it now adds to it (fix(playwright) commit). The same Cypress blackout bug was fixed on main in f72211e.
• WebdriverIO: screenshots of pages that use data-visual-test attributes will change, because the helpers now apply.

Type of changes

enhancement

Checklist

• I have read the CONTRIBUTING doc
• The commits message follows the Conventional Commits' policy
• Lint and unit tests pass locally
• I have added tests if needed

Optional checks:

• My changes requires a change to the documentation
• I have updated the documentation accordingly (docs: document hide, remove and mask screenshot options docs#264, to merge after the release)

Further comments

Tests. Every SDK has e2e tests that check pixels in the captured PNGs, or attributes for Cypress, during and after the screenshot. They cover hide, remove, precedence, restoring the page, the merged blackout mask, maskColor, and for Puppeteer full-page, element and modal-dialog masks. Locally: Playwright 28, Puppeteer 17, Cypress 9, WebdriverIO 9 and Vitest 21 pass, plus types, lint, format and unit tests for the seven packages.

Merging. Prefer Rebase and merge. Each commit is a conventional commit scoped to its packages (fix(playwright), feat(puppeteer), feat(webdriverio), …), so the changelogs list each change. A squash would collapse them into one entry.

Not covered: the wider ARG-520 idea of diff-time ignore regions (stored in metadata or set in the review UI) is backend and app work, so the issue stays open.

🤖 Generated with Claude Code

[linear-code]

ARG-520

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
argos-js-sdk-reference	Ready	Preview	Oct 21, 2026 9:10am UTC