Cypress 12: New Features, Changes & Migration

Cypress 12, released in December 2022, introduces experimental web vitals tracking, a new custom reporter API, and removes the deprecated cy.route() command. This article covers the key feature additions, breaking changes, and a step-by-step migration guide for existing test suites.

Background: What Led to Cypress 12

Cypress 12 builds on the architectural shift started in Cypress 10, which introduced the new cy.session() API and the component testing runner. The 12.x line focuses on improving performance insights and making the test runner more extensible. The Cypress team also continued to align the open-source Cypress with the paid Cypress Cloud service, though all features discussed here are available in the free, open-source version.

New Features in Cypress 12

1. Experimental Web Vitals

Cypress 12 adds an experimental cy.webVitals() command that captures Core Web Vitals (LCP, CLS, FID, TTFB, INP) during a test. To enable it, set experimentalWebVitals: true in your Cypress config. The command returns a report object you can assert on, for example:

cy.webVitals().then((report) => {
  expect(report.lcp).to.be.lessThan(2500);
});

This helps teams catch performance regressions before they reach production.

2. Custom Reporter API

Previously, custom reporters had to be npm packages. Cypress 12 lets you define a reporter directly in your config file using a function. This simplifies integration with internal dashboards:

reporter: (results) => {
  console.log(`Tests passed: ${results.passes}`);
}

3. Improved Retry Logic

The retries option now supports a more granular openMode and runMode configuration, and retry attempts are better logged in the runner.

Breaking Changes in Cypress 12

• Removal of cy.route(): The legacy cy.route() API was removed. Use cy.intercept() instead, which has been available since Cypress 6.
• Node.js version requirement: Cypress 12 requires Node.js 14 or newer. Node 12 is no longer supported.
• TypeScript minimum: If you use TypeScript, the minimum supported version is now 4.2.
• Removal of Cypress.Buffer: The Cypress.Buffer helper was removed; use the native Buffer from Node.js.

Migration Notes: Upgrading from Cypress 11 or Earlier

1. Update the package: Run npm install --save-dev cypress@12 or yarn add --dev cypress@12.
2. Replace cy.route(): Search your specs for cy.route( and replace with cy.intercept(. The syntax is similar but cy.intercept() uses a URL pattern or matcher. For example, cy.route('GET', '/users') becomes cy.intercept('GET', '/users').
3. Update Node.js: Ensure your CI and local environment use Node.js 14 or higher.
4. Check TypeScript: If you use TypeScript, update to at least 4.2.
5. Review removed commands: Run your tests and check for any usage of Cypress.Buffer or other deprecated APIs.

Common Problems After Upgrading

• Tests fail with cy.route is not a function: This means you haven’t replaced all instances. Use find-and-replace.
• Web Vitals not working: Ensure you have set experimentalWebVitals: true and that your app is served over HTTP/2 (the command uses the PerformanceObserver API).
• Custom reporter not loading: If you used a string path, switch to a function or update the package to be compatible with the new API.

How to Choose Between Cypress 12 and Cypress 13

Cypress 13 was released in 2023 and includes additional features like test filtering and better component testing. If you are starting a new project, consider the latest stable version. For existing projects on Cypress 11 or earlier, migrating to 12 is a necessary intermediate step before jumping to 13, as the migration path is smoother.

Frequently Asked Questions

Is Cypress 12 free?

Yes, Cypress 12 is open-source and free to use. The Cypress Cloud service (formerly Cypress Dashboard) is paid, but all the features mentioned in this article are part of the free test runner.

Can I still use cy.route() in Cypress 12?

No. cy.route() was removed in Cypress 12. You must use cy.intercept() for stubbing and mocking network requests. The migration is straightforward, and the Cypress documentation provides a guide.

How do I enable web vitals in Cypress 12?

Add experimentalWebVitals: true to your cypress.config.js file. Then use cy.webVitals() in your tests. Note that this is experimental and may change in future versions.

What Node.js version do I need for Cypress 12?

Cypress 12 requires Node.js 14 or higher. If you are using an older version, upgrade Node.js before installing Cypress 12.

Will my existing Cypress 10 tests work in Cypress 12?

Most tests will work, but you need to replace any usage of cy.route() and ensure your Node.js version meets the requirement. The Cypress team provides a migration guide for each major version.

Does Cypress 12 support component testing?

Yes, component testing is fully supported in Cypress 12, with the same API as in Cypress 10 and 11. The experimental web vitals feature also works in component tests.

Related

• Arc Raiders: What Comes Around, Finish What Goes Around
• New iPod Touch Guide: Setup, Features & Tips
• S25 Ultra Qi2 Wireless Charging: Too Little, Too Late?

in t | Finish time | min | 50 | 0
in d | Distance | km | 10 | 0
out pace | Average pace | min/km | t / d | 2
out speed | Average speed | km/h | d / (t / 60) | 2