When a project is added to Cypress, a cypress.json file is created in the project. This file is used to store the projectId (after configuring your tests to record) and any configuration values you supply.

{
  "projectId": "jd90q7"
}

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

Option	Default	Description
`baseUrl`	`null`	URL used as prefix for `cy.visit()` or `cy.request()` command’s URL
`env`	`{}`	Any values to be set as environment variables
`ignoreTestFiles`	`*.hot-update.js`	A String or Array of glob patterns used to ignore test files that would otherwise be shown in your list of tests. Cypress uses `minimatch` with the options: `{dot: true, matchBase: true}`. We suggest using http://globtester.com to test what files would match.
`numTestsKeptInMemory`	`50`	The number of tests for which snapshots and command data are kept in memory. Reduce this number if you are experiencing high memory consumption in your browser during a test run.
`port`	`null`	Port used to host Cypress. Normally this is a randomly generated port
`reporter`	`spec`	The reporter used during `cypress run`
`reporterOptions`	`null`	The reporter options used. Supported options depend on the reporter.
`testFiles`	`*/.*`	A String glob pattern of the test files to load
`watchForFileChanges`	`true`	Whether Cypress will watch and restart tests on test file changes

Timeouts

Core Concept
Timeouts are a core concept you should understand well. The default values listed here are meaningful.

Option	Default	Description
`defaultCommandTimeout`	`4000`	Time, in milliseconds, to wait until most DOM based commands are considered timed out
`execTimeout`	`60000`	Time, in milliseconds, to wait for a system command to finish executing during a `cy.exec()` command
`taskTimeout`	`60000`	Time, in milliseconds, to wait for a task to finish executing during a `cy.task()` command
`pageLoadTimeout`	`60000`	Time, in milliseconds, to wait for `page transition events` or `cy.visit()`, `cy.go()`, `cy.reload()` commands to fire their page `load` events. Network requests are limited by the underlying operating system, and may still time out if this value is increased.
`requestTimeout`	`5000`	Time, in milliseconds, to wait for an XHR request to go out in a `cy.wait()` command
`responseTimeout`	`30000`	Time, in milliseconds, to wait until a response in a `cy.request()`, `cy.wait()`, `cy.fixture()`, `cy.getCookie()`, `cy.getCookies()`, `cy.setCookie()`, `cy.clearCookie()`, `cy.clearCookies()`, and `cy.screenshot()` commands

Folders / Files

Option	Default	Description
`fileServerFolder`	root project folder	Path to folder where application files will attempt to be served from
`fixturesFolder`	`cypress/fixtures`	Path to folder containing fixture files (Pass `false` to disable)
`integrationFolder`	`cypress/integration`	Path to folder containing integration test files
`pluginsFile`	`cypress/plugins/index.js`	Path to plugins file. (Pass `false` to disable)
`screenshotsFolder`	`cypress/screenshots`	Path to folder where screenshots will be saved from `cy.screenshot()` command or after a test fails during `cypress run`
`supportFile`	`cypress/support/index.js`	Path to file to load before test files load. This file is compiled and bundled. (Pass `false` to disable)
`videosFolder`	`cypress/videos`	Path to folder where videos will be saved during `cypress run`

Screenshots

Option	Default	Description
`screenshotsFolder`	`cypress/screenshots`	Path to folder where screenshots will be saved from `cy.screenshot()` command or after a test fails during `cypress run`
`trashAssetsBeforeRuns`	`true`	Whether Cypress will trash assets within the `screenshotsFolder` and `videosFolder` before tests run with `cypress run`.

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

Videos

Option	Default	Description
`trashAssetsBeforeRuns`	`true`	Whether Cypress will trash assets within the `screenshotsFolder` and `videosFolder` before tests run with `cypress run`.
`videoCompression`	`32`	The quality setting for the video compression, in Constant Rate Factor (CRF). The value can be `false` to disable compression or a value between `0` and `51`, where a lower value results in better quality (at the expense of a higher file size).
`videosFolder`	`cypress/videos`	Where Cypress will automatically save the video of the test run when tests run with `cypress run`.
`video`	`true`	Whether Cypress will capture a video of the tests run with `cypress run`.
`videoUploadOnPasses`	`true`	Whether Cypress will process, compress, and upload videos to the Dashboard even when all tests in a spec file are passing. This only applies when recording your runs to the Dashboard. Turn this off if you’d like to only upload the spec file’s video when there are failing tests.

Browser

Option	Default	Description
`chromeWebSecurity`	`true`	Whether Chrome Web Security for `same-origin policy` and `insecure mixed content` is enabled. Read more about this here
`userAgent`	`null`	Enables you to override the default user agent the browser sends in all request headers. User agent values are typically used by servers to help identify the operating system, browser, and browser version. See User-Agent MDN Documentation for example user agent values.
`blacklistHosts`	`null`	A String or Array of hosts that you wish to block traffic for. Please read the notes for examples on using this.
`modifyObstructiveCode`	`true`	Whether Cypress will search for and replace obstructive JS code in `.js` or `.html` files. Please read the notes for more information on this setting.

Viewport

Option	Default	Description
`viewportHeight`	`660`	Default height in pixels for the application under tests’ viewport (Override with `cy.viewport()` command)
`viewportWidth`	`1000`	Default width in pixels for the application under tests’ viewport. (Override with `cy.viewport()` command)

Animations

Option	Default	Description
`animationDistanceThreshold`	`5`	The distance in pixels an element must exceed over time to be considered animating
`waitForAnimations`	`true`	Whether to wait for elements to finish animating before executing commands

Overriding Options

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

This gives you the option to do things like override the baseUrl or environment variables.

Command Line

When running Cypress from the Command Line you can pass a --config flag.

Examples:

cypress open --config watchForFileChanges=false,waitForAnimations=false

cypress run --config integrationFolder=tests,fixturesFolder=false

cypress run --record --config viewportWidth=1280,viewportHeight=720

Plugins

As of 1.2.0 you can programmatically modify configuration values using Node code. This enables you to do things like use fs and read off configuration values and dynamically change them.

While this may take a bit more work than other options - it yields you the most amount of flexibility and the ability to manage configuration however you’d like.

We’ve fully documented how to do this here.

Environment Variables

You can also use environment variables to override configuration values. 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.

By default, any environment variable that matches a corresponding configuration key will override the cypress.json value.

export CYPRESS_VIEWPORT_WIDTH=800

export CYPRESS_VIEWPORT_HEIGHT=600

We automatically normalize both the key and the value. Cypress will strip off the CYPRESS_, camelcase any keys and automatically convert values into Number or Boolean. Make sure to prefix your environment variables with CYPRESS_ else they will be ignored.

Both options below are valid

export CYPRESS_pageLoadTimeout=100000

export CYPRESS_PAGE_LOAD_TIMEOUT=100000

Environment variables that do not match configuration keys will instead be set as regular environment variables for use in your tests with Cypress.env().

You can read more about Environment Variables.

`Cypress.config()`

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

Scope
Configuration set using Cypress.config is only in scope for the current spec file.

Cypress.config('pageLoadTimeout', 100000)

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

Resolved Configuration

When you open a Cypress project, clicking on the Settings tab will display the resolved configuration to you. This makes it easy to understand and see where different values came from.

Notes

blacklistHosts

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 blacklist a host:

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

Not sure what a part of the URL a host is? Use this guide as a reference.

When blacklisting a host, we use minimatch to check the host. When in doubt you can test whether something matches yourself.

Given the following URLs:

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

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

This would match the following blacklisted 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.

Subdomains
Be cautious for URL’s which have no subdomain.

For instance given a URL: https://google.com/search?q=cypress

Matches google.com

Matches *google.com

Does NOT match *.google.com

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-blacklist-host header so you can see which rule it matched.

Network tab of dev tools with analytics.js request selected and the response header 'x-cypress-matched-blacklisted-host: www.google-analytics.com' highlighted

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 the following patterns.

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.

Intelligent Code Completion

IntelliSense is available for Cypress while editing your cypress.json file. Learn how to set up Intelligent Code Completion.