How to setup Cypress environment with Typescript

Testing is always the best way to make sure that everything in your application is working as it should (even after fixes or new features).

Unit tests are so useful, but when it comes to testing a whole flow or bigger functionalities, end-to-end tests are most suitable. In this tutorial, I will help you to setup a Cypress environment with Typescript, create custom commands and use Cypress Testing Library.

Install

First, you should add cypress to the application you want.

yarn add cypress --dev

(or with npm, if you prefer)

Now, we still need open it for the first time to config. You need to add a new script in your package.json and run in your terminal. It's very important to run, because it will generate a lot of files in your app.

root/package.json

"cy:open": "cypress open"

This will open the cypress interface and create a cypress folder and cypress.json file. As you can see, there are some example tests (in cypress/integration) and a lot of default configs. cypress/integration is the folder you can create your tests.

Config

Typescript

The first thing we need to do is creating a tsconfig.json file inside the cypress folder and paste this

cypress/tsconfig.json

{
    "compilerOptions": {
        "target": "ES5",
        "lib": ["es5", "dom"],
        "types": ["cypress"]
    },
    "include": ["**/*.ts"]
}

At this time, you should restart your Typescript server. If you're in VSCode just type:

1. ctrl + shift + P
2. restart TS server.

In cypress/support folder, you see commands.js file and index.js file. Rename to typescript extension.

cypress/support

commands.js -> commands.ts
index.js -> index.ts

Create an index.d.ts file in this same folder (cypress/support). This will be important to create custom commands - very useful!. Add this to index.d.ts file:

cypress/support/index.d.ts

/// <reference types="cypress" />

declare namespace Cypress {
    interface Chainable {

    }
}

Now, we have to update root/tsconfig.json by adding "cypress" to exclude.

root/tsconfig.json

"exclude": ["cypress", "node_modules"]

The config is almost done, now, we just have to this to the root/cypress.json

cypress.json

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

Testing Library

Once we configured Typescript, now it's time to add improve our environment. First, we need to add the Cypress Testing Library. It allows us to use commands from testing library.

Just run in your terminal

yarn add @testing-library/cypress @types/cypress jest @types/jest -D 

After this, is necessary to add these commands to our environment. Add this to the commands.ts file.

cypress/support/commands.ts

import "@testing-library/cypress/add-commands";

And add this line to the cypress/tsconfig.json file, so it can identify the library.

cypress/tsconfig.json

"types": ["cypress", "@testing-library/cypress"]

Creating custom commands

This is actually the most cool thing, in my opinion, about Cypress. We can create custom commands like:

cy.google() - and then the test visit the google page
cy.login() - and then you login in your application

Literally anything you want. What we always need to do is:

1. Create the command in cypress/support/commands.ts
2. Type the command in cypress/support/index.d.ts

Sometimes, error may be generated, just restart TS server and everything is ok again.

Let's create our first command: cy.google() will visit google.

cypress/support/commands.ts

import "@testing-library/cypress/add-commands";

Cypress.Commands.add("google", () => cy.visit("https://www.google.com"));

Typing our new command
cypress/support/index.d.ts

/// <reference types="cypress" />

declare namespace Cypress {
    interface Chainable {
        /**
         * Custom command to visit google page
         * @example cy.google()
         */
        google (): Chainable<Window>
    }
}

Now you can use cy.google() in any test you want :)

Let's create an example test.

Create an example.ts file in cypress/integration folder.

Since we're using custom commands, we need to reference in every test file!

This is my example.ts file:

/// <reference path="../support/index.d.ts" />

describe('Cypress TS', () => {
    it('should visit Google', () => {
        cy.google();
    })
}) 

You can also add the cypress run command to your scripts, this is a way to run cypress tests without open the default item.

Extra

Creating getByDataCy() command

This command is very useful, since we have to get by data-cy a lot of times in cypress.

commands.ts

Cypress.Commands.add("getByDataCy", (selector, ...args) => {
  return cy.get(`[data-cy="${selector}"]`, ...args);
});

index.d.ts

/**
* Custom command to get element by data-cy value
* @example cy.getByDataCy('selector')
*/
getByDataCy (selector: string): Chainable<Window>

Conclusion

My goal was helping you to setup your cypress environment, you can search and learn about cypress and all its features later. There are a lot of things to see.

Thanks for reading :)