[gregberge]

Stacked on #403 (ARG-520).

Why

Puppeteer has no native mask, so [data-visual-test="blackout"] was silently ignored by @argos-ci/puppeteer (the docs say blackout is "Storybook, Playwright, and Cypress SDKs only"). Playwright has mask and Cypress has blackout; Puppeteer had nothing.

What

• @argos-ci/browser: new __ARGOS__.mask(elements, color), undone by afterEach(). It draws a box over each element, the way Playwright's own mask works:
  • a glass pane shown as a popover="manual" so it sits in the top layer, above modal dialogs and popovers;
  • boxes inside a shadow root, so page styles don't reach them, positioned from getBoundingClientRect();
  • a requestAnimationFrame loop that keeps the boxes on their elements until cleanup. Puppeteer scrolls the element into view inside ElementHandle.screenshot(), after we measure, and resizes the viewport for fullPage + captureBeyondViewport: false.
• @argos-ci/puppeteer: new mask option ((string | ElementHandle)[]) and maskColor option (default #FF00FF, same as Playwright and the WebdriverIO SDK). [data-visual-test="blackout"] is always masked. The mask is applied after the last stabilization wait, right before capture, so the boxes match the final layout.

The browser function is generic, so other SDKs without a native mask can reuse it.

Tests

Pixel-level tests in packages/puppeteer/test.spec.js decode the PNG in the page with a canvas:

• blackout helper + mask selectors and handles, with exact box edges, and the overlay is removed afterwards;
• maskColor;
• full-page screenshot of a page scrolled to 1000px, with an element masked below the fold;
• element screenshot of an element below the fold (fails without the rAF loop);
• element masked inside an open modal <dialog> (fails without the popover).

pnpm exec turbo run check-types lint check-format --filter=@argos-ci/puppeteer --filter=@argos-ci/browser passes, and all 17 Puppeteer tests pass locally.

Follow-ups

• Docs: drop "Storybook, Playwright, and Cypress SDKs only" from the blackout helper and document mask/maskColor in the Puppeteer reference, once this ships.

🤖 Generated with Claude Code

[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 8:20am UTC