How to install and set up Cypress

Before diving into Cypress installation, it’s essential to understand what you’ll need to set up this powerful testing framework effectively. First, ensure you have Node.js installed on your machine. Cypress relies on Node.js to run, so it’s vital for any JavaScript testing environment.

You can check if Node.js is already installed by running the following command in your terminal:

node -v

If you see a version number, you’re good to go. If not, you’ll need to download and install it from the official Node.js website. Make sure to install the LTS version, which is more stable and suitable for most projects.

Next, you’ll want a package manager like npm or Yarn. npm typically comes bundled with Node.js, but if you prefer Yarn, you can install it separately. This package manager allows you to manage your project dependencies easily.

It’s also wise to have a code editor ready, as you’ll be writing configurations and test scripts. Editors like Visual Studio Code or Atom are excellent choices due to their extensive ecosystem of plugins and support for JavaScript.

Lastly, consider your project’s structure. Cypress works best in a Node.js project that already uses a package.json file. If you’re starting from scratch, you can initialize a new project by running:

npm init -y

This generates a package.json file, setting the stage for you to install Cypress and any other dependencies your project might need later.

Once you’ve confirmed all these prerequisites, you’ll be ready to move on to the actual installation steps, which…

Step-by-step guide to installing Cypress

…are straightforward. To install Cypress, you simply need to use your package manager of choice. If you’re opting for npm, the command is as follows:

npm install cypress --save-dev

This command installs Cypress as a development dependency in your project. The --save-dev flag is essential here, as it tells npm to save Cypress in your devDependencies section of your package.json, making it clear that this tool is only needed during development and testing.

If you’re using Yarn, the installation command would look like this:

yarn add cypress --dev

After executing either of these commands, you should see output indicating that Cypress has been installed successfully. You can verify this by checking the node_modules directory or the package.json file where Cypress should now be listed under devDependencies.

Once installed, the next step is to open Cypress for the first time. You can do this by adding a script to your package.json to make it easier to launch. Modify your scripts section like this:

"scripts": {
  "cypress": "cypress open"
}

Now, you can start Cypress with:

npm run cypress

This command opens the Cypress Test Runner, which is a user-friendly interface for running and managing your tests. At this point, you should see a directory structure created by Cypress, including a cypress folder with subdirectories such as integration, fixtures, and support. Each of these directories serves a specific purpose in organizing your tests, fixtures, and custom commands.

Inside the integration folder, you can start adding your test files. Cypress supports various types of testing, primarily focusing on end-to-end testing, but it also allows for component testing when set up correctly. A simple example of an integration test could look like this:

describe('My First Test', () => {
  it('Does not do much!', () => {
    expect(true).to.equal(true);
  });
});

In this example, we define a test suite using describe and an individual test case with it. The expect assertion is part of Cypress’s built-in Chai assertion library, which allows you to write readable tests. You can add more tests to this file or create new ones in the same directory as your project grows.

Now that Cypress is installed and you’ve set up your first test, it’s time to configure it to fit your testing environment. Cypress provides a configuration file where you can set various options like the base URL for your application, timeouts, and more. This file is typically located at cypress.json in the root of your project. Here’s how you can configure it:

{
  "baseUrl": "http://localhost:3000",
  "defaultCommandTimeout": 10000
}

Setting the baseUrl is particularly useful as it allows you to use relative URLs in your tests instead of hardcoding full URLs, making them more portable. The defaultCommandTimeout setting adjusts the time Cypress waits for commands to complete, which can be helpful if your application has slow responses or heavy loading times.

As you dive deeper into Cypress, you’ll discover many more configuration options that can help tailor the testing experience to suit your project’s specific needs. Understanding these settings will empower you to write more efficient and effective tests, ultimately leading to a more robust application. Next, we will explore how to…

Configuring Cypress for your testing environment

While the cypress.json file is still supported for backward compatibility, modern Cypress projects (version 10 and up) use a cypress.config.js or cypress.config.ts file. The reason for this shift is simple: a JavaScript configuration file is far more powerful. You can dynamically compute configuration values, pull in other Node.js modules, or read from environment variables directly within your config. It’s no longer just a static set of key-value pairs.

When you first run cypress open in a newer project, Cypress will automatically scaffold this configuration file for you. It provides a basic structure to get you started.

const { defineConfig } = require("cypress");

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      // implement node event listeners here
    },
  },
});

Notice the e2e key. This is where you place all configuration specific to your end-to-end tests. For example, the baseUrl we discussed earlier now lives inside this object. Another incredibly useful option is specPattern, which lets you define a glob pattern to tell Cypress where to find your test files. This is great if you don’t want to stick to the default cypress/e2e/**/*.cy.{js,jsx,ts,tsx} pattern.

const { defineConfig } = require("cypress");

module.exports = defineConfig({
  e2e: {
    baseUrl: "http://localhost:8080",
    specPattern: "tests/e2e/**/*.spec.js",
    setupNodeEvents(on, config) {
      // ...
    },
  },
  
  // A global option outside the e2e block
  viewportWidth: 1280,
  viewportHeight: 720,
});

For managing different testing environments, like a local development server versus a staging server, you can leverage the env configuration key. This allows you to store key-value pairs that are accessible within your tests via Cypress.env(). You can define a base set of environment variables in the config file and override them from the command line or your CI server, which is essential for a flexible testing pipeline.

// in cypress.config.js
module.exports = defineConfig({
  // ...
  env: {
    login_url: "/login",
    products_url: "/products",
    api_server: "https://api.staging.example.com"
  },
});

// in your test file
it('should navigate to the login page', () => {
  cy.visit(Cypress.env("login_url"));
  cy.request(Cypress.env("api_server") + "/health").its("status").should("eq", 200);
});

One of the most powerful configuration aspects is extending Cypress with custom commands. This is done in the cypress/support/e2e.js file. Custom commands help you abstract away repetitive sequences of actions into a single, reusable command. A classic example is a custom login command, which keeps your tests DRY (Don’t Repeat Yourself) and much more readable.

// in cypress/support/e2e.js
Cypress.Commands.add('login', (username, password) => {
  cy.session([username, password], () => {
    cy.visit('/login');
    cy.get('input[name="username"]').type(username);
    cy.get('input[name="password"]').type(password);
    cy.get('form').submit();
    cy.url().should('contain', '/dashboard');
  });
});

With that command defined, your tests become much cleaner. Instead of repeating the same login steps in every test that requires an authenticated user, you can simply call your new command. The use of cy.session() here is a modern Cypress best practice that caches the browser session, so you only have to perform the full login once per spec file, dramatically speeding up your test suite.

// in a test file
describe('Dashboard', () => {
  beforeEach(() => {
    cy.login('testuser', 'supersecret');
  });

  it('can view the user profile', () => {
    cy.visit('/dashboard/profile');
    cy.get('h1').should('contain', 'User Profile');
  });

  it('can view account settings', () => {
    cy.visit('/dashboard/settings');
    cy.get('h1').should('contain', 'Account Settings');
  });
});

Finally, the setupNodeEvents function inside your cypress.config.js is your gateway to the back-end of Cypress. Because this function runs in Node.js, you can do things that are impossible in the browser context where your tests run. This includes tasks like connecting to a database to seed or reset test data, running external scripts, or modifying the Cypress configuration before a test run begins. For example, you can use it to log messages to your terminal during test execution via tasks.

// in cypress.config.js
e2e: {
  setupNodeEvents(on, config) {
    on('task', {
      log(message) {
        console.log([TEST LOG] ${message});
        return null;
      },
      seedDatabase(data) {
        // Code to connect to your DB and seed it
        console.log(Seeding database with: ${JSON.stringify(data)});
        return true; // Indicate success
      }
    });
  },
},

// in your test file
it('seeds the database before interacting with the UI', () => {
  cy.task('seedDatabase', { user: 'new_user', role: 'admin' }).should('be.true');
  cy.task('log', 'Database has been seeded.');
  cy.visit('/admin');
  // ... rest of the test
});