[gregberge]

Documents ARG-515 (argos-ci/argos-javascript#410): the new padding option for element screenshots in the Playwright, Puppeteer, Cypress and Vitest SDKs, and Playwright's argosScreenshot now accepting a Locator as its first argument.

Important

Merge only after the @argos-ci/* release that includes argos-ci/argos-javascript#410 (ARG-515). The SDK change isn't released yet (npm has playwright 7.8.0, puppeteer 6.2.0, cypress 7.4.0, vitest 0.9.0), and this PR removes statements that are true until then: the Playwright FAQ says there is no padding option, and the migration guide says the first argument can't be a locator.

Changes

• Playwright
  • handler can be a Locator: argosScreenshot(page.getByRole("dialog"), "dialog") is the same as passing the page with element, so it can't be combined with options.element.
  • New options.padding: a number or a CSS-shorthand array of 1–4 numbers. It requires element (or a Locator handler), can't be combined with clip, and is clamped to the page, or to the frame when the handler is a Frame or a Locator inside an iframe.
  • "Screenshots inside iframes" now says that passing an iframe locator as the handler makes stabilization, argosCSS and the helpers run inside that frame. The SDK resolves the locator's owner frame.
  • FAQ "Can I add padding around an element screenshot?" now answers yes, with an example. It used to suggest capturing a wrapper element.
• Puppeteer: options.padding requires element, can't be combined with clip, and is clamped to the page.
• Cypress: options.padding only applies when chained off an element. Argos clamps it to the page, while cy.screenshot's own padding shifts the area back inside the page near its edges. I also moved the "chain the command from an element" sentence above the option list, where it had been splitting the list in two.
• Vitest: per-call padding requires element and is clamped to the test's content.
• Migration guide (Playwright native): element screenshots now pass the locator directly, and padding is mentioned for shadows and focus rings. This replaces "The first argument must be a Page or a Frame, not a locator."

Checked against the SDK changes in argos-ci/argos-javascript#410: ElementPadding / getPaddedClip / clampPadding in @argos-ci/util, the validation errors in the Playwright and Puppeteer argosScreenshot, and the Cypress clamping before cy.screenshot.

Not changed

• argosAriaSnapshot still takes a Page or Frame only, so its reference is unchanged.
• WebdriverIO and Storybook don't get padding in ARG-515.

🤖 Generated with Claude Code