Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Run cypress run with Cypress’s default trashAssetsBeforeRuns: true. Before the run starts, Cypress removes every file and nested folder inside the configured screenshotsFolder (normally cypress/screenshots). This is different from cypress open, which does not perform that automatic cleanup.

The setting that clears screenshots

Cypress controls generated screenshot cleanup with trashAssetsBeforeRuns. The default is true, so a headless run starts with an empty screenshots directory. Cleanup is broad: Cypress deletes the entire contents, including nested directories and non-image files, not merely the PNG files it created.

Setting Default or example Effect
trashAssetsBeforeRuns true Clears the configured screenshots, videos and downloads asset folders before cypress run.
screenshotsFolder cypress/screenshots Directory in which Cypress writes screenshots. You can replace it with a project-relative or absolute path.
screenshotOnRunFailure true in the example below Captures a screenshot when a test fails during a run.

The cleanup applies to Cypress’s configured asset folders. It does not remove files in an unrelated visual-regression directory used by a plugin, a baseline repository, or a hosted review service.

Configure it in cypress.config.js or cypress.config.ts

For a modern Cypress project using JavaScript modules, put this configuration in the project root:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
#1 Best Overall
Sale
The IXL Ultimate 3rd Grade Math Workbook, Activity Book for Kids Ages 8-9 Covering Addition, Subtraction, Multiplication, Division, Fractions, Geometry, and More Mathematics (IXL Ultimate Workbooks)
  • Carefully designed questions: Ensuring a solid understanding of concepts
  • Engaging activities: Offering a mix of enjoyable exercises
  • Problem-solving techniques: Providing strategies for tackling challenges
  • Vibrant, full-color visuals: Enhancing learning with captivating illustrations
import { defineConfig } from 'cypress'

export default defineConfig({
  screenshotsFolder: 'cypress/screenshots',
  trashAssetsBeforeRuns: true,
  screenshotOnRunFailure: true,
})

With CommonJS, use the equivalent form:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  screenshotsFolder: 'cypress/screenshots',
  trashAssetsBeforeRuns: true,
  screenshotOnRunFailure: true,
})

Then run the suite in the mode that performs cleanup:

npx cypress run

If you use a custom folder, the same rule applies to that path:

export default defineConfig({
  screenshotsFolder: 'artifacts/cypress/screens',
  trashAssetsBeforeRuns: true,
})

Make sure your CI artifact-upload step points to the same configured directory. A common mistake is to clean cypress/screenshots while Cypress is actually writing to a custom path.

What is deleted, and when

cypress run versus cypress open

Automatic trashing occurs before cypress run, including runs in continuous integration. Interactive cypress open does not trash the asset folders on startup, so images from earlier interactive runs can remain visible there. If you need a clean interactive session, remove the directory yourself before opening Cypress, or run the suite headlessly.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Nested files are included

Cypress uses the screenshots folder as a run-artifact directory. Its cleanup removes nested spec folders, old failure images and any other files placed beneath that directory. Do not store reviewed baselines, masks or hand-edited reference images under this path unless you are prepared to recreate them before every headless run.

Rank #2
YAFIYGI Eye Chart Snellen and Rosenbaum Combo Vision Test Card for Exams Near Point Charts for Professional and Pediatric Use 2 in 1 Eye Exam Chart Set Kids Gifts Eye Exams and Vision Screening 2 PCS
  • Dual Functionality: Our Pocket Eye Chart set includes both the 2 eye charts, offering a versatile solution for measuring visual acuity at a distance and in limited spaces. This 2-in-1 design caters to various vision testing needs
  • Compact and Convenient: Sized at 6.5*3.5 inches, these pocket eye charts are designed for portability. Whether you're a professional optometrist, student, or need a handy tool for vision tests on the go, our compact pocket eye chart set fits conveniently in your pocket 
  • Color Vision Test: The eye chart features Red and Green color bars, providing an easy and helpful color vision test. This additional feature enhances the versatility of our pocket eye chart set, making it suitable for a range of vision examinations
  • Durable and Washable: Crafted from durable plastic, our pocket eye charts are built to last. The washable material ensures easy maintenance and hygiene, making them ideal for repeated use in optometry practices, schools, and offices
  • Pupil Gauge and Non-Reflective:The plastic pocket eye chart includes a pupil gauge, adding practicality to vision examinations. The non-reflective surface ensures accurate readings. This set is a reliable tool for professionals and a handy resource for quick vision assessments

Other Cypress asset folders

The same asset-cleanup mechanism covers the configured downloadsFolder, screenshotsFolder and videosFolder. This does not mean Cypress knows about arbitrary folders created by a visual plugin. A plugin’s baseline and diff directories need their own retention and cleanup policy.

A safe visual-regression workflow

  1. Store approved baselines separately. Put reference images where your comparison tool expects them, outside the generated screenshots folder. Keep them versioned if code review is your approval process.
  2. Start a clean generated-artifact run. Use cypress run with trashAssetsBeforeRuns: true. This prevents an old failure image from being mistaken for output from the current commit.
  3. Capture the page or element. Use Cypress’s cy.screenshot() or your visual plugin’s command. Cypress names files using the adjusted spec path and test name, so stable test names produce predictable locations.
  4. Compare against the baseline. Let the local plugin or hosted service produce its diff. Review the diff rather than replacing the baseline automatically.
  5. Publish only useful artifacts. Upload current screenshots, diffs and test metadata that reviewers need. Do not treat an old failure screenshot as a baseline merely because it is present on a workspace.
  6. Apply retention outside Cypress. Clean temporary diff and image folders according to your CI retention policy, while preserving approved baselines for the branch or release process.

This separation gives each directory one job: generated run output can be disposable, while approved references remain durable.

Why old files create misleading results

Cypress derives screenshot paths from the spec and test name. If a workspace is reused and old assets remain, a directory listing can contain images from different commits, renamed tests or previous failures. Reviewers may then inspect the wrong image, and scripts that glob for “the latest” file can compare an unintended pair.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Generated screenshots, videos and downloads are commonly excluded from source control because they are reproducible run artifacts. Keep them ignored unless your process intentionally reviews those exact files in Git. Baselines are the exception: they belong in the location and repository defined by your comparison tool, not in a folder Cypress is configured to empty.

How to keep screenshots instead

Disable automatic trashing deliberately

Set the option to false only when retaining prior run assets is part of your workflow:

export default defineConfig({
  screenshotsFolder: 'cypress/screenshots',
  trashAssetsBeforeRuns: false,
})

With this setting, Cypress leaves existing contents in place before cypress run. You must then prevent stale files from being treated as current output. Use a unique CI workspace, add a commit or build identifier to your artifact path, or run an explicit cleanup step that removes only temporary files while preserving the assets you have reviewed.

Do not use the switch to protect baselines

Turning off trashing protects everything in the folder, including accidental leftovers. It is safer to move baselines elsewhere and keep cleanup enabled for generated output. If a plugin writes diffs or comparison metadata beside Cypress screenshots, configure that plugin’s retention independently.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Where screenshots and diffs are stored

Unless changed in configuration, Cypress writes screenshots below cypress/screenshots. The path continues through an adjusted spec path and the test name, which is why two specs can produce separate subdirectories. A visual-regression plugin may write its baseline, actual-image and diff-image files to completely different locations, locally or in a hosted dashboard.

Artifact Typical owner Retention decision
Failure or explicit cy.screenshot() image Cypress Usually disposable per run; clean with trashAssetsBeforeRuns.
Approved baseline Visual-regression tool or repository Preserve according to review and release policy.
Diff image and comparison metadata Plugin or hosted service Keep for the review window, then expire independently.

Troubleshooting cleanup problems

Old screenshots remain after a supposed clean run

  • Confirm the command was npx cypress run, not cypress open.
  • Print or inspect the effective screenshotsFolder; a custom path may differ from the directory you are checking.
  • Check whether the “old” files are actually plugin baselines or diffs outside Cypress’s folder.
  • Verify that the CI job is using the configuration file and environment you edited, rather than a different package or working directory.

Baselines disappeared

If baselines were stored under the configured screenshots folder, they were included in Cypress’s cleanup. Restore them from version control or the comparison service, then move them to the tool’s designated baseline location. Keep trashAssetsBeforeRuns enabled for generated output.

The run passes, but the comparison reports unexpected images

  • Check the spec and test names used to build the screenshot path; renaming a test can leave an old image beside a new one when trashing is disabled.
  • Inspect the plugin’s own output directory and cache rules. Cypress cleanup does not imply plugin cleanup.
  • Ensure the comparison step consumes files from the current build directory, not a shared workspace left by another job.

CI cannot find screenshots to upload

Upload the configured screenshotsFolder, not a hard-coded default. Also ensure the upload runs after Cypress exits and before the workspace-cleanup step. If no test failed and no explicit screenshot command ran, an empty folder may be the expected result.

Rank #4
Morning and Bedtime Routine Chart with 12 visual symbols pecs cards by Create Visual Aids to support routine, transition for children, autism, aspergers, ADHD, speech and language delay.
  • Creating calmer and happier mornings and bedtimes for the whole family by showing your child what they need to do to get ready.
  • Encourages independence and therefore boosts self esteem as children are no longer dependent on you reminding them what comes next.
  • Allows for processing time - the pictures, or pecs cards for autism, don't disappear like words do and therefore these are great for children with special educational needs, autism, ADHD, speech and language delay, ASD.
  • Eliminates the need for you to nag - children can see what they need to do for themselves in this routine chart.
  • Pictures cards can be moved around thanks to being attached using VELCRO Brand hook and loop, meaning you can order the routine to suit your family.

Runs are slow after enabling cleanup

Deleting many files adds filesystem work before the browser starts. Keep generated folders limited to run artifacts, avoid placing large baselines there, and let CI retention handle old job artifacts. The cleanup cost varies with the number and size of files; Cypress does not publish a universal timing figure.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Local plugins versus hosted visual testing

Open-source visual-testing plugins commonly perform image comparison locally or in CI. A hosted option such as SmartBear VisualTest adds Cypress commands for full-page, element and multi-device captures plus a review dashboard. Choose based on where baselines live, how approvals are recorded, how CI is integrated, and whether you need one viewport or several.

Decision point Local or open-source plugin Hosted visual service
Execution Your runner and browser environment Commands integrate with Cypress while review and processing are provided by the service
Baseline storage Repository or CI workspace chosen by you Service-managed project storage, subject to its retention model
Approval Pull requests, files and your existing tooling Dashboard-based review and approval workflow
Capture scope Depends on the plugin commands you install SmartBear VisualTest documentation describes full-page, element and multi-device captures

Whichever model you choose, Cypress’s own screenshots folder remains a generated-artifact location. Document the separate baseline and diff paths so a cleanup change cannot erase reviewed references.

Or skip the browser setup:

If you only need a clean page image for a regression check, ScreenshotNeo provides a single HTTP request instead of a locally managed browser. It accepts the page before capture, removes cookie-consent banners, newsletter popups and chat widgets, and supports PNG, JPEG, WebP or PDF output. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads and cache hits are identified in the response and are not billed as clean shots. Its MCP server exposes take_screenshot, get_page_info and capture_pdf to Claude, Cursor and other MCP clients.

See the ScreenshotNeo API documentation for all options. A cURL request:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python:

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo includes full-page and element capture, dark mode, device presets or custom viewports, retina scale, PDF page controls, custom CSS and JavaScript, selector hiding, waits, request blocking, headers, cookies, user-agent, authorization, timezone, geolocation, transparent backgrounds, resizing, configurable caching, signed image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API and an OpenAPI specification. Parameter names used by other screenshot APIs also work, which can simplify migration.

The Free plan includes 1,000 shots each month with no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan, and annual billing gives two months free. Create a free ScreenshotNeo account to start with those 1,000 monthly shots.

Frequently Asked Questions

Does changing screenshotsFolder change the names Cypress generates?

No. Cypress still builds paths from the adjusted spec path and test name; changing the setting changes the root directory only.

Can a visual plugin clean its own baseline directory automatically?

Not through Cypress’s trashAssetsBeforeRuns option. Plugin and hosted-service directories require the retention controls provided by that tool.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Is disabling trashing appropriate for collecting historical run images?

Only with an explicit storage design, such as unique build directories or a controlled archival step. Otherwise, files from different runs can be mixed and misread.

The Bottom Line

Keep trashAssetsBeforeRuns: true, run cypress run, and store baselines outside Cypress’s generated screenshots folder. Disable cleanup only when your retention process can distinguish every build’s artifacts.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.