Configuration

Configuration file

The first time you open Cypress Test Runner, it creates the cypress.config.js configuration file. This Javascript file is used to store any configuration values you supply. If you configure your tests to record the results to the Cypress Dashboard the projectId will be written in this file too.

Alternately, Cypress supports a TypeScript cypress.config.ts configuration file, and a (deprecated) cypress.json configuration file.

Intelligent Code Completion

The defineConfig helper function is exported by Cypress, and it provides automatic code completion for configuration in many popular code editors. While it's not strictly necessary for Cypress to parse your configuration, we recommend wrapping your config object with defineConfig() like this:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  baseUrl: 'http://localhost:1234'
})

import { defineConfig } from 'cypress'

export default defineConfig({
  baseUrl: 'http://localhost:1234'
})

Options

The default behavior of Cypress can be modified by supplying any of the following configuration options. Below is a list of available options and their default values.

Global

Timeouts

Folders / Files

Screenshots

For more options regarding screenshots, view the Cypress.Screenshot API.

Videos

Downloads

Browser

Viewport

Actionability

For more information, see the docs on actionability.

Node version

The Node version is used in Cypress to:

• Build files in the supportFile.
• Execute code in the pluginsFile.

Experiments

Configuration might include experimental options currently being tested. See Experiments page.

Runner Specific Options

You can provide configuration options for either the E2E or Component Testing runners by creating e2e and component objects inside your Cypress configuration.

e2e

These options are available to be specified inside the e2e configuration object:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    // e2e options here
  }
})

import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    // e2e options here
  }
})

component

These options are available to be specified inside the component configuration object:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  component: {
    // component options here
  }
})

import { defineConfig } from 'cypress'

export default defineConfig({
  component: {
    // component options here
  }
})

Overriding Options

Cypress gives you the option to dynamically alter configuration options. This is helpful when running Cypress in multiple environments and on multiple developer machines.

Command Line

When running Cypress from the command line you can pass a --config flag to override individual config options or a --config-file flag to specify an entirely different configuration file.

For example:

cypress run --browser firefox --config viewportWidth=1280,viewportHeight=720

cypress run --config-file tests/cypress.config.js

See the Command Line guide for more examples.

Runner Specific Overrides

In addition to setting Runner Specific Options, you can override other configuration options for either the E2E or Component Testing runners.

For example:

const { defineConfig } = require('cypress')

const { devServer } = require('@cypress/webpack-dev-server')

module.exports = defineConfig({
  // These settings apply everywhere unless overridden
  defaultCommandTimeout: 5000,
  viewportWidth: 1000,
  viewportHeight: 600,
  // Viewport settings overridden for component tests
  component: {
    devServer,
    viewportWidth: 500
    viewportHeight: 500
  },
  // Command timeout overridden for E2E tests
  e2e: {
    defaultCommandTimeout: 10000
  }
})

import { defineConfig } from 'cypress'

const { devServer } = require('@cypress/webpack-dev-server')

export default defineConfig({
  // These settings apply everywhere unless overridden
  defaultCommandTimeout: 5000,
  viewportWidth: 1000,
  viewportHeight: 600,
  // Viewport settings overridden for component tests
  component: {
    devServer,
    viewportWidth: 500
    viewportHeight: 500
  },
  // Command timeout overridden for E2E tests
  e2e: {
    defaultCommandTimeout: 10000
  }
})

Environment Variables

Configuration options can be overridden with environment variables. This is especially useful in Continuous Integration or when working locally. This gives you the ability to change configuration options without modifying any code or build scripts.

For example, these enviroment variables in the command line will override any viewportWidth or viewportHeight options set in the Cypress configuration:

export CYPRESS_VIEWPORT_WIDTH=800
export CYPRESS_VIEWPORT_HEIGHT=600

See the Environment Variables guide for more examples.

Test Configuration

We provide two options to override the configuration while your test are running, Cypress.config() and suite-specific or test-specific configuration overrides.

• animationDistanceThreshold
• baseUrl
• browser note: filters whether the tests or a suite of tests runs depending on the current browser
• defaultCommandTimeout
• execTimeout
• env note: Provided environment variables will be merged with current environment variables.
• includeShadowDom
• keystrokeDelay
• requestTimeout
• responseTimeout
• retries
• scrollBehavior
• slowTestThreshold
• viewportHeight
• viewportWidth
• waitForAnimations

Cypress.config()

You can also override configuration values within your test using Cypress.config().

This changes the configuration for the remaining execution of the current spec file. The values will reset to the previous default values after the spec has complete.

Cypress.config('pageLoadTimeout', 100000)

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

Test-specific Configuration

To apply specific Cypress configuration values to a suite or test, pass a configuration object to the test or suite function as the second argument.

The configuration values passed in will only take effect during the suite or test where they are set. The values will then reset to the previous default values after the suite or test is complete.

Syntax

describe(name, config, fn)
context(name, config, fn)
it(name, config, fn)
specify(name, config, fn)

Suite configuration

If you want to target a suite of tests to run or be excluded when run in a specific browser, you can override the browser configuration within the suite configuration. The browser option accepts the same arguments as Cypress.isBrowser().

You can configure the number of times to retries a suite of tests if they fail during cypress run and cypress open separately.

describe(
  'login',
  {
    retries: {
      runMode: 3,
      openMode: 2,
    },
  },
  () => {
    it('should redirect unauthenticated user to sign-in page', () => {
      // ...
    })

    it('allows user to login', () => {
      // ...
    })
  }
)

Single test configuration

If you want to target a test to run or be excluded when run in a specific browser, you can override the browser configuration within the test configuration. The browser option accepts the same arguments as Cypress.isBrowser().

it('Show warning outside Chrome', { browser: '!chrome' }, () => {
  cy.get('.browser-warning').should(
    'contain',
    'For optimal viewing, use Chrome browser'
  )
})

Resolved Configuration

When you open a Cypress project, clicking on the Settings tab will display the resolved configuration to you. This helps you to understand and see where different values came from. Each set value is highlighted to show where the value has been set via the following ways:

• Default value
• Cypress configuration file
• The Cypress environment file
• System environment variables
• Command Line arguments
• Plugins file

Notes

blockHosts

By passing a string or array of strings you can block requests made to one or more hosts.

To see a working example of this please check out our Stubbing Google Analytics Recipe.

To block a host:

• Pass only the host
• Use wildcard * patterns
• Include the port other than 80 and 443
• Do NOT include protocol: http:// or https://

Given the following URLs:

https://www.google-analytics.com/ga.js

http://localhost:1234/some/user.json

This would match the following blocked hosts:

www.google-analytics.com
*.google-analytics.com
*google-analytics.com

localhost:1234

Because localhost:1234 uses a port other than 80 and 443 it must be included.

When Cypress blocks a request made to a matching host, it will automatically send a 503 status code. As a convenience it also sets a x-cypress-matched-blocked-host header so you can see which rule it matched.

devServer / devServerConfig

The devServer function is a required component runner specific option, and allows you to register a component testing dev server. It receives a cypressDevServerConfig argument which is passed to the dev server module.

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  component: {
    devServer(cypressDevServerConfig) {
      // start dev server here
    },
  },
})

import { defineConfig } from 'cypress'

export default defineConfig({
  component: {
    devServer(cypressDevServerConfig) {
      // start dev server here
    },
  },
})

The devServerConfig object is optional and specific to the dev server that you've specified. If provided, it will be passed into the devServer function as the second argument.

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  component: {
    devServer(cypressDevServerConfig, devServerConfig) {
      // this ^ devServerConfig is the same as the one below
    },
    devServerConfig: {/* optional config object */},
  },
})

import { defineConfig } from 'cypress'

export default defineConfig({
  component: {
    devServer(cypressDevServerConfig, devServerConfig) {
      // this ^ devServerConfig is the same as the one below
    },
    devServerConfig: {/* optional config object */},
  },
})

See the component testing framework configuration guide for specific examples.

firefoxGcInterval

Firefox versions 79 and earlier have a bug where it does not run its internal garbage collection (GC) fast enough, which can lead to consuming all available system memory and crashing.

Cypress prevents Firefox from crashing by forcing Firefox to run its GC cleanup routines between tests.

Running GC is an expensive and blocking routine. It adds significant time to the overall run, and causes Firefox to "freeze" for the duration of GC cleanup. This causes the browser not to respond to any user input.

Cypress runs GC cleanup during cypress run only because we don't expect users to interact with the browser - since this is typically run in CI. We've disabled running GC during cypress open because users typically interact with the browser.

Because GC adds additional time to the overall run, we've added the amount of time this routine has taken to the bottom of the Command Log in the Test Runner.

Configuration

You can control how often GC cleanup runs via the firefoxGcInterval configuration value.

firefoxGcInterval controls whether Cypress forces Firefox to run GC cleanup and how frequently.

By default, we force GC cleanup between every test during cypress run, but do not run any GC cleanup during cypress open using the configuration below:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  firefoxGcInterval: {
    runMode: 1,
    openMode: null
  }
})

import { defineConfig } from 'cypress'

export default defineConfig({
  firefoxGcInterval: {
    runMode: 1,
    openMode: null
  }
})

You can override how often Cypress runs GC cleanup by setting the firefoxGcInterval config value to:

• null, to disable it for both cypress run and cypress open
• a number, which sets the interval for both cypress run and cypress open
• an object to set different intervals for each mode

Examples

Turn off GC cleanup all modes

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  firefoxGcInterval: null
})

import { defineConfig } from 'cypress'

export default defineConfig({
  firefoxGcInterval: null
})

Run GC cleanup before every other test during cypress run and cypress open

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  firefoxGcInterval: 2
})

import { defineConfig } from 'cypress'

export default defineConfig({
  firefoxGcInterval: 2
})

Run GC cleanup before every 3rd test during cypress run and disable running GC cleanup during cypress open.

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  firefoxGcInterval: {
    runMode: 3,
    openMode: null
  }
})

import { defineConfig } from 'cypress'

export default defineConfig({
  firefoxGcInterval: {
    runMode: 3,
    openMode: null
  }
})

isInteractive

You can open Cypress in the interactive mode via the cypress open command, and in run mode via the cypress run command. To detect the mode from your test code you can query the isInteractive property on Cypress.config.

if (Cypress.config('isInteractive')) {
  // interactive "cypress open" mode!
} else {
  // "cypress run" mode
}

modifyObstructiveCode

With this option enabled - Cypress will search through the response streams coming from your server on .html and .js files and replace code that matches patterns commonly found in framebusting.

These script patterns are antiquated and deprecated security techniques to prevent clickjacking and framebusting. They are a relic of the past and are no longer necessary in modern browsers. However many sites and applications still implement them.

These techniques prevent Cypress from working, and they can be safely removed without altering any of your application's behavior.

Cypress modifies these scripts at the network level, and therefore there is a tiny performance cost to search the response streams for these patterns.

You can turn this option off if the application or site you're testing does not implement these security measures. Additionally it's possible that the patterns we search for may accidentally rewrite valid JS code. If that's the case, please disable this option.

setupNodeEvents

The setupNodeEvents function allows you to tap into, modify, or extend the internal behavior of Cypress using the on and config arguments, and is valid as an e2e or component runner specific option.

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      // e2e testing node events setup code
    },
  },
  component: {
    setupNodeEvents(on, config) {
      // component testing node events setup code
    },
  },
})

import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      // e2e testing node events setup code
    },
  },
  component: {
    setupNodeEvents(on, config) {
      // component testing node events setup code
    },
  },
})

See the plugins guide for more information.

Common problems

baseUrl is not set

Make sure you do not accidentally place the baseUrl or another top-level config option into the env object. The following configuration is incorrect and will not work:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  // ⛔️ DOES NOT WORK
  env: {
    baseUrl: 'http://localhost:3030',
    FOO: 'bar'
  }
})

import { defineConfig } from 'cypress'

export default defineConfig({
  // ⛔️ DOES NOT WORK
  env: {
    baseUrl: 'http://localhost:3030',
    FOO: 'bar'
  }
})

Solution: place the baseUrl property at the top level, outside the env object.

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  // ✅ THE CORRECT WAY
  baseUrl: 'http://localhost:3030',
  env: {
    FOO: 'bar'
  }
})

import { defineConfig } from 'cypress'

export default defineConfig({
  // ✅ THE CORRECT WAY
  baseUrl: 'http://localhost:3030',
  env: {
    FOO: 'bar'
  }
})

You can also find a few tips on setting the baseUrl in this short video.

Test files not found when using spec parameter

When using the --spec <path or mask> argument, make it relative to the project's folder. If the specs are still missing, run Cypress with DEBUG logs with the following setting to see how the Test Runner is looking for spec files:

DEBUG=cypress:cli,cypress:server:specs

History

See also

• Cypress.config() and Cypress.env()
• Environment variables
• Environment Variables recipe
• Extending the Cypress Configuration File blog post and @bahmutov/cypress-extends package.
• Blog post Keep passwords secret in E2E tests