Cypress Screenshot Blackout Option for Hiding Private Data

Cypress can obscure selected page elements in screenshots with the blackout option. Pass it an array of CSS selectors to cy.screenshot(), or set defaults with Cypress.Screenshot.defaults(). The important limit: Cypress documents blackout for capture: 'viewport'; it is ignored for capture: 'runner'. In particular, do not assume blackout protects automatic failure screenshots from cypress run, which Cypress coerces to runner captures.

1. Use blackout for a viewport screenshot

Use selectors that match the sensitive elements in the application under test. This example captures the current application viewport and covers elements matching either selector:

cy.screenshot('account-page', {
  capture: 'viewport',
  blackout: ['.private-data', '[data-private="true"]'],
})

blackout takes an array of CSS selector strings. Cypress’s documented default is an empty array. If a selector matches no elements, there is nothing for that selector to obscure; check the selector against the rendered page and the markup used in the test.

2. Configure defaults for a test suite

To apply the same capture mode and selectors to screenshots throughout a suite, set screenshot defaults in the Cypress support file. Cypress loads that file before test files are evaluated.

Cypress.Screenshot.defaults({
  capture: 'viewport',
  blackout: ['[data-private="true"]'],
})

A test can pass screenshot options at the call site, as in the first example. Keep sensitive selectors aligned with the application’s markup as it changes. A dedicated attribute such as data-private="true" can make the intent easier to identify and maintain than a broad selector.

3. Understand capture modes and the privacy limit

Capture mode	What Cypress captures	Blackout behavior
`viewport`	The application in the current viewport	Cypress documents selector blackout for this mode.
`fullPage`	The application page from top to bottom	The documentation reviewed does not establish a blackout guarantee for this mode. Do not rely on it to mask private data without confirming the current Cypress API behavior.
`runner`	The browser viewport including the Cypress Command Log	Blackout is ignored.

Cypress states that matching elements are blacked out “only when the capture option is viewport.” Set capture: 'viewport' explicitly when relying on blackout. This makes the intended behavior clear and avoids assuming a different capture mode has the same protection. See the Cypress screenshot API documentation.

4. Treat automatic failure screenshots separately

Cypress documents that screenshots taken automatically after a test failure during cypress run are coerced to runner captures. Because blackout is ignored for runner captures, selectors configured for normal viewport screenshots should not be treated as protection for those failure screenshots.

If those automatic screenshots should not be created, Cypress documents screenshotOnRunFailure: false as a configuration option:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  screenshotOnRunFailure: false,
})

Use this only when disabling automatic failure screenshots fits your debugging workflow. If failure screenshots remain enabled, account for their runner capture behavior when deciding what data may appear in the test environment and who can access the resulting artifacts.

5. Know what screenshot blackout does not control

Blackout masks matching page elements in the documented viewport capture. It is not a general control for every kind of data Cypress might capture or make available. Cypress Cloud documents separate controls for screenshot masking, Command Log content, and Test Replay data. Consider each captured-data surface on its own, and check Cypress’s current Cloud screenshot masking documentation when configuring access to run artifacts.

Cypress saves screenshots in the configured screenshots folder, which defaults to cypress/screenshots. Treat saved files and uploaded run artifacts according to their contents and the access controls for the environment where they are stored.

6. Troubleshooting

Symptom	Likely cause	What to check
Sensitive content is visible in the screenshot.	The capture is not `viewport`, or the selector does not match the rendered element.	Set `capture: 'viewport'` on the screenshot call or in defaults. Inspect the rendered DOM and verify each selector.
Blackout works in a manual screenshot but not after a failed run.	Automatic failure screenshots during `cypress run` are coerced to `runner`.	Do not rely on blackout for that capture. If suitable for the workflow, disable automatic failure screenshots with `screenshotOnRunFailure: false`.
The Cypress Command Log or other run data still contains information.	Blackout targets matching application elements; it is not a universal command-log or replay-data control.	Review Cypress Cloud’s separate screenshot, Command Log, and Test Replay controls.
A selector stops masking after a UI change.	The application markup or sensitive element’s location changed.	Update the selector and verify it against the current rendered page. Prefer stable attributes maintained with the component.

7. Reliability, runtime, and visual testing

Selector-based masking depends on both the selected capture mode and the selector matching the page at screenshot time. Keep the selector close to the test or application contract, and review it when the UI changes. This is a configuration safeguard, not a replacement for using non-sensitive test data where possible.

Cypress’s screenshot command captures an image; Cypress’s visual-testing documentation says the built-in command does not compare images. If you need visual regression checks, add a comparison workflow or tool. Masking a region can also hide visual changes inside that region, so choose selectors that cover only the data that needs obscuring.

ScreenshotNeo is a website screenshot API and MCP server from ScreenshotNeo. It is useful when the task is capturing a website outside a Cypress test: one GET request can return a PNG, JPEG, WebP, or PDF. Its capture options include CSS selector hiding, custom CSS and JavaScript, and waits. It does not replace Cypress test-run screenshots or Cypress Cloud controls.

Or skip the browser setup

For a standalone website screenshot, call the ScreenshotNeo API:

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

Cookie banners are accepted and removed before capture, along with known consent platforms, newsletter popups, and chat widgets; each of those steps can be turned off. Bot checks, blank pages, and failed loads are not billed. An MCP server provides screenshot tools for AI agents. The free plan includes 1,000 screenshots a month without a card; paid plans start at $5 for 3,000 screenshots. Use ScreenshotNeo’s CSS selector hiding option when the goal is to obscure a specific element in a standalone capture.

FAQ

Does blackout remove an element from the page?

No. It obscures matching content in the supported screenshot capture; it does not change the application’s rendered page.

Does Cypress compare the screenshot to a baseline?

No. The built-in screenshot command captures an image. Visual comparison needs an additional workflow or tool.

Where are Cypress screenshots saved?

They are saved in the configured screenshots folder. The default is cypress/screenshots.