How to Programmatically Access Cypress Configuration: Runtime API Guide

Use the global Cypress.config() API to read or modify configuration values at runtime by calling it with no arguments for the full config object, with a key string to read a specific value, or with key-value pairs to override settings for the current test execution.

The cypress-io/cypress repository provides a robust configuration system that allows developers to programmatically access Cypress configuration during test execution. Whether you need to inspect the current baseUrl, adjust timeouts mid-run, or retrieve file paths like downloadsFolder, the Cypress.config() method offers runtime access to the resolved configuration object stored in the driver's state.

Using the Cypress.config() API in Tests

The global Cypress.config() method serves as both a getter and setter for the test runner's configuration state.

Reading Configuration Values

To retrieve configuration data, call Cypress.config() with no arguments to return the entire resolved configuration object, or pass a specific key to access individual properties.

// Read a single config value
const baseUrl = Cypress.config('baseUrl')

// Read the entire resolved config object
const fullConfig = Cypress.config()
console.log('Running in', fullConfig.browser?.name)

Modifying Configuration at Runtime

Update settings dynamically by passing a key and value pair, or provide an object containing multiple configuration changes. These modifications apply only to the current test execution and do not persist to your cypress.config.js or cypress.config.ts files.

// Override a config option for the rest of the run
Cypress.config('defaultCommandTimeout', 15000)

// Set multiple options at once
Cypress.config({
  video: false,
  viewportWidth: 1200,
})

Configuration Architecture and Source Files

Understanding how Cypress handles configuration internally helps explain why runtime changes behave as they do. The configuration system spans two main packages: @packages/config handles parsing and resolution, while @packages/driver manages runtime access.

When Cypress loads, the configuration is parsed from your project files, merged with defaults, and stored in the driver's state management system. Specifically, the implementation resides in:

• packages/config/src/index.ts – Entry point that re-exports configuration helpers including addToCypressConfig and defineConfig
• packages/config/src/utils.ts – Core utilities for resolving environment variables, validating options, and merging configuration objects
• packages/driver/src/util/config.ts – Runtime bridge that forwards Cypress.config() calls to the resolved config stored in Cypress.state('config')
• packages/driver/src/cypress/cy.ts – Sets up the global Cypress namespace and binds the config method to the driver

Practical Code Examples

Here are practical patterns for working with Cypress configuration in your test code and Node scripts.

Accessing Config Values Inside Tests

Use Cypress.config() to retrieve dynamic paths or settings within your test logic:

it('reads a file from the downloads folder', () => {
  cy.readFile(`${Cypress.config('downloadsFolder')}/records.csv`)
    .should('contain', 'id,name')
})

Programmatic Access from Node Scripts

When running Cypress from a custom CLI or build script, pass configuration options programmatically:

import cypress from 'cypress'

cypress.run({
  config: {
    baseUrl: 'http://localhost:3000',
    defaultCommandTimeout: 8000,
  },
}).then((results) => {
  console.log('Tests finished with status', results.totalFailed)
})

Runtime Behavior and Limitations

Changes made via Cypress.config() affect only the in-memory configuration for the current test run. Because the config object is stored in Cypress.state('config') within the driver, modifications do not write back to disk or alter your project's configuration files. This design ensures test isolation while allowing dynamic adjustments based on runtime conditions.

Summary

• The Cypress.config() global API provides runtime read and write access to the resolved configuration object
• Configuration is managed by the @packages/config package and exposed through the driver in packages/driver/src/util/config.ts
• Read values by calling Cypress.config() with no arguments or a specific key string
• Modify values by passing key-value pairs or an options object, but note that changes are temporary and execution-specific
• Access configuration programmatically from Node scripts using the cypress.run() method with a config option

Frequently Asked Questions

How do I read the entire configuration object in Cypress?

Call Cypress.config() with no arguments to receive the complete resolved configuration object containing all merged defaults, environment variables, and user settings from your cypress.config.js file.

Can I permanently change Cypress configuration from within a test?

No. Changes made using Cypress.config() inside tests only modify the in-memory configuration for the current test execution. To permanently change configuration, edit your cypress.config.js or cypress.config.ts file directly.

Where does Cypress store the configuration at runtime?

Internally, Cypress stores the resolved configuration in Cypress.state('config'), which is managed by the driver package in packages/driver/src/util/config.ts. The Cypress.config() method serves as the public API to access this internal state.

How do I pass custom configuration when running Cypress programmatically from Node?

Use the cypress.run() method from the Cypress npm module, passing a config object in the options. This allows you to programmatically set values like baseUrl or defaultCommandTimeout when triggering test runs from build scripts or CI pipelines.

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