Cypress Configuration

Cypress stores its project-wide settings inside a configuration file. This file controls behavior like timeouts, base web addresses, and folder locations. This topic explains the most useful configuration options.

The Configuration File

The cypress.config.js file sits at the root of your project. Cypress generates a basic version of this file during installation.

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    baseUrl: 'https://example.com',
    viewportWidth: 1280,
    viewportHeight: 720
  }
})

A Simple Way to Picture It

Think of the configuration file as the settings menu on a phone. You adjust screen brightness, sound volume, and network options in one central place. Cypress uses its configuration file the same way, controlling test-wide behavior from one location.

Setting a Base URL

The baseUrl option lets you visit pages using short paths instead of full web addresses.

cy.visit('/login')

Without a baseUrl setting, the same line would require the full address, such as https://example.com/login.

Adjusting Timeouts

Cypress waits a limited time for commands and assertions to succeed before marking a test as failed. The default timeout suits most cases, but slow-loading pages sometimes need a longer value.

module.exports = defineConfig({
  defaultCommandTimeout: 8000
})

This setting extends the wait time to eight seconds instead of the default four seconds.

Configuration Options Overview

cypress.config.js
 |
 |-- baseUrl            (starting address for cy.visit)
 |-- viewportWidth       (browser window width)
 |-- viewportHeight      (browser window height)
 |-- defaultCommandTimeout (wait time for commands)
 |-- video               (record test runs or not)

Controlling Viewport Size

The viewportWidth and viewportHeight options set the simulated browser window size during tests. Testing at a smaller viewport helps confirm that a page still works correctly on smaller screens.

module.exports = defineConfig({
  e2e: {
    viewportWidth: 375,
    viewportHeight: 667
  }
})

Enabling Video Recording

Cypress can record a video of each test run automatically, useful for reviewing failures later.

module.exports = defineConfig({
  video: true
})

Recorded videos get saved into a folder generated automatically after the test run finishes.

Environment-Specific Configuration

Some projects need different settings for different environments, such as staging and production. Cypress supports separate configuration files or environment variables to handle this need.

module.exports = defineConfig({
  env: {
    apiUrl: 'https://staging-api.example.com'
  }
})

Overriding Settings from the Command Line

Cypress allows overriding configuration values temporarily without editing the file directly.

npx cypress run --config baseUrl=https://staging.example.com

This approach suits quick tests against a different environment without a permanent file change.

Excluding Specific Test Files

The specPattern option controls which files Cypress treats as tests, useful for excluding work-in-progress files.

module.exports = defineConfig({
  e2e: {
    specPattern: 'cypress/e2e/**/*.cy.js'
  }
})

Best Practices for Configuration

Keep sensitive values like passwords out of the configuration file, since it often gets shared through version control. Use environment variables for anything considered private or environment-specific. Document unusual configuration choices with a short comment for future team members.

Key Points

• The cypress.config.js file controls project-wide settings.
• baseUrl allows visiting pages using short paths instead of full addresses.
• Timeout settings control how long Cypress waits for commands to succeed.
• Viewport settings simulate different screen sizes during testing.
• Command-line overrides allow temporary configuration changes without editing files.