Cypress: Migrating from 9.x to 10.x manually

In this article, Im going to share step-by-step how to properly manually upgrade Cypress within your Node.js applications from 9.x (9.5.4) to 10.x (10.0.3)

If you’re using cucumber feature format for your tests, here is a good migration guide for the same.

Step 1. Update package.json

Before we start with the Cypress code itself, let’s first update the npm cypress version to 10.x. Just update this line in your package.json

...
"cypress": "9.5.4",
...

to (or any 10.x version you want)

...
"cypress": "10.0.3",
...

and run npm install to auto update your package-lock.json.

After doing Step1, you can optionally use Cypress Migration Helper which automatically takes care of Step 2 and 3. If you wish to do that, you can open the test runner (cypress open) and click on the “Continue to Cypress 10” button to do the necessary changes. If you are doing this, you can skip directly to Step 4

Step 2. Update Cypress config file

You might currently have cypress.json as your config file. This has been now replaced with cypress.config.js or cypress.config.ts . They have also removed the plugin file and the contents of the old cypress/plugins/index.js has been also moved to the cypress.config.js .

So, if your old cypress.json content was:

{
  "baseUrl": "http://localhost:3300",
  "video": false
}

Your new file named cypress.config.js (or .ts) would have something like:

const { defineConfig } = require('cypress')
module.exports = defineConfig({
  video: false,
  e2e: {
    baseUrl: 'http://localhost:3300',
    setupNodeEvents(on, config) {
      on('<event>', (arg1, arg2) => {
        // plugin stuff here
      })
    }
  }
})

You can delete your cypress/plugins/index.js file.

Step 3. Updating Cypress file names and extensions

Cypress has changed the default spec folder from integration to e2e . So what we need to do is:

• rename the old integration folder to e2e
• rename all the test/spec file extension from .js to .cy.js
• rename the Cypress support file from old support/index.js to support/e2e.js

So after the changes, an example test file

cypress/integration/user/add-user.js

will now become

cypress/e2e/user/add-user.cy.js

and the support file will now become

cypress/support/e2e.js

If you are using the Cypress Migration Helper, please note it sometimes does not update the spec file extension properly to .cy.js. In which case you can manually renaming the spec files as suggested above.

Step 4. Update cypress open command

In 9.x and earlier versions, cypress open would bring you directly to the project specs list. In 10.x, you would have to pass --browserand--e2e or --component to launch Cypress directly to the specs list.

So, a command like:

"test:cypress:open": "cypress open"

will now become

"test:cypress:open": "cypress open --e2e --browser chrome"

Conclusion

You can refer to the Cypress Migration Guide to get a good picture of the recent changes made to 10.x

Hope this was helpful !