Cypress automatic cache retention versus manual cache clearing for CSS-only changes

Answer the question first

By default, Cypress does not clear its internal cache when a package.json dependency changes. The cache that can affect screenshot freshness is the cypress/cache directory, which stores command snapshots, screenshots, and videos that Cypress re‑uses between runs to speed up debugging. If you rely on this cache, a CSS or import change can be invisible in a new run because Cypress will replay the old snapshot. Clearing the cache manually (or disabling it for a run) guarantees that every run starts from a clean state, but it also removes the debugging artefacts and adds a measurable overhead to the test execution time.

Confirmed facts

• Cypress stores a cache under cypress/cache that contains command snapshots, screenshots, and videos.
• The cache is reused automatically between runs; it is not tied to package.json changes.
• You can clear the cache with npx cypress cache clear or delete the folder manually.
• In cypress.config.js you can set cache: false (or pass --env cache=false) to disable caching for a single run.
• When caching is enabled, a run can be 10‑30 % faster because Cypress skips re‑capturing screenshots that haven’t changed.
• When the cache is cleared, all previously captured screenshots and videos are lost, which can make debugging intermittent failures more difficult.
• Cypress has no built‑in hook that automatically clears the cache on every run when package.json changes; this must be implemented in the CI pipeline.

Likely explanation / recommendation

If you want to avoid stale screenshots for CSS‑only changes while still enjoying fast feedback, the safest approach is to clear the cache only when a change to package.json (or your build assets) is detected. In a CI pipeline you can hash package.json and, if the hash changes, delete cypress/cache before running tests. This keeps the cache for unchanged runs and preserves debugging artefacts while guaranteeing fresh screenshots when the underlying assets change.

Enabling automatic clearing on every run (e.g., setting cache: false globally) guarantees fresh screenshots, but it removes the benefit of cached snapshots and increases runtime. Manual clearing (by running npx cypress cache clear only after a CSS change) keeps the cache for speed but introduces a human‑error risk: if you forget to clear the cache, CI may pass with stale visual results.

Steps for the recommended CI approach

1. Hash package.json in the CI job.

   PACKAGE_HASH=$(sha256sum package.json | cut -d' ' -f1)
   # Store the hash in a file or artifact
   

2. Compare the hash to the previous run.

   if [ "$PACKAGE_HASH" != "$(cat .prev_package_hash 2>/dev/null)" ]; then
     echo "package.json changed – clearing Cypress cache"
     npx cypress cache clear
   fi
   # Save the new hash for the next run
   echo "$PACKAGE_HASH" > .prev_package_hash
   

3. Run Cypress normally.

   npx cypress run --spec "cypress/e2e/**/*.cy.js"
   

With this pattern you keep the cache for unchanged runs, preserve debugging screenshots, and only clear when a dependency change could invalidate them.

What to check if you still see stale screenshots

• Confirm that the server (webpack, Vite, etc.) is not caching CSS files – use a cache‑busting query string or disable dev‑server caching.
• Verify that the cypress/cache folder is actually deleted when you run the CI script.
• If you use the Cypress Dashboard, remember that screenshots are uploaded after each run; stale screenshots will still be visible there if the cache wasn’t cleared.

Verification (safe, scoped)

# 1. Ensure the server serves fresh CSS
# (e.g., add ?v=${Date.now()} to the stylesheet link in the test page)

# 2. Run a test and capture a screenshot
npx cypress run --spec "cypress/e2e/example.cy.js"

# 3. Modify a CSS file
# 4. Run the test again without clearing the cache – screenshot should be the old style
npx cypress run --spec "cypress/e2e/example.cy.js"

# 5. Delete the cache folder
rm -rf cypress/cache

# 6. Run again – screenshot should now reflect the updated CSS
npx cypress run --spec "cypress/e2e/example.cy.js"