Implementation:Cypress io Cypress DefineConfig Options

Knowledge Sources	Cypress Cypress Configuration
Domains	Configuration, Testing
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete tool for defining and resolving Cypress configuration options provided by the @packages/config module.

Description

The options.ts module defines all Cypress configuration options as typed arrays (BreakingOption[]). Each option specifies its name, default value, validation function, which testing types it applies to, and whether it can be overridden at runtime. The setupFullConfigWithDefaults function in project/utils.ts resolves the final configuration by merging all sources.

Usage

Import these options when building the configuration resolution pipeline or when validating user-provided configuration. The options array is the single source of truth for all configurable Cypress behavior.

Code Reference

Source Location

• Repository: cypress-io/cypress
• File: packages/config/src/options.ts
• Lines: L1-778

Signature

interface ConfigOption {
  name: string
  defaultValue?: any
  validation: Function
  requireRestartOnChange?: 'server' | 'browser'
  overrideLevels?: OverrideLevel[]  // 'any' | 'suite' | 'never'
}

type OverrideLevel = 'any' | 'suite' | 'never'

// User-facing API
export function defineConfig(config: Cypress.ConfigOptions): Cypress.ConfigOptions

// Internal resolution
export function setupFullConfigWithDefaults(
  config: Record<string, any>,
  options: Record<string, any>
): ResolvedConfig

Import

import { defineConfig } from 'cypress'
// Internal:
import { options, breakingOptions } from '@packages/config'

I/O Contract

Inputs

Name	Type	Required	Description
config	Cypress.ConfigOptions	Yes	User configuration from cypress.config.ts
env vars	CYPRESS_*	No	Environment variable overrides
CLI flags	--config key=value	No	Command-line configuration overrides

Outputs

Name	Type	Description
ResolvedConfig	object	Fully resolved configuration with all sources merged
Validation errors	Error[]	Array of validation errors if config is invalid

Usage Examples

Basic E2E Configuration

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

export default defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',
    specPattern: 'cypress/e2e/**/*.cy.{js,jsx,ts,tsx}',
    viewportWidth: 1280,
    viewportHeight: 720,
    defaultCommandTimeout: 10000,
  },
})

Environment Variable Override

# Override baseUrl via environment variable
CYPRESS_BASE_URL=http://staging.example.com npx cypress run

Related Pages

Implements Principle

• Principle:Cypress_io_Cypress_Project_Configuration

Uses Heuristic

• Heuristic:Cypress_io_Cypress_Timeout_Tuning