How to Override Default Cypress Configuration Settings: A Complete Guide

You can override default Cypress configuration settings via CLI flags (--config, --config-file), the cypress.config.js file, or programmatically at runtime using Cypress.config() and suite-level overrides, with each option respecting an overrideLevel that restricts when changes are allowed.

The cypress-io/cypress repository provides multiple extension points to customize default behavior without modifying core source code. Understanding how to override default Cypress configuration settings requires knowledge of the overrideLevel semantics that govern when and where each option can be changed. This guide examines the actual source implementation to show you exactly how to customize timeouts, viewport dimensions, base URLs, and other settings across CLI, config file, and test-run scopes.

Understanding Configuration Architecture and Default Values

Cypress stores its default configuration values in packages/config/src/options.ts, where every option is defined with a default value, validation function, and overrideLevel restriction. The overrideLevel property determines where an option can be modified:

• 'any' – Can be changed via CLI, config file, or at test time
• 'suite' – Only modifiable via Cypress.config() inside a suite or test
• 'never' – Immutable at runtime; only settable at build time

For example, baseUrl uses 'any' while testIsolation uses 'suite' and allowCypressEnv uses 'never'. When you attempt to override a value, packages/config/src/browser.ts validates the change against these levels using a lookup table generated by createIndex.

CLI Overrides: --config and --config-file

Overriding via --config Flag

Pass configuration values directly when running Cypress via the command line. The CLI parser defined in cli/lib/cli.ts accepts the --config flag, which cli/lib/exec/run.ts processes into the internal configuration object.

Use comma-separated key-value pairs for simple overrides:

cypress run --config "baseUrl=http://my.test,video=false,defaultCommandTimeout=8000"

Or pass a JSON string for complex values:

cypress run --config '{"video":false,"viewportWidth":1440}'

Specifying Alternative Config Files

Use --config-file to load a completely different configuration file without renaming your defaults:

cypress run --config-file ./config/cypress.staging.config.ts

The path is forwarded to the config loader, which merges the exported values with defaults from options.ts using the same validation logic as the standard cypress.config.js file.

Config File Overrides: cypress.config.js and defineConfig

Create a cypress.config.{js,ts,mjs} file at your project root to override defaults persistently. Import defineConfig from Cypress to get TypeScript validation and autocompletion:

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

export default defineConfig({
  baseUrl: 'http://localhost:3000',
  viewportWidth: 1280,
  viewportHeight: 800,
  video: false,
  defaultCommandTimeout: 10000,
  env: {
    API_TOKEN: 'test-token-123'
  }
})

During startup, the configuration loader validates each key against the schema in packages/config/src/options.ts and merges your values with built-in defaults. Invalid values trigger validation errors before tests begin.

Test-Time Overrides: Cypress.config() and Suite-Level Options

Runtime Configuration with Cypress.config()

Inside your test code, call Cypress.config() to change values dynamically. This method is implemented in packages/driver/src/util/config.ts, which enforces overrideLevel restrictions at runtime:

describe('Admin Dashboard', () => {
  before(() => {
    // Override baseUrl for this suite only
    Cypress.config('baseUrl', 'http://admin.test')
  })

  it('loads the dashboard', () => {
    cy.visit('/dashboard')
    // Assertions here use the overridden baseUrl
  })
})

Suite-Level Configuration Objects

Pass a configuration object as the second argument to describe() or it() to scope overrides to specific test blocks:

describe('Responsive Layout', { viewportWidth: 1440 }, () => {
  it('renders correctly on large screens', () => {
    cy.visit('/')
    // This test runs with viewportWidth: 1440
  })
})

describe('Mobile View', { viewportWidth: 375, viewportHeight: 667 }, () => {
  it('works on phones', () => {
    cy.visit('/')
  })
})

Only options with overrideLevel: 'any' or overrideLevel: 'suite' can be used here. Attempting to override a 'never' option generates a validation error.

Validation and Error Handling

When you attempt an illegal override, packages/driver/src/util/config.ts throws a validation error formatted by packages/driver/src/cypress/error_messages.ts. For example, trying to override allowCypressEnv (which has overrideLevel: 'never') produces:

// This will throw an error
describe('Invalid Suite', { allowCypressEnv: false }, () => {
  // Error: The config passed to your suite-level overrides has the following validation error...
})

The error message includes the specific key and the restriction (overrideLevel: 'never'), helping you identify which configuration layer is appropriate for your change.

Summary

• Default values live in packages/config/src/options.ts and include overrideLevel metadata restricting when values can be changed.
• CLI overrides use --config for inline JSON or comma-separated values, processed by cli/lib/exec/run.ts, or --config-file to specify alternative config files.
• Config file overrides export a defineConfig object from cypress.config.{js,ts} to merge persistent customizations with defaults.
• Test-time overrides use Cypress.config() or suite-level options in describe()/it() blocks, enforced by packages/driver/src/util/config.ts.
• Validation occurs at multiple layers: CLI parsing, config file loading, and runtime enforcement, with clear error messages for invalid overrides.

Frequently Asked Questions

Can I override any Cypress configuration option at runtime?

No. Each option has an overrideLevel defined in packages/config/src/options.ts. Options marked 'never' cannot be changed at runtime; 'suite' options only via Cypress.config() or suite-level overrides; and 'any' options via CLI, config file, or runtime. Attempting to override a restricted option throws a validation error from packages/driver/src/util/config.ts.

What is the difference between --config and --config-file flags?

The --config flag accepts inline configuration values as JSON or comma-separated key-value pairs for immediate overrides during a single run. The --config-file flag accepts a file path to a JavaScript or TypeScript configuration file that exports a complete config object, useful for maintaining separate environment-specific configurations (e.g., staging vs. production).

How do I override configuration for a single test suite without affecting others?

Pass a configuration object as the second argument to describe() or it(). For example: describe('Suite', { viewportWidth: 1200 }, () => { ... }). This creates a scoped override that applies only to tests within that block. Alternatively, use Cypress.config('key', value) inside a before() hook to set values for the duration of that suite.

Where does Cypress validate that my configuration values are correct?

Validation occurs in three stages: the CLI validates flag syntax in cli/lib/cli.ts; the config loader validates against schemas in packages/config/src/options.ts when loading files; and the driver validates runtime overrides in packages/driver/src/util/config.ts against the testOverrideLevels lookup built by packages/config/src/browser.ts.

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