Running Tests - Cypress Automation Framework

Test Execution Overview

Cypress offers multiple ways to run your tests, from interactive development to automated CI/CD pipelines.

Interactive Mode

Visual test runner for development and debugging

Headless Mode

Fast execution for CI/CD and quick verification

Browser Selection

Run tests in Chrome, Firefox, Edge, or Electron

Filtered Execution

Run specific tests, files, or test suites

NPM Scripts

The framework provides convenient scripts in package.json:

package.json

{
  "scripts": {
    "cy:open:ui": "cypress open --config-file cypress.config.ui.ts",
    "cy:open:api": "cypress open --config-file cypress.config.api.ts",
    "cy:run:ui": "cypress run --config-file cypress.config.ui.ts",
    "cy:run:api": "cypress run --config-file cypress.config.api.ts"
  }
}

Interactive Mode

Interactive mode opens the Cypress Test Runner with a visual interface:

npm run cy:open:ui

What Interactive Mode Provides

Browser Selection

Choose which browser to run tests in (Chrome, Electron, Edge, Firefox)

Test Selection

Click on individual test files to run them

Real-Time Execution

Watch tests run in a real browser with visual feedback

Time Travel

Hover over commands to see application state at that moment

Auto-Reload

Tests automatically reload when you save changes (if enabled)

Use interactive mode during development to debug tests and see exactly what’s happening in the application.

Headless Mode

Headless mode runs tests without opening a browser window:

npm run cy:run:ui

Headless Mode Output

You’ll see output like this:

====================================================================================================

  (Run Starting)

  ┌────────────────────────────────────────────────────────────────────────────────┐
  │ Cypress:        14.5.4                                                                       │
  │ Browser:        Electron 118 (headless)                                                      │
  │ Node Version:   v18.17.0 (/usr/local/bin/node)                                               │
  │ Specs:          3 found (LoginPageSpec.cy.ts, HomePageSpec.cy.ts, CheckoutPageSpec.cy.ts)   │
  │ Searched:       cypress/e2e/ui/**/*.cy.ts                                                    │
  └────────────────────────────────────────────────────────────────────────────────┘


────────────────────────────────────────────────────────────────────────────────────────────────────

  Running:  LoginPageSpec.cy.ts                                                            (1 of 3)


  User Authentication
    ✓ Should log in successfully with valid credentials (2456ms)
    ✓ Should not log in with a locked user credentials (876ms)
    ✓ Should log in successfully with a problem user credentials (1234ms)
    ✓ Should log in successfully with a glitched performance user credentials (2100ms)
    ✓ Should log in successfully with a visual issues user credentials (1150ms)


  5 passing (8s)


  (Results)

  ┌────────────────────────────────────────────────────────────────────────────────┐
  │ Tests:        5                                                                            │
  │ Passing:      5                                                                            │
  │ Failing:      0                                                                            │
  │ Pending:      0                                                                            │
  │ Skipped:      0                                                                            │
  │ Screenshots:  0                                                                            │
  │ Video:        true                                                                         │
  │ Duration:     8 seconds                                                                    │
  │ Spec Ran:     LoginPageSpec.cy.ts                                                          │
  └────────────────────────────────────────────────────────────────────────────────┘

Headless mode is perfect for CI/CD pipelines where you need fast, automated test execution without a UI.

Browser Selection

Run tests in different browsers:

npx cypress run --config-file cypress.config.ui.ts --browser chrome

Available Browsers

Check which browsers Cypress detected:

npx cypress info

Output:

Detected 3 browsers installed:

1. Chrome
   - Name: chrome
   - Channel: stable
   - Version: 120.0.6099.109
   - Executable: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

2. Firefox
   - Name: firefox
   - Channel: stable  
   - Version: 121.0
   - Executable: /Applications/Firefox.app/Contents/MacOS/firefox

3. Electron
   - Name: electron
   - Channel: stable
   - Version: 118.0.5993.159

Running Specific Tests

Single Test File

npx cypress run --config-file cypress.config.ui.ts --spec "cypress/e2e/ui/LoginPageSpec.cy.ts"

Multiple Test Files

npx cypress run --config-file cypress.config.ui.ts --spec "cypress/e2e/ui/LoginPageSpec.cy.ts,cypress/e2e/ui/HomePageSpec.cy.ts"

Pattern Matching

# Run all login-related tests
npx cypress run --config-file cypress.config.ui.ts --spec "cypress/e2e/ui/*Login*.cy.ts"

# Run all tests in a directory
npx cypress run --config-file cypress.config.ui.ts --spec "cypress/e2e/ui/**/*.cy.ts"

Filtering Tests with .only and .skip

Run Only Specific Tests

Use .only to run a single test:

it.only('Should log in successfully', () => {
  // Only this test will run
})

it('Should log out', () => {
  // This test will be skipped
})

Or an entire describe block:

describe.only('User Authentication', () => {
  // Only tests in this block will run
})

describe('Product Management', () => {
  // All tests in this block will be skipped
})

Skip Specific Tests

Use .skip to skip tests:

it.skip('Should handle edge case', () => {
  // This test will be skipped
})

it('Should log in successfully', () => {
  // This test will run
})

Remember to remove .only and .skip before committing code! They’re for development only.

Parallel Execution

Run tests in parallel for faster execution:

# Requires Cypress Dashboard or CI provider
npx cypress run --config-file cypress.config.ui.ts --parallel --record --key YOUR_RECORD_KEY

Parallel execution requires a CI setup with multiple machines or Cypress Cloud.

Environment-Specific Execution

Using Environment Variables

# Set base URL via environment variable
CYPRESS_BASE_URL=https://staging.example.com npm run cy:run:ui

# Set custom environment variable
CYPRESS_API_KEY=test123 npm run cy:run:api

Using —env Flag

npx cypress run --config-file cypress.config.ui.ts --env baseUrl=https://staging.example.com,apiKey=test123

Access in tests:

const apiKey = Cypress.env('apiKey')
const baseUrl = Cypress.env('baseUrl')

CI/CD Integration

GitHub Actions Example

.github/workflows/cypress.yml

name: Cypress Tests

on: [push, pull_request]

jobs:
  ui-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 18
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run UI tests
        run: npm run cy:run:ui
      
      - name: Upload screenshots
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: cypress-screenshots
          path: cypress/screenshots

  api-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 18
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run API tests
        run: npm run cy:run:api

GitLab CI Example

.gitlab-ci.yml

image: cypress/browsers:node18.17.0-chrome118.0.5993.88-1-ff118.0.2-edge118.0.2088.46-1

stages:
  - test

ui-tests:
  stage: test
  script:
    - npm ci
    - npm run cy:run:ui
  artifacts:
    when: on_failure
    paths:
      - cypress/screenshots
      - cypress/videos
    expire_in: 1 week

api-tests:
  stage: test
  script:
    - npm ci
    - npm run cy:run:api

Docker Execution

Dockerfile

FROM cypress/included:14.5.4

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .

CMD ["npm", "run", "cy:run:ui"]

Run in Docker:

docker build -t cypress-tests .
docker run cypress-tests

Advanced Execution Options

Record Test Results

npx cypress run --config-file cypress.config.ui.ts --record --key YOUR_PROJECT_KEY

Configure Reporters

# Use JUnit reporter for CI
npx cypress run --config-file cypress.config.ui.ts --reporter junit --reporter-options "mochaFile=results/test-results-[hash].xml"

# Use multiple reporters
npx cypress run --config-file cypress.config.ui.ts --reporter cypress-multi-reporters

Control Video Recording

# Disable video recording
npx cypress run --config-file cypress.config.ui.ts --config video=false

# Record videos only on failure
npx cypress run --config-file cypress.config.ui.ts --config video=true,videoUploadOnPasses=false

Adjust Timeouts

npx cypress run --config-file cypress.config.ui.ts --config defaultCommandTimeout=10000,requestTimeout=15000

Debugging Failed Tests

Screenshots on Failure

Cypress automatically takes screenshots when tests fail. Find them in:

cypress/screenshots/

Videos

Videos of test runs are saved to:

cypress/videos/

Debug Mode

Run tests with debug output:

DEBUG=cypress:* npm run cy:run:ui

Headed Mode in CI

Run with visible browser in CI for debugging:

npx cypress run --config-file cypress.config.ui.ts --headed --no-exit

Test Execution Best Practices

Use interactive mode for development

Develop and debug tests using cy:open for visual feedback:

npm run cy:open:ui

Use headless mode for CI/CD

Run tests in CI pipelines using cy:run for speed:

npm run cy:run:ui

Test in multiple browsers

Ensure cross-browser compatibility:

npm run cy:run:ui -- --browser chrome
npm run cy:run:ui -- --browser firefox

Keep test runs fast

Run only changed tests during development:

npx cypress run --config-file cypress.config.ui.ts --spec "cypress/e2e/ui/LoginPageSpec.cy.ts"

Performance Tips

Disable Video

Speed up test runs by disabling video recording during development

Run in Electron

Electron browser is typically faster than Chrome or Firefox

Use --headed Sparingly

Headed mode is slower; use only when debugging

Parallelize in CI

Split tests across multiple CI machines for faster feedback

Next Steps

Test Organization

Structure tests for efficient execution

Maintainability

Keep your test suite maintainable

Configuration

Optimize Cypress configuration

TypeScript Usage

Leverage TypeScript features

Get Started

Core Concepts

Guides

Best Practices

​Test Execution Overview

Interactive Mode

Headless Mode

Browser Selection

Filtered Execution

​NPM Scripts

​Interactive Mode

​What Interactive Mode Provides

​Headless Mode

​Headless Mode Output

​Browser Selection

​Available Browsers

​Running Specific Tests

​Single Test File

​Multiple Test Files

​Pattern Matching

​Filtering Tests with .only and .skip

​Run Only Specific Tests

​Skip Specific Tests

​Parallel Execution

​Environment-Specific Execution

​Using Environment Variables

​Using —env Flag

​CI/CD Integration

​GitHub Actions Example

​GitLab CI Example

​Docker Execution

​Advanced Execution Options

​Record Test Results

​Configure Reporters

​Control Video Recording

​Adjust Timeouts

​Debugging Failed Tests

​Screenshots on Failure

​Videos

​Debug Mode

​Headed Mode in CI

​Test Execution Best Practices

​Performance Tips

Disable Video

Run in Electron

Use --headed Sparingly

Parallelize in CI

​Next Steps

Test Organization

Maintainability

Configuration

TypeScript Usage

Build docs developers (and LLMs) love

Test Execution Overview

NPM Scripts

Interactive Mode

What Interactive Mode Provides

Headless Mode

Headless Mode Output

Browser Selection

Available Browsers

Running Specific Tests

Single Test File

Multiple Test Files

Pattern Matching

Filtering Tests with .only and .skip

Run Only Specific Tests

Skip Specific Tests

Parallel Execution

Environment-Specific Execution

Using Environment Variables

Using —env Flag

CI/CD Integration

GitHub Actions Example

GitLab CI Example

Docker Execution

Advanced Execution Options

Record Test Results

Configure Reporters

Control Video Recording

Adjust Timeouts

Debugging Failed Tests

Screenshots on Failure

Videos

Debug Mode

Headed Mode in CI

Test Execution Best Practices

Performance Tips

Next Steps