Cypress Configuration Options: Complete Guide to Driver and Runtime Settings

Cypress configuration options are defined in the @packages/config package and controlled via cypress.config.{js|ts|mjs} files, CLI flags, or the Cypress.config() API, with each option specifying validation rules, default values, and restart requirements.

The cypress-io/cypress repository organizes its configuration system in the packages/config directory, where TypeScript interfaces define every available setting. Understanding these Cypress configuration options helps developers optimize test behavior, from viewport dimensions to experimental feature flags.

How Configuration Options Are Defined

The configuration system lives in packages/config/src/options.ts and declares two distinct groups of settings.

DriverConfigOption represents options that affect the test driver, browser, or server. These entries can define defaults, validation functions, and may require a restart when changed. They are exported in the driverConfigOptions array.

RuntimeConfigOption handles run-time only settings such as internal flags (configFile, cypressBinaryRoot). These appear in the runtimeOptions array within the same file.

Both groups follow the ConfigOption interface, which standardizes how Cypress processes user input.

The ConfigOption Interface Structure

Each option in packages/config/src/options.ts implements a strict interface with fields that control behavior and validation:

• defaultValue: Either a static value or a function that varies by testing type (e2e vs component)
• validation: A function from packages/config/src/validation.ts (e.g., validate.isNumber, validate.isStringOrArrayOfStrings) that checks type and shape
• overrideLevel: Determines scope—'any' allows per-test overrides, 'suite' restricts to describe blocks, and 'never' prevents changes
• requireRestartOnChange: Triggers a server or browser restart when modified
• isExperimental: Hides the option from the UI unless the experiment is explicitly enabled

Essential Cypress Configuration Options

The driverConfigOptions array contains the public API that most developers interact with.

baseUrl

The baseUrl option defaults to null and accepts a string value. This setting defines the base URL for cy.visit() commands. According to the source code in packages/config/src/options.ts, changing this value forces a server restart to ensure the new origin is properly configured.

viewportWidth and viewportHeight

These numeric options default to 1000 and 660 for e2e testing, or 500 for component testing. The test runner uses these values to set the browser viewport dimensions before executing tests.

defaultCommandTimeout

This option defaults to 4000 milliseconds and controls the timeout for most Cypress commands. The configuration allows per-test overrides because it uses overrideLevel: 'any', making it safe to adjust for individual slow-running tests.

specPattern

The specPattern option defines which test files to load using glob patterns. It defaults to cypress/e2e/**/*.cy.{js,jsx,ts,tsx} for e2e testing and **/*.cy.{js,jsx,ts,tsx} for component testing. The validation function ensures the value is a string or array of strings.

supportFile

This string option specifies the path to the support file automatically loaded before tests start. Defaults differ by testing type: cypress/support/e2e.{js,jsx,ts,tsx} for e2e and cypress/support/component.{js,jsx,ts,tsx} for component testing.

retries

The retries option accepts an object defaulting to { runMode: 0, openMode: 0 }. This configures automatic retries for flaky tests, with separate counts for headed and headless runs.

testIsolation

This boolean option defaults to true and controls whether each test runs in a clean browser context. It carries overrideLevel: 'suite', meaning it can only be changed at the suite level, and is explicitly disallowed for component testing.

video

The video option defaults to false and enables video recording of test runs. This is a boolean option validated by the isBoolean checker in packages/config/src/validation.ts.

Breaking and Deprecated Options

Cypress maintains separate lists for removed or renamed options in packages/config/src/options.ts:

• breakingOptions: Global options removed in Cypress 10+
• breakingRootOptions: Root-level configuration changes
• testingTypeBreakingOptions: Testing-type specific deprecations

When encountered, Cypress throws or warns with specific error keys (e.g., EXPERIMENTAL_JIT_COMPILE_REMOVED).

The Validation Pipeline

When Cypress loads a configuration file, it executes a four-step process defined in the configuration loader:

1. Load defaults from the options array exported by packages/config/src/index.ts
2. Merge user-provided values from the config file, CLI --config flags, or Cypress.config() calls
3. Validate each entry using the validation functions from packages/config/src/validation.ts
4. Detect breaking options and emit errors or warnings based on the breaking options metadata

Validation helpers are pure functions that return true on success or a descriptive error object on failure.

Configuration Examples

Basic E2E Configuration

// cypress.config.js
const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',
    specPattern: 'cypress/e2e/**/*.spec.js',
    defaultCommandTimeout: 8000,
    video: true,
  },
  retries: { runMode: 2, openMode: 1 },
  experimentalOriginDependencies: true,
})

CLI Override

cypress run --spec "cypress/e2e/login.spec.js" \
            --config baseUrl=https://staging.example.com,video=true

Runtime Modification

// Inside a test
Cypress.config('defaultCommandTimeout', 12000)  // Allowed: overrideLevel = 'any'

Component Testing Setup

// cypress.config.ts
import { defineConfig } from 'cypress'

export default defineConfig({
  component: {
    specPattern: 'src/**/*.cy.{js,ts,tsx}',
    devServer: {
      framework: 'react',
      bundler: 'vite',
    },
  },
})

Summary

• Cypress configuration options are declared in packages/config/src/options.ts as either DriverConfigOption (affects browser/server) or RuntimeConfigOption (internal flags)
• Each option specifies validation functions, default values, and restart requirements via the ConfigOption interface
• The validation pipeline in packages/config/src/validation.ts ensures type safety and detects breaking changes from Cypress 10+
• Options like baseUrl and viewportWidth support different defaults for e2e versus component testing
• Changes to certain options trigger server or browser restarts, while others can be overridden per-test or per-suite

Frequently Asked Questions

How do I change Cypress configuration options at runtime?

You can modify options during test execution using Cypress.config('optionName', value). However, this only works for options with overrideLevel: 'any'. Options marked with overrideLevel: 'suite' can only be changed within describe blocks, while those marked 'never' cannot be modified at runtime.

What happens when I modify a configuration option that requires a restart?

When you change an option marked with requireRestartOnChange: 'server' or requireRestartOnChange: 'browser', Cypress automatically terminates and restarts the affected process. For example, changing baseUrl triggers a server restart to ensure the new origin is properly configured for subsequent tests.

Where are experimental Cypress configuration options defined?

Experimental options are defined in the driverConfigOptions array in packages/config/src/options.ts with the isExperimental: true flag. These options remain hidden from the standard UI unless explicitly enabled, and they follow the same validation patterns as stable options but may be removed in future versions.

How does Cypress validate configuration option values?

Validation occurs through pure functions exported from packages/config/src/validation.ts. Each option references a validator (such as isNumber or isStringOrArrayOfStrings) that returns true for valid input or an error object for invalid data. This validation runs during the configuration loading phase before any tests execute.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}