TypeScript

Improve this doc

Cypress ships with official type declarations for TypeScript. This allows you to write your tests in TypeScript. All that is required is a little bit of configuration.

Transpiling TypeScript test files

Just as you would when writing TypeScript files in your project, you will have to handle transpiling your TypeScript test files. Cypress exposes a file:preprocessor event you can use to customize how your test code is transpiled and sent to the browser.

Examples

Set up your dev environment

Please refer to your code editor in TypeScript’s Editor Support doc and follow the instructions for your IDE to get TypeScript support and intelligent code completion configured in your developer environment before continuing. TypeScript support is built in for Visual Studio Code, Visual Studio, and WebStorm - all other editors require extra setup.

Configure tsconfig.json

We recommend the following configuration in a tsconfig.json inside your cypress folder.

{
  "compilerOptions": {
    "strict": true,
    "baseUrl": "../node_modules",
    "target": "es5",
    "lib": ["es5", "dom"],
    "types": ["cypress"]
  },
  "include": [
    "**/*.ts"
  ]
}

The "types" will tell the TypeScript compiler to only include type definitions from Cypress. This will address instances where the project also uses @types/chai or @types/jquery. Since Chai and jQuery are namespaces (globals), incompatible versions will cause the package manager (yarn or npm) to nest and include multiple definitions and cause conflicts.

You can find an example of Jest and Cypress installed in the same project using a separate tsconfig.json file in the cypress-io/cypress-and-jest-typescript-example repo.

Types for custom commands

When adding custom commands to the cy object, you can add their types to avoid TypeScript errors. You can find the simplest implementation of Cypress and TypeScript in this repo example here.

TODO MVC Example Repo

You can find an example in the cypress-example-todomvc custom commands repo.

Types for custom assertions

If you extend Cypress assertions, you can extend the assertion types to make the TypeScript compiler understand the new methods. See the Recipe: Adding Chai Assertions for instructions.

Additional information

See the excellent advice on setting Cypress using TypeScript in the TypeScript Deep Dive e-book by Basarat Syed. Take a look at this video Basarat has recorded and the accompanying repo basarat/cypress-ts.

We have published a utility npm module, add-typescript-to-cypress, that sets TypeScript test transpilation for you with a single command.