fix: pause animations during screenshots

[adamalston]

• Closes Cypress Test Occasionally Fails Due to Minor Image Differences With Animation Disabled #29144

Additional details

• cy.screenshot() did not pause animations created via the Web Animations API (document.getAnimations()), which allowed elements using element.animate() to continue changing during capture.
• I updated the animation disabler to pause and resume animations, while keeping nested disable and cleanup calls balanced.
• I adjusted screenshot cleanup so onAfterScreenshot runs only after timers and animations are restored.

---

Note

Medium Risk
Changes how Cypress disables animations during cy.screenshot() by pausing/resuming Web Animations API animations with nested-call reference counting, which could impact timing-sensitive tests or leave animations paused if edge cases are missed.

Overview
Fixes cy.screenshot() flake potential by extending the animation disabler to pause running Web Animations API animations (document.getAnimations()) during capture and resume them afterward, while keeping nested add/remove calls balanced and ensuring the injected CSS disabler style is only added/removed once per document.

Adds a new unit test suite for dom/animation covering resume/pause behavior, nesting, missing getAnimations fallback, and error handling, plus an e2e screenshot test asserting onAfterScreenshot runs before timers are resumed. Updates the CLI changelog to note the screenshot/animation bugfix.

^{Reviewed by Cursor Bugbot for commit 39c66c1. Bugbot is set up for automated code reviews on this repo. Configure here.}

Steps to test

# Tests should pass.
yarn workspace @packages/driver test test/unit/dom/animation.spec.ts
yarn workspace @packages/driver cypress:run --spec cypress/e2e/commands/screenshot.cy.js
# Revert the fix.
git restore --source=develop --staged --worktree \
  packages/driver/src/dom/animation.ts \
  packages/driver/src/cy/commands/screenshot.ts
# Tests should fail.
yarn workspace @packages/driver test test/unit/dom/animation.spec.ts
# Restore the fix.
git restore --source=HEAD --staged --worktree \
  packages/driver/src/dom/animation.ts \
  packages/driver/src/cy/commands/screenshot.ts
# Tests should pass again.
yarn workspace @packages/driver test test/unit/dom/animation.spec.ts
yarn workspace @packages/driver cypress:run --spec cypress/e2e/commands/screenshot.cy.js

How has the user experience changed?

Before, screenshot capture could leave animations running. Based on the code, nested cleanup calls could also result in animations remaining paused after capture, and there was no post-cleanup hook for screenshot callbacks to safely inspect or preserve the final animation state.

After, Cypress pauses running animations during screenshot capture, restores them after the final cleanup call, and calls onAfterScreenshot only after timers and animations have been restored. That should improve the stability of screenshot comparisons for apps that include animations.

PR Tasks

• Have tests been added/updated?
• [na] Has a PR for user-facing changes been opened in cypress-documentation?
• [na] Have API changes been updated in the type definitions?

[cypress-app-bot]

• Create a Draft Pull Request if your PR is not ready for review. Mark the PR as Ready for Review when you're ready for a Cypress team member to review the PR.

[cacieprins]

for ... of is more idiomatic

[cacieprins]

Does this change in behavior fix something? Before, onAfterScreenshot would be invoked while animations were still paused.

[adamalston]

Yes, it was intended to address an issue. With the original ordering, onAfterScreenshot runs while Cypress still has timers paused and animations disabled, so callback code appears to see a temporary screenshot state rather than the restored page state.

I've reverted the change because it introduces a behavior change that is separate from the main screenshot fix in this pull request.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit e3987aa. Configure here.}