Cypress Configuration

The Shape of cypress.config.js

Configuration is split by testing type, e2e and component, since each has different relevant settings (like specPattern and baseUrl for E2E, versus devServer for component testing). Shared settings can live at the top level, outside either block.

// cypress.config.js
import { defineConfig } from 'cypress';

export default defineConfig({
  viewportWidth: 1280,
  viewportHeight: 800,
  retries: { runMode: 2, openMode: 0 },
  e2e: {
    baseUrl: 'http://localhost:3000',
    specPattern: 'cypress/e2e/**/*.cy.js',
  },
});

Top-level settings like viewportWidth and retries apply across both E2E and component testing.

Frequently Adjusted Settings

baseUrl
viewportWidth / viewportHeight
defaultCommandTimeout
retries
video
screenshotOnRunFailure
specPattern
env

• baseUrl is used by cy.visit()/cy.request() for relative URLs.
• retries can be configured separately for headless (runMode) and interactive (openMode) runs.
• video/screenshotOnRunFailure control debugging artifacts, especially useful in CI.
• specPattern controls which files Cypress treats as tests, covered earlier in this course.

Configuration Options Cheat Sheet

The most commonly tuned settings across real-world Cypress projects.

Configuring Test Retries

Cypress supports automatically re-running a failed test a configured number of times before marking it as truly failed, useful for absorbing occasional environment-level flakiness in CI, though it should never be used as a substitute for fixing genuinely flaky tests.

export default defineConfig({
  retries: {
    runMode: 2,   // retry up to 2 times in `cypress run`
    openMode: 0,  // never auto-retry in the interactive Test Runner
  },
});

Retries are intentionally disabled by default in interactive mode, so you always see a failure immediately while debugging.

Overriding Configuration per Environment

Beyond the --config CLI flag, larger projects sometimes export different configuration objects based on a Node environment variable, letting one config file adapt cleanly across local, staging, and CI without duplicating the whole file.

const isCI = process.env.CI === 'true';

export default defineConfig({
  e2e: {
    baseUrl: isCI ? 'http://localhost:4000' : 'http://localhost:3000',
    retries: { runMode: isCI ? 2 : 0, openMode: 0 },
  },
});

Common Mistakes

• Setting a high retries value to hide consistently flaky tests instead of fixing their root cause.
• Forgetting that openMode and runMode retries are configured, and default, differently.
• Not setting baseUrl, leading to verbose, hardcoded full URLs throughout every spec file.
• Overriding specPattern without realizing it can silently stop discovering existing spec files.

Key Takeaways

• cypress.config.js centralizes settings for both E2E and component testing.
• baseUrl, timeouts, and retries are among the most commonly tuned options.
• Retries help absorb CI-level flakiness but should not replace fixing genuinely flaky tests.
• Configuration can vary per environment using Node-level logic inside the config file itself.