Skip to main content
Skip table of contents

Upgrade guide for Cypress

Cypress is under active development, and the Cypress development team has been releasing regular changes to the tool. Minor version are released every few weeks, while major versions are released a few times per year. This guide documents our approach to upgrading Cypress consistently so that potential issues with upgrades are adequately addressed and to keep you informed of any relevant changes to Cypress.

Minor version updates

Currently, minor version updates of Cypress are released roughly once every few weeks. Historically, minor versions have fixed bugs and occasionally introduced new features. Minor versions typically do not introduce any potential breaking changes to tests such as test syntax changes.

In vets-website and content-build, Cypress can be upgraded through yarn:

  •  yarn upgrade cypress@latest --dev.

After installing the update, at least one Cypress test should be run locally, and the entire test suite will run in GitHub Actions. If any new test failures emerge as part of the upgrade, they should be fixed, or the teams that own the tests should be notified. Cypress' changelog includes a list of changes included with the minor version release, so any test failures should be inspected to see if they are related to these changes.

It is unlikely that minor versions will include significant changes such as major deprecations; however, if this is the case then the major version update guide should be followed.

Major version updates

Major version updates to Cypress typically come with significant changes to functionality, new features, deprecated methods, and other changes. Additional testing and communication is required to ensure Cypress is updated without issues.

The process for updating to a new major version is the same as described in the minor version update section. The major version should be tested locally and in GitHub Actions to check for regressions. Additionally, tests may have to be inspected to see if they contain deprecated methods and other significant changes from the major update.

Major version upgrades should be tested in the daily accessibility scan as well. This page describes how to run the daily accessibility manually for testing purposes. (Users who aren’t on Platform teams may be unable to view this document.)

Due to the significant changes that come with major versions, Cypress has a migration guide that helps with the transition. The key changes from this guide should be communicated to engineering teams:

  • A migration guide should be provided that covers key changes engineers should be aware of

  • If there are any deprecations, these should be mentioned in the migration guide.

  • The guide should be shared with all engineering teams before the update is merged to main.

  • If necessary, teams should be given sufficient notice of changes that may impact testing.

  • After sharing the migration guide, the update can be merged to main.

  • After merging, tests should be monitored to check for new issues. Cypress' migration guides are not comprehensive and may omit breaking changes.

Additional resources

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.