# Cypress Configuration Options: Complete Guide to Driver and Runtime Settings

> Master Cypress configuration options for driver and runtime settings. Learn to control Cypress.config and CLI flags for efficient test automation. Enhance your testing workflow today.

- Repository: [Cypress.io/cypress](https://github.com/cypress-io/cypress)
- Tags: deep-dive
- Published: 2026-06-18

---

**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`](https://github.com/cypress-io/cypress/blob/main/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`](https://github.com/cypress-io/cypress/blob/main/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`](https://github.com/cypress-io/cypress/blob/main/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`](https://github.com/cypress-io/cypress/blob/main/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`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/validation.ts).

## Breaking and Deprecated Options

Cypress maintains separate lists for removed or renamed options in [`packages/config/src/options.ts`](https://github.com/cypress-io/cypress/blob/main/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`](https://github.com/cypress-io/cypress/blob/main/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`](https://github.com/cypress-io/cypress/blob/main/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

```javascript
// 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

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

```

### Runtime Modification

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

```

### Component Testing Setup

```javascript
// 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`](https://github.com/cypress-io/cypress/blob/main/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`](https://github.com/cypress-io/cypress/blob/main/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`](https://github.com/cypress-io/cypress/blob/main/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`](https://github.com/cypress-io/cypress/blob/main/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.