Cypress Screenshots

Automatic Failure Screenshots

By default, Cypress automatically captures a screenshot the moment a test fails during a headless (cypress run) execution, saved to the cypress/screenshots folder, giving you visual evidence of the failure state without needing to reproduce it manually.

// cypress.config.js
export default defineConfig({
  screenshotOnRunFailure: true, // default
  screenshotsFolder: 'cypress/screenshots',
});

This behavior is enabled by default; disabling it is rarely useful outside of specific CI storage constraints.

Manual Screenshot Syntax

cy.screenshot()
cy.screenshot('custom-name')
cy.get('[data-cy="chart"]').screenshot()
cy.screenshot({ capture: 'viewport' })

• A bare cy.screenshot() captures the entire page at that point in the test.
• Passing a name saves the file with that specific, identifiable filename.
• Chaining .screenshot() on an element captures just that element's bounding box.
• The capture option controls whether to capture the viewport, the full page, or just a runner element.

Screenshot Options Cheat Sheet

Common configuration and command options for screenshots.

Using Manual Screenshots for Documentation or Visual Review

Beyond failure diagnostics, manual cy.screenshot() calls at key steps can double as lightweight visual documentation of a flow, useful for design review or onboarding new team members to what a feature actually looks like at each stage.

cy.visit('/checkout');
cy.screenshot('checkout-step-1-cart-review');
cy.get('[data-cy="continue"]').click();
cy.screenshot('checkout-step-2-shipping');

Retrieving Screenshots from CI

In CI, screenshots are written to disk during the run but disappear once the job's workspace is cleaned up, unless you explicitly configure your CI provider to upload the cypress/screenshots folder as a build artifact.

• Configure your CI pipeline to upload the cypress/screenshots folder as an artifact on failure.
• Name manual screenshots descriptively so failures are easy to identify in a flat artifact listing.
• Combine with Cypress Cloud (if used) for automatic, centralized screenshot storage and viewing.

Common Mistakes

• Never configuring CI to actually upload the screenshots folder, losing valuable failure evidence.
• Taking so many manual screenshots that the folder becomes cluttered and hard to navigate.
• Assuming a screenshot alone tells the full story without also checking the command log/video for context.
• Disabling automatic failure screenshots without a good reason, losing free, useful failure diagnostics.

Key Takeaways

• Cypress automatically screenshots failures during headless runs by default.
• Manual cy.screenshot() calls capture the page, viewport, or a specific element on demand.
• CI pipelines must be explicitly configured to preserve the screenshots folder as an artifact.
• Screenshots work best combined with videos and command log detail for full failure context.