[gregberge]

Documents the hide, remove and mask options of argosScreenshot from argos-ci/argos-javascript#403 (ARG-520), which now covers every SDK. They let you hide, remove or mask dynamic elements from the test, without adding data-visual-test attributes to the app.

Important

Merge only after the SDK release that includes argos-ci/argos-javascript#403. #403 is merged on main (4609e4a..5712957) but not released yet: npm still has playwright 7.7.1, puppeteer 6.1.11, cypress 7.2.4, webdriverio 0.9.0, vitest 0.8.0 and storybook 6.4.2.

Changes

• Playwright: options.hide and options.remove (Locators or string selectors), options.mask (now also string selectors) and options.maskColor in the argosScreenshot options, plus an example in "Helper Attributes for Visual Testing". "Mask elements" now says mask adds to the [data-visual-test="blackout"] elements, so I removed the workaround of re-adding the blackout locator yourself.
• Puppeteer: hide, remove and the new mask (string selectors or ElementHandles) and maskColor. data-visual-test="blackout" is now listed in the helpers.
• Cypress: hide and remove (selectors), and blackout, which now extends the [data-visual-test="blackout"] selector (fixed on argos-javascript main in f72211e, also unreleased).
• WebdriverIO: hide, remove (WebdriverIO selectors), mask (now WebdriverIO selectors as well as rectangles; elements with data-visual-test="blackout" are always masked) and the new argosCSS. The hint saying the SDK captures as-is is replaced: the data-visual-test helpers and argosCSS now apply, but stabilization waits (loading, fonts, images, GIFs, scrollbars, carets) still don't. A new "Helper Attributes for Visual Testing" section matches the other SDKs, with a warning that screenshots of pages using data-visual-test attributes change after upgrading. In an Appium native app context, the screen is still captured as is: no helpers, rectangle masks only, and hide, remove, argosCSS or selector masks throw an error (5c5b175).
• Vitest: hide, remove, mask (selectors) and maskColor in the per-call options. The plugin paragraph notes that a per-call list replaces the plugin's list instead of adding to it ({ ...pluginOptions, ...options }).
• Argos helpers: blackout is no longer limited to some SDKs. A note says WebdriverIO applies transparent, removed, blackout and no-radius, but not the stabilization ones (wait-bg-img, GIF pausing). A new "Apply helpers from your tests" section maps transparent → hide, removed → remove, blackout → mask (blackout in Cypress), with a Playwright example and links to every SDK reference.

Checked against the merged code on argos-javascript main (5712957, same tree as the #403 head 5c5b175). Behavior described everywhere: hide keeps the element's layout space, remove takes it out of the layout, selectors that match nothing are ignored, an element in both lists is removed, and the page is restored after the screenshot. The options are applied again for each viewport in the SDKs that support viewports.

Not changed

• Storybook: the page links to the Playwright options instead of listing them, so it picks up the new options without changes.
• The migration guides (from-lost-pixel.md, from-vitest-native-screenshots.md) still map mask to data-visual-test helpers or argosCSS. They could point to hide / mask in a follow-up.

🤖 Generated with Claude Code

[Copilot]

🔵 Needs a closer look

Upstream SDK PR #403 remains unmerged, so a maintainer must confirm the required release before merging these docs.

No open issues 🎉

What changed in this PR

Documents test-side screenshot helpers for hiding dynamic content without changing application markup.

Changes:

• Adds hide and remove options and examples across SDK references.
• Clarifies additive masking and Vitest per-call overrides.
• Maps helper attributes to SDK options in the shared guide.

File	Description
docs/​sdks-reference/​vitest.md	Documents selectors and plugin-default overrides.
docs/​sdks-reference/​puppeteer.md	Adds helper options and usage example.
docs/​sdks-reference/​playwright.md	Adds helper options and clarifies additive masking.
docs/​sdks-reference/​cypress.md	Documents helper options and additive blackout.
docs/​learn/​reliability-and-flakiness/​flaky-tests/​argos-helpers.md	Maps attributes to test-side options and SDK references.

_{Review effort: Balanced}