Cypress - Configuration of JSON File

Cypress - Modern Configuration with cypress.config.js

Cypress configurations define global settings applicable to all tests within your project. In modern Cypress (version 10 and above), these configurations are primarily managed in a cypress.config.js or cypress.config.ts file at the root of your project. This replaces the older cypress.json file.

When you open Cypress, the Test Runner’s ‘Settings’ tab will display the resolved configuration. Under ‘Project Settings’ (or by expanding ‘Configuration’ in older Test Runner views), you can inspect all effective configuration values, including defaults and your overrides.

This includes crucial settings like default timeouts (e.g., defaultCommandTimeout, pageLoadTimeout), the baseUrl for cy.visit() and cy.request(), environment variables, folder paths, and more. Understanding these settings is key to a stable and efficient testing setup.

For instance, you’ll see values for baseUrl, defaultCommandTimeout, paths to fixturesFolder, supportFile, etc., all clearly listed. This transparency helps in debugging configuration issues.

Overriding Default Configuration Values

To override Cypress’s default configurations or set project-specific ones, you define them in your cypress.config.js (or .ts) file. This file exports a configuration object.

Implementation in cypress.config.js

Here’s how you can set a baseUrl and a custom defaultCommandTimeout in cypress.config.js:

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

module.exports = defineConfig({
  defaultCommandTimeout: 5000, // Sets default command timeout to 5 seconds
  e2e: {
    baseUrl: 'https://www.yourapp.com',
    setupNodeEvents(on, config) {
      // Implement node event listeners here, if any
      // This is a good place for tasks like report generation or pre-processing
    },
    // specPattern: 'cypress/e2e/**/*.cy.{js,jsx,ts,tsx}' // Default spec pattern
  },
});

In this example, baseUrl is set to ‘https://www.yourapp.com’ for end-to-end tests, and defaultCommandTimeout is set to 5000ms globally. After saving this file and re-running Cypress, these changes will be reflected in the Test Runner’s configuration display.

Using defineConfig provides autocompletion and type checking if you’re using JavaScript with JSDoc or TypeScript, which is highly recommended for larger projects.

Impact on Tests: Using baseUrl

With baseUrl configured, your test scripts become cleaner:

describe('My Application Test', () => {
  it('Visits the home page', () => {
    // Cypress automatically prepends the baseUrl
    cy.visit('/'); // Navigates to https://www.yourapp.com/
    cy.contains('Welcome').should('be.visible');
  });
});

Execution Results:

The test log will show cy.visit('/') successfully navigating to the full URL specified by baseUrl. This setting applies to all tests, making them more maintainable as the base URL is centralized.

Overriding Configuration Dynamically

You can override configuration values at different levels, providing flexibility:

1. Test-Specific Configuration: Use Cypress.config('key', 'value') within a test file to change a configuration for the subsequent commands in that test or suite. This is less common for global settings but can be useful.

2. Command-Specific Options: Many Cypress commands accept an options object that can override specific configurations like timeout just for that command. This is the preferred way for localized overrides.

For example, to increase the timeout for a specific cy.get() command:

// Override timeout for this specific command
cy.get('.very-slow-element', { timeout: 10000 }).should('be.visible');

// Or, for a section of a test (less common for defaultCommandTimeout):
// Cypress.config('defaultCommandTimeout', 10000); // All subsequent commands use 10s
// cy.get('.another-element').click();
// Cypress.config('defaultCommandTimeout', 5000); // Reset if needed

Configuration Precedence: Command-specific options (e.g., { timeout: 10000 }) take the highest precedence, followed by dynamic changes via Cypress.config(), then values in cypress.config.js, and finally Cypress’s internal defaults.

Disabling Configuration File Loading via CLI

You can prevent Cypress from loading your cypress.config.js file by using a command-line flag. This is useful for debugging or running tests with pure Cypress defaults.

Suppose your cypress.config.js has defaultCommandTimeout: 10000 (10 seconds).

// cypress.config.js example content for this scenario
const { defineConfig } = require('cypress');

module.exports = defineConfig({
  defaultCommandTimeout: 10000,
  e2e: {
    // other e2e configurations
  }
});

To run Cypress without loading this custom configuration:

npx cypress open --config-file false

After running this command, the ‘Settings’ tab in the Test Runner will show configFile as false. Consequently, defaultCommandTimeout will revert to Cypress’s internal default (e.g., 4000ms), not the 10000ms set in your (now ignored) config file.

You can also override specific configuration values via the CLI using the --config flag, e.g., npx cypress run --config viewportWidth=1280,viewportHeight=720. For more details, search ‘Cypress command line options’ in the official documentation.