Cypress Setup

Installing Cypress

Cypress is distributed as an npm package, which means it installs like any other project dependency and does not require a separate driver or browser download for Chromium-based browsers, since it can reuse the browsers already installed on your system.

After installation, opening Cypress for the first time scaffolds a cypress/ folder with example specs, and an interactive setup wizard helps you choose between E2E and component testing.

npm install cypress --save-dev
npx cypress open

cypress open launches the interactive Test Runner, where you can pick a testing type and browser.

Common Setup Commands

npx cypress open      // interactive Test Runner
npx cypress run       // headless run, e.g. for CI
npx cypress run --browser chrome
npx cypress run --spec "cypress/e2e/login.cy.js"

• cypress open is best for writing and debugging tests interactively.
• cypress run executes tests headlessly and prints results to the terminal.
• --browser selects a specific installed browser (Chrome, Edge, Firefox, or Electron).
• --spec limits a run to one file or a glob pattern of files.

Setup Command Reference

The commands you will run most often while setting up and using Cypress locally.

Understanding cypress.config.js

The configuration file at the project root controls global behavior: the base URL used by cy.visit(), default timeouts, viewport size, retry settings, and which folders hold specs, fixtures, and support files.

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

export default defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',
    viewportWidth: 1280,
    viewportHeight: 800,
    defaultCommandTimeout: 6000,
  },
});

Setting baseUrl lets you write cy.visit('/login') instead of the full URL in every test.

What Gets Scaffolded on First Run

The first time you run cypress open, Cypress creates the cypress/ folder along with example spec files that demonstrate common patterns. Many teams delete the generated examples once they understand the patterns, keeping only their own real tests.

• cypress/e2e/ — starter example spec files you can delete or keep as reference.
• cypress/fixtures/example.json — a sample fixture file.
• cypress/support/e2e.js — the global support file, imported before every spec.
• cypress.config.js — the generated configuration file at your project root.

Installing Cypress for CI Environments

Cypress downloads a binary in addition to the npm package. In CI environments, caching both node_modules and the Cypress binary cache directory avoids re-downloading the binary on every run, which is one of the most common causes of slow CI pipelines.

# Typical cache paths to persist between CI runs
~/.cache/Cypress
node_modules

Common Mistakes

• Forgetting to commit cypress.config.js, leaving teammates without a working base URL or timeout configuration.
• Not caching the Cypress binary in CI, causing slow, repeated downloads on every pipeline run.
• Leaving the auto-generated example spec files in place indefinitely, cluttering real test output.
• Hardcoding full URLs in every cy.visit() call instead of configuring baseUrl once.

Key Takeaways

• Cypress installs as a normal npm dev dependency: npm install cypress --save-dev.
• cypress open launches the interactive Test Runner; cypress run executes headlessly.
• cypress.config.js centralizes settings like baseUrl, viewport size, and timeouts.
• Caching the Cypress binary in CI meaningfully speeds up pipeline runs.