Cypress Configuration Options: Complete Guide to the Config System

Cypress configuration options are centrally defined in the @packages/config package within packages/config/src/options.ts, where they follow the ConfigOption interface with validation rules, default values, and restart requirements.

The cypress-io/cypress repository organizes its configuration system into two distinct categories—DriverConfigOption and RuntimeConfigOption—that control everything from browser viewport settings to internal runtime flags. Whether you define settings in a cypress.config.{js|ts|mjs} file, pass them via the CLI --config flag, or modify them at runtime with Cypress.config(), every option is validated against strict schemas in packages/config/src/validation.ts.

Core Configuration Architecture

The configuration system resides entirely within the @packages/config package, with packages/config/src/options.ts serving as the single source of truth for all available Cypress configuration options.

Driver vs. Runtime Configuration Options

Cypress splits its configuration into two functional groups:

• DriverConfigOption: Options defined in the driverConfigOptions array that affect the test driver, browser behavior, or server settings. These can require a server or browser restart when modified and include settings like baseUrl, viewportWidth, and defaultCommandTimeout.
• RuntimeConfigOption: Options defined in the runtimeOptions array that are read-only at launch or used internally, such as configFile, cypressBinaryRoot, and isInteractive.

The ConfigOption Interface

Every Cypress configuration option follows the ConfigOption interface structure declared in options.ts. Key fields include:

• defaultValue: A static value or function that can vary by testing type (e2e vs component).
• validation: A function from packages/config/src/validation.ts (e.g., validate.isNumber, validate.isStringOrArrayOfStrings) that enforces type safety.
• overrideLevel: Controls mutability—'any' allows per-test overrides, 'suite' restricts to per-suite, and 'never' prevents changes.
• requireRestartOnChange: Specifies whether changing the option forces a 'server' or 'browser' restart.
• isExperimental: Boolean flag marking feature-gated options that hide from the UI unless explicitly enabled.

Essential Cypress Configuration Options

The driverConfigOptions array contains the public API surface that most developers interact with. Here are the critical settings that control test execution:

Network and Browser Settings

• baseUrl: String defaulting to null. Sets the base URL for cy.visit() commands. Changing this value requires a server restart according to the source code.
• viewportWidth / viewportHeight: Numeric defaults that differ by testing type—1000/660 for e2e tests and 500 for component tests. These dimensions configure the browser viewport in the test runner.

Test Execution Behavior

• defaultCommandTimeout: Defaults to 4000 ms. Defines the timeout for most Cypress commands. Because its overrideLevel is set to 'any', you can modify this per-test or per-suite.
• specPattern: Glob pattern defaulting to cypress/e2e/**/*.cy.{js,jsx,ts,tsx} for e2e tests or **/*.cy.{js,jsx,ts,tsx} for component tests. Determines which test files Cypress discovers.
• supportFile: Path to the support file automatically loaded before tests run—cypress/support/e2e.{js,jsx,ts,tsx} for e2e or cypress/support/component.{js,jsx,ts,tsx} for component testing.

Recording and Debugging

• video: Boolean defaulting to false. Enables video recording of the entire test run.
• screenshotOnRunFailure: Boolean defaulting to true. Automatically captures screenshots when tests fail.
• retries: Object defaulting to { runMode: 0, openMode: 0 }. Configures automatic retry attempts for flaky tests in both headless and interactive modes.

Experimental and Advanced Options

• experimental*: Various boolean flags (e.g., experimentalOriginDependencies) that gate upcoming features. These options are hidden from the Cypress UI unless the specific experiment is enabled.
• testIsolation: Boolean defaulting to true that controls whether each test runs in a clean browser context. Restricted to 'suite' level override, meaning it cannot be changed per-test, and is not allowed for component testing.

Configuration Validation and Breaking Changes

Cypress employs a strict validation pipeline to ensure configuration integrity. When loading a config file, the system:

1. Loads defaults from the options array in packages/config/src/options.ts.
2. Merges user-provided values from the config file, CLI arguments, or runtime API.
3. Validates each entry using pure validation functions from packages/config/src/validation.ts that return true on success or descriptive error objects on failure.
4. Detects breaking options by checking against breakingOptions, breakingRootOptions, and testingTypeBreakingOptions arrays. When deprecated options like experimentalJitCompile appear, Cypress throws specific error keys (e.g., EXPERIMENTAL_JIT_COMPILE_REMOVED).

How to Configure Cypress

Using cypress.config.js with defineConfig

The standard approach uses defineConfig from the cypress package to export your settings with full TypeScript support and validation:

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

module.exports = defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',
    specPattern: 'cypress/e2e/**/*.spec.js',
    defaultCommandTimeout: 8000,
    video: true,
  },
  // Driver-level option requiring server restart when changed
  retries: { runMode: 2, openMode: 1 },
  // Experimental flag gated by feature availability
  experimentalOriginDependencies: true,
})

CLI Overrides

You can override any configuration option directly from the command line using the --config flag with comma-separated key-value pairs:

# Target specific tests with custom baseUrl and video recording

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

Runtime Configuration Changes

For options with overrideLevel: 'any', modify values dynamically within your test code using Cypress.config():

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

Note that options marked with 'never' or 'suite' for overrideLevel will throw errors if you attempt to change them at this scope.

Summary

• Cypress configuration options are declared in packages/config/src/options.ts as either DriverConfigOption or RuntimeConfigOption instances.
• Each option enforces type safety through validation functions in packages/config/src/validation.ts and supports dynamic defaults based on testing type.
• Driver options like baseUrl and viewportWidth can require server or browser restarts when changed, while runtime options are internal or read-only at launch.
• Configuration supports multiple override levels: via cypress.config.{js|ts|mjs}, CLI --config flags, or at runtime with Cypress.config() for options marked with overrideLevel: 'any'.
• Breaking changes are detected through dedicated arrays (breakingOptions, breakingRootOptions) that emit specific error keys when deprecated options are encountered.

Frequently Asked Questions

Where are Cypress configuration options defined?

Cypress configuration options are defined in the @packages/config package, specifically within packages/config/src/options.ts. This file exports two arrays—driverConfigOptions and runtimeOptions—that contain every valid configuration property, its default value, validation function, and metadata about restart requirements.

What is the difference between driver and runtime config options?

DriverConfigOption settings affect the test driver, browser behavior, or server state, and they often require a restart when modified. Examples include baseUrl, viewportWidth, and defaultCommandTimeout. RuntimeConfigOption settings are internal flags or read-only values set at launch, such as configFile or cypressBinaryRoot, which cannot be changed after Cypress initializes.

How do I override Cypress configuration at runtime?

You can override configuration at runtime using Cypress.config('key', value) inside your test files, but only for options where overrideLevel is set to 'any' in the source definition. Options marked 'suite' can only be changed in suite-level hooks, while those marked 'never' cannot be modified at runtime. Attempting to override restricted options will result in runtime errors.

What happens when I change an option that requires a restart?

When you modify a configuration option where requireRestartOnChange is set to 'server' or 'browser' (such as baseUrl), Cypress must restart the affected component to apply the change. In the interactive mode (cypress open), this happens automatically. In run mode, you must restart the Cypress process to pick up the new configuration value.

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