Intro to Cypress Configuration

Table of Contents

• Introduction
• Overriding default configuration
  • config
  • env
  • cli
  • dynamic
• Accessing configuration in test files
• Most used configuration items in our experience

Introduction

Effective configuration is the backbone of efficient test automation. It’s the foundation upon which reliable, maintainable, and scalable tests are built. By getting your Cypress configuration right from the start, you’re not only saving time but also ensuring that your test suite remains robust and adaptable as your application evolves.

First, let’s understand where to find the default configuration. To see the configuration the tests are using open your project in the test runner and open the browser. Once the browser is opened, click on “Settings” on the left menu and click on “Project settings”. See the screenshot below:

Then scroll down until you see “Resolved configuration”, similar to the screenshot:

Everything with the light gray background is the default configuration. There are multiple ways to override that:

1. config - cypress.config.js file
2. env - environment variables (also set from cypress.config.js file)
3. cli - command line arguments
4. dynamic - setupNodeEvents function (also in cypress.config.js file)

Note that if the same value is overridden in multiple places, the order is the same as shown above, meaning dynamic is overriding all the rest.

Most of the configuration is changed in the cypress.config.js file. By default the file is quite empty and looks like this:

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

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

Let’s have a closer look on how to change the values on each level.

Overriding default configuration

config

Let’s add a configuration value, e.g baseUrl. Change the code as follows:

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

module.exports = defineConfig({
  e2e: {
    baseUrl: 'https://example.cypress.io/todo',
    setupNodeEvents(on, config) {
      // implement node event listeners here
    },
  },
});

Now the configuration looks like this: Similarily you can change all the configuration values.

env

In case you want to add your own custom configuration values, it might be a good idea to do that in the env variables. This is done in cypress.config.js file in the env object. Let’s add one, email in this example:

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

module.exports = defineConfig({
  e2e: {
    baseUrl: 'https://example.cypress.io/todo',
    env: {
      email: "info@bigbyte.ee"
    },
    setupNodeEvents(on, config) {
      // implement node event listeners here
    },
  },
});

Now the configuration looks like this:

cli

To override configuration using cli you need to open or run the tests via command line. This is not accessible when you use Cypress you got via direct download. All the configuration values can be overriden similarily - when opening or running Cypress tests from command line, you add some flags in the end, e.g:

npx cypress open --config blockHosts="https://click.bait",baseUrl="https://bigbyte.academy"
 

npx cypress run --config blockHosts="https://click.bait",baseUrl="https://bigbyte.academy"

Note that in this example we overwrite 2 configuration items - blockHosts and baseUrl. Similarily you can add multiple other items as needed. The resovled configuration now looks like this: As you can see from the image, the blockHosts now has a new value and the value of baseUrl is overridden with the command line value.

Similarily you can override the values in env object or add new ones, e.g:

npx cypress open --env email="new@email.ee",password="test"

You can also still use the --config flag in parallel with --env.

dynamic

The dynamic configuration values can not be overridden anywhere else. If you add those, be sure you don’t need any other values when running tests from CI for example. To add the dynamic values, you need to add those in the setupNodeEvents function:

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

module.exports = defineConfig({
  e2e: {
    baseUrl: 'https://example.cypress.io/todo',
    env: {
      environment: 'dev',
      email: "info@bigbyte.ee"
    },
    setupNodeEvents(on, config) {
      if(config.env.environment === 'dev'){
        config.env.email = 'dev@email.ee'
        config.baseUrl = 'https://bigbyte.ee'
      } else {
        config.env.email = 'default@email.ee'
        config.baseUrl = 'https://blog.bigbyte.academy'
      }

      return config
    },
  },
});

A new item was added inside the env object - environment. Now in case the enviroment value is ‘dev’, the env.email changes to dev@email.ee and the baseUrl changes to https://bigbyte.ee. Note that even though you can run s command from the command line and add the baseUrl and email, those are not overriden by the values from setupNodeEvents:

npx cypress open --config baseUrl="https://bigbyte.academy" --env email="new@email.ee"

In case environment: ‘dev’:

In case environment: ‘prod’:

Accessing configuration in test files

One of Cypress’s powerful features is its ability to access configuration settings directly from within your test files. This capability allows you to seamlessly integrate configuration into your test logic. By calling Cypress.config(), you can retrieve any configuration value defined in your cypress.config.js file or from other sources. For example, you can access the baseUrl for your application or any custom configuration item you’ve defined. This access opens up endless possibilities, enabling you to dynamically adapt your tests based on the configuration, further enhancing the flexibility and versatility of your Cypress test suite.

You can access all configuration variables inside the test:

Cypress.config('pageLoadTimeout') // => 60000

Custom environment variables:

Cypress.env('email') // => info@bigbyte.ee

You can also override configuration values within your test:

Cypress.config('pageLoadTimeout', 100000) 

Most used configuration items in our experience

There are a lot of possible configuration items to override or to add in Cypress configuration, but here are a few that we’ve used mostly across projects:

• baseUrl - URL used as prefix for cy.visit() or cy.request() command’s URL.
• defaultCommandTimeout - Time, in milliseconds, to wait until most DOM based commands are considered timed out.
• env - custom environment variables
• numTestsKeptInMemory - The number of tests for which snapshots and command data are kept in memory.
• projectId - project ID in Cypress Cloud
• retries - The number of times to retry a failing test.
• userAgent - Enables you to override the default user agent the browser sends in all request headers.
• viewportHeight - Default height in pixels for the application under tests’ viewport.
• viewportWidth - Default width in pixels for the application under tests’ viewport.
• watchForFileChanges - Whether Cypress will watch and restart tests on test file changes.

userAgent, viewportHeight and viewportWidth are very useful when trying to add mobile view testing with Cypress, which we will talk about in a future post.

You can also take a look on the config file in our example project: https://github.com/bigbytecy/bigbyte-example-project/blob/main/cypress.config.js.

Stay tuned for more insights and practical examples to help you maximize the potential of Cypress configuration!