How to Configure Cypress: Setup and Configuration Guide

To configure Cypress, create or edit the cypress.config.js file in your project root to set base URL, test folder, and other options. Run npx cypress open or npx cypress run to start tests with your configuration applied.

Syntax

The main configuration file for Cypress is cypress.config.js. It exports a configuration object with properties like e2e for end-to-end test settings, baseUrl to set the default URL for tests, and viewportWidth and viewportHeight to control browser size.

Inside e2e, you specify specPattern to tell Cypress where your test files are located, and supportFile to include reusable commands or setup code.

javascript

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',
    specPattern: 'cypress/e2e/**/*.cy.js',
    supportFile: 'cypress/support/e2e.js',
    viewportWidth: 1280,
    viewportHeight: 720
  }
})

Example

This example shows a basic cypress.config.js file that sets the base URL to http://localhost:3000, looks for test files in cypress/e2e, and sets the browser viewport size. Running npx cypress open will launch the Cypress Test Runner with these settings.

javascript

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',
    specPattern: 'cypress/e2e/**/*.cy.js',
    supportFile: 'cypress/support/e2e.js',
    viewportWidth: 1280,
    viewportHeight: 720
  }
})

Output

Cypress Test Runner opens with configured baseUrl http://localhost:3000 and viewport 1280x720

Common Pitfalls

• Wrong file name or location: The config file must be named cypress.config.js and placed in the project root.
• Incorrect spec pattern: If specPattern does not match your test files, Cypress won't find tests to run.
• Forgetting to restart Cypress: Changes to the config file require restarting the test runner to take effect.
• Using deprecated config keys: Use the latest Cypress config format with defineConfig to avoid warnings.

javascript

/* Wrong way: old config format */
module.exports = {
  baseUrl: 'http://localhost:3000',
  integrationFolder: 'cypress/integration'
}

/* Right way: new config format */
const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',
    specPattern: 'cypress/e2e/**/*.cy.js'
  }
})

Quick Reference

Here is a quick cheat sheet for common Cypress config options:

Option	Description	Example
baseUrl	Default URL for tests	'http://localhost:3000'
specPattern	Glob pattern for test files	'cypress/e2e/**/*.cy.js'
supportFile	Path to support file with commands	'cypress/support/e2e.js'
viewportWidth	Browser width in pixels	1280
viewportHeight	Browser height in pixels	720
video	Record video of test runs	true or false
defaultCommandTimeout	Timeout for commands in ms	4000

Key Takeaways

Create or update cypress.config.js in your project root to configure Cypress.

Use the defineConfig function to export your configuration object.

Set baseUrl and specPattern to tell Cypress where to run tests and which files to use.

Restart Cypress Test Runner after changing the config file to apply updates.

Avoid deprecated config keys and follow the latest Cypress config format.