How to Reduce Cypress Screenshot File Size

The most reliable way to reduce Cypress screenshot storage is to capture fewer screenshots and less page area. Keep failure screenshots if your team uses them to debug CI, avoid full-page captures when a component screenshot will answer the question, and post-process PNGs only after checking the output. Cypress’s documented screenshot options do not include a compression-quality setting.

1. Decide whether you need each screenshot

Cypress can capture screenshots when you call cy.screenshot(), and it can automatically capture a screenshot when a test fails during cypress run. Automatic failure capture is enabled by default. Turn it off only if your team has another dependable way to investigate failures; otherwise, the storage reduction may cost useful debugging evidence.

const { defineConfig } = require('cypress')

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

This setting affects Cypress’s automatic failure screenshots in cypress run. It does not disable explicit cy.screenshot() calls. See the Cypress configuration reference and screenshot command documentation.

Before changing it, answer these questions:

• Do developers use failure screenshots to diagnose intermittent CI failures?
• Are screenshots retained as CI artifacts, and for how long?
• Can the test report or another artifact provide the same visual evidence?

If failure screenshots are essential, keep them and reduce file size by capturing less area or optimizing copies. Disabling screenshots reduces artifact count, not the bytes in each screenshot.

2. Capture the relevant element instead of the whole page

A screenshot of a small component usually contains less image data than a full-page capture. Cypress supports taking a screenshot of an element selected with cy.get():

cy.get('[data-cy=checkout-summary]').screenshot('checkout-summary')

Use a stable test selector and choose an element that includes the evidence needed to diagnose the failure. For example, a checkout summary may need its heading, line items, and total; capturing only the total could hide the cause of a mismatch.

Cypress full-page capture scrolls and stitches sections of the page. That is useful when the test concerns content across the page, but wasteful when the relevant state is confined to one component. Prefer the default viewport screenshot or an element screenshot unless you need the full document. Review the installed Cypress version’s screenshot command options before using crop or full-page options: capture modes do not necessarily accept identical settings.

3. Check artifact retention separately from image size

Cypress clears the configured screenshots folder before cypress run by default. The trashAssetsBeforeRuns configuration controls that cleanup. Setting it to false can retain files across runs and make the directory larger, but it does not compress individual PNGs.

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  trashAssetsBeforeRuns: true,
})

Keep the default cleanup when each run should contain only its own artifacts. If you disable cleanup for a specific retention workflow, arrange separate run directories or another cleanup policy so old screenshots do not accumulate unnoticed. This is a retention decision, distinct from reducing each file’s byte count. See the configuration reference.

4. Optimize PNGs after capture

The documented Cypress screenshot API does not expose a PNG compression-quality option. If capture count and area are already appropriate, post-process screenshots as a separate artifact step. Always preserve the original until you have checked that the optimized image works for debugging and any visual-diff pipeline.

Lossless attempt with OptiPNG

OptiPNG attempts to optimize PNG encoding without changing the represented image. Results vary: a file may shrink, or it may remain the same size. Try it on a copy and compare byte counts:

cp cypress/screenshots/checkout-summary.png /tmp/checkout-summary.png
optipng -o2 /tmp/checkout-summary.png
wc -c cypress/screenshots/checkout-summary.png /tmp/checkout-summary.png

Install OptiPNG using the package manager for your operating system, following the OptiPNG project documentation. The example optimizes the copy in /tmp, leaving Cypress’s original untouched. Use a project-appropriate temporary directory on systems without /tmp.

Lossy reduction with pngquant

For a potentially larger reduction, pngquant reduces the color palette. This is lossy: pixels can change, and gradients, antialiasing, shadows, and color-rich interfaces may show banding or other differences. Do not replace pixel-exact visual baselines without validating the change.

cp cypress/screenshots/checkout-summary.png /tmp/checkout-summary.png
pngquant --quality=80-95 --force --output /tmp/checkout-summary-quantized.png /tmp/checkout-summary.png
wc -c cypress/screenshots/checkout-summary.png /tmp/checkout-summary-quantized.png

The --quality=min-max range lets you set an acceptable quality interval; adjust it based on inspection rather than targeting a promised file size. If pngquant cannot meet the selected quality range, it may return a nonzero status. Check the command result and keep the original. See the pngquant documentation.

5. Validate the change in your actual workflow

1. Choose representative screenshots: a typical page, a gradient-heavy page, and a screenshot used for visual comparison.
2. Record the original file sizes and keep copies of the originals.
3. Apply one change at a time: capture scope, lossless optimization, or lossy optimization.
4. Compare the resulting files and inspect them at normal viewing size and at the scale used by your visual-diff tooling.
5. Run the relevant visual tests and confirm that debugging evidence is still sufficient.
6. Check the CI artifact directory and retention policy separately from individual image bytes.

There is no universal expected saving for Cypress screenshots. The result depends on the page, the image content, and the chosen optimization. Use measured byte counts from your own suite.

6. Troubleshooting

Problem	Likely cause	What to do
Failure screenshots still appear after setting screenshotOnRunFailure: false.	Your test explicitly calls cy.screenshot(), or another workflow creates screenshots.	Search the tests and support code for explicit screenshot calls. The setting controls automatic failure captures, not manual calls.
The screenshots folder keeps growing between runs.	Cleanup may be disabled with trashAssetsBeforeRuns: false, or your CI process preserves prior artifacts.	Check the effective Cypress configuration and CI artifact retention. Cleanup behavior does not alter the size of each PNG.
An element screenshot misses information needed to debug.	The selected element is too narrow, or the issue depends on surrounding layout.	Capture a containing element, use a suitable viewport capture, or use a supported crop/full-page mode appropriate to the installed Cypress version.
OptiPNG produces no smaller file.	The PNG is already efficiently encoded or has little remaining optimization potential.	Keep the original result; savings are not guaranteed. Consider reducing capture area before trying lossy processing.
pngquant reports that the quality range cannot be met.	The requested minimum quality is incompatible with the image’s color distribution and palette reduction.	Keep the original, inspect the output and command status, then choose a different range only if the visual change is acceptable.
Visual tests fail after lossy optimization.	Palette reduction changed pixels in an image used as visual evidence or a baseline.	Do not overwrite pixel-exact baselines with lossy output. Restrict lossy processing to artifacts that tolerate the change, or use capture-scope reduction and lossless optimization.
Optimized files look different around text or gradients.	Lossy color reduction can affect antialiased edges and smooth transitions.	Inspect representative screens at the scale users and diff tools see them. Revert if the changed detail matters.

7. Performance, reliability, and cost considerations

Element capture can reduce the amount of page content recorded, while full-page capture has additional scrolling and stitching work. Post-processing adds a step to the artifact pipeline and consumes build time; measure its effect in your own CI. The supplied documentation does not establish universal runtime costs or compression ratios.

For reliability, preserve originals until optimized artifacts pass inspection and the relevant visual tests. Keep failure screenshots when they are part of your incident or debugging workflow. If you use lossy output, make that choice explicit in the pipeline so it does not silently alter evidence used for pixel comparisons.

For storage cost, compare total artifact bytes per run and retention duration. Fewer captures, smaller capture areas, and verified optimization can all reduce stored data, but the savings depend on the suite and retention setup.

Or skip the browser setup

If you need screenshots of live pages outside Cypress, ScreenshotNeo is a website screenshot API and MCP server. Its one-request API returns PNG, JPEG, WebP, or PDF. This does not change Cypress’s own test artifacts; it is an option when your task is capturing a website through an API.

For example, request a WebP screenshot of a page:

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

See the ScreenshotNeo API documentation for the request options. Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, with response headers indicating the page verdict and billing status. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

Sign up free for 1,000 screenshots a month, with no card required.

FAQ

Does disabling failure screenshots stop manual screenshots?

No. It disables Cypress’s automatic screenshot on test failure during cypress run; explicit cy.screenshot() calls remain active.

Does retaining old Cypress screenshots make each PNG larger?

No. Retention can increase total stored bytes by keeping more files, but it does not change any individual image.

Should I use lossy optimization for visual regression baselines?

Only if your comparison workflow is designed to accept the pixel changes. Otherwise, preserve the original and use capture-scope reduction or lossless optimization.