Cypress Testing Complete Guide

# Create new project (if needed)
mkdir cypress-tests && cd cypress-tests
npm init -y
 
# Install Cypress
npm install cypress --save-dev
 
# Or with yarn
yarn add cypress --dev

# First run opens Cypress Launchpad
npx cypress open

npm install typescript --save-dev

project/
├── cypress/
│   ├── e2e/                  # Test files
│   │   └── spec.cy.js
│   ├── fixtures/             # Test data (JSON)
│   │   └── example.json
│   ├── support/              # Custom commands and setup
│   │   ├── commands.js       # Custom commands
│   │   └── e2e.js            # Support file (loads before tests)
│   └── downloads/            # Downloaded files (gitignored)
├── cypress.config.js         # Cypress configuration
└── package.json

// cypress/e2e/first-test.cy.js
 
describe('My First Test Suite', () => {
  beforeEach(() => {
    // Runs before each test
    cy.visit('https://example.com')
  })
 
  it('should display the homepage', () => {
    // Verify page loaded
    cy.contains('Example Domain')
  })
 
  it('should have working navigation', () => {
    cy.contains('More information').click()
    cy.url().should('include', 'iana.org')
  })
})

# Open interactive mode
npx cypress open
 
# Run all tests headlessly
npx cypress run
 
# Run specific spec file
npx cypress run --spec "cypress/e2e/login.cy.js"
 
# Run in specific browser
npx cypress run --browser chrome
 
# Run with headed browser (visible)
npx cypress run --headed

<!-- In your application -->
<button data-cy="submit-btn" class="btn btn-primary">Submit</button>

// In your test
cy.get('[data-cy="submit-btn"]').click()

// By data attribute (recommended)
cy.get('[data-cy="search-input"]')
cy.get('[data-testid="submit-button"]')
 
// By CSS selector
cy.get('#username') // ID
cy.get('.error-message') // Class
cy.get('input[type="email"]') // Attribute
cy.get('form > button') // Child combinator
 
// By text content
cy.contains('Submit') // Find by text
cy.contains('button', 'Submit') // Element with text
 
// Within a container
cy.get('[data-cy="login-form"]').within(() => {
  cy.get('input[name="email"]').type('user@test.com')
  cy.get('input[name="password"]').type('password')
})
 
// Find within element
cy.get('.nav').find('a').first()

// Click
cy.get('[data-cy="submit"]').click()
cy.get('[data-cy="menu"]').click({ force: true }) // Click even if covered
 
// Type text
cy.get('[data-cy="email"]').type('user@example.com')
cy.get('[data-cy="search"]').type('query{enter}') // Type and press Enter
 
// Clear and type
cy.get('[data-cy="email"]').clear().type('new@example.com')
 
// Select from dropdown
cy.get('[data-cy="country"]').select('United States') // By visible text
cy.get('[data-cy="country"]').select('US') // By value
 
// Check/Uncheck
cy.get('[data-cy="agree"]').check()
cy.get('[data-cy="newsletter"]').uncheck()
 
// Focus and blur
cy.get('[data-cy="input"]').focus()
cy.get('[data-cy="input"]').blur()
 
// Scroll
cy.get('[data-cy="footer"]').scrollIntoView()
cy.scrollTo('bottom')
 
// Hover (trigger mouseover)
cy.get('[data-cy="menu"]').trigger('mouseover')
 
// Right-click
cy.get('[data-cy="item"]').rightclick()
 
// Double-click
cy.get('[data-cy="item"]').dblclick()

cy.get('[data-cy="input"]').type('{enter}') // Enter key
cy.get('[data-cy="input"]').type('{esc}') // Escape key
cy.get('[data-cy="input"]').type('{backspace}') // Backspace
cy.get('[data-cy="input"]').type('{del}') // Delete
cy.get('[data-cy="input"]').type('{selectall}') // Select all
cy.get('[data-cy="input"]').type('{ctrl+a}') // Ctrl+A
cy.get('[data-cy="input"]').type('{shift+tab}') // Shift+Tab

// With cypress-file-upload plugin or native
cy.get('[data-cy="file-input"]').selectFile('cypress/fixtures/test-file.pdf')
 
// Multiple files
cy.get('[data-cy="file-input"]').selectFile([
  'cypress/fixtures/file1.pdf',
  'cypress/fixtures/file2.pdf',
])
 
// Drag and drop
cy.get('[data-cy="dropzone"]').selectFile('cypress/fixtures/image.png', {
  action: 'drag-drop',
})

// Should assertions
cy.get('[data-cy="title"]').should('be.visible')
cy.get('[data-cy="title"]').should('have.text', 'Welcome')
cy.get('[data-cy="input"]').should('have.value', 'test@example.com')
cy.get('[data-cy="button"]').should('be.disabled')
 
// Chained assertions with .and()
cy.get('[data-cy="link"]')
  .should('have.attr', 'href', '/dashboard')
  .and('have.class', 'active')
  .and('be.visible')
 
// Negative assertions
cy.get('[data-cy="error"]').should('not.exist')
cy.get('[data-cy="button"]').should('not.be.disabled')

// Using expect
cy.get('[data-cy="items"]').then(($items) => {
  expect($items).to.have.length(5)
  expect($items.first()).to.contain('Item 1')
})
 
// Using assert
cy.get('[data-cy="count"]')
  .invoke('text')
  .then((text) => {
    const count = parseInt(text)
    assert.isAbove(count, 0, 'Count should be positive')
  })

// URL assertions
cy.url().should('include', '/dashboard')
cy.url().should('eq', 'https://example.com/dashboard')
 
// Title
cy.title().should('eq', 'Dashboard | MyApp')
 
// Location
cy.location('pathname').should('eq', '/users/profile')
cy.location('search').should('include', 'page=2')

// Cypress waits up to 4 seconds (default) for element to exist
cy.get('[data-cy="button"]').click()
 
// Increase timeout for slow elements
cy.get('[data-cy="slow-content"]', { timeout: 10000 }).should('be.visible')

// Set up intercept and alias
cy.intercept('GET', '/api/users').as('getUsers')
 
// Trigger the request
cy.get('[data-cy="load-users"]').click()
 
// Wait for request to complete
cy.wait('@getUsers')
 
// Wait and assert on response
cy.wait('@getUsers').then((interception) => {
  expect(interception.response.statusCode).to.eq(200)
  expect(interception.response.body).to.have.length.greaterThan(0)
})

// Bad - arbitrary wait
cy.wait(5000)
 
// Good - wait for specific condition
cy.get('[data-cy="loading"]').should('not.exist')
cy.get('[data-cy="content"]').should('be.visible')
 
// Good - wait for network request
cy.intercept('POST', '/api/submit').as('submit')
cy.get('[data-cy="submit"]').click()
cy.wait('@submit')

// cypress/support/commands.js
 
// Login command
Cypress.Commands.add('login', (email, password) => {
  cy.visit('/login')
  cy.get('[data-cy="email"]').type(email)
  cy.get('[data-cy="password"]').type(password)
  cy.get('[data-cy="submit"]').click()
  cy.url().should('include', '/dashboard')
})
 
// API login (faster)
Cypress.Commands.add('loginByApi', (email, password) => {
  cy.request('POST', '/api/auth/login', { email, password }).then(
    (response) => {
      window.localStorage.setItem('token', response.body.token)
    },
  )
})
 
// Get by data-cy shorthand
Cypress.Commands.add('getByDataCy', (selector) => {
  return cy.get(`[data-cy="${selector}"]`)
})

// In your tests
describe('Dashboard', () => {
  beforeEach(() => {
    cy.loginByApi('user@test.com', 'password123')
    cy.visit('/dashboard')
  })
 
  it('should display user data', () => {
    cy.getByDataCy('user-name').should('contain', 'Test User')
  })
})

// cypress/support/index.d.ts
declare namespace Cypress {
  interface Chainable {
    login(email: string, password: string): Chainable<void>
    loginByApi(email: string, password: string): Chainable<void>
    getByDataCy(selector: string): Chainable<JQuery<HTMLElement>>
  }
}

const { defineConfig } = require('cypress')
 
module.exports = defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',
    specPattern: 'cypress/e2e/**/*.cy.{js,jsx,ts,tsx}',
    supportFile: 'cypress/support/e2e.js',
 
    // Timeouts
    defaultCommandTimeout: 4000,
    requestTimeout: 5000,
    responseTimeout: 30000,
    pageLoadTimeout: 60000,
 
    // Viewport
    viewportWidth: 1280,
    viewportHeight: 720,
 
    // Screenshots and videos
    screenshotOnRunFailure: true,
    video: true,
    videosFolder: 'cypress/videos',
    screenshotsFolder: 'cypress/screenshots',
 
    // Retries
    retries: {
      runMode: 2, // Retry failed tests in CI
      openMode: 0, // No retries in interactive mode
    },
 
    // Environment variables
    env: {
      apiUrl: 'http://localhost:3001/api',
    },
 
    setupNodeEvents(on, config) {
      // Plugin configuration
    },
  },
})

// Access in tests
const apiUrl = Cypress.env('apiUrl')
cy.request(`${apiUrl}/users`)
 
// Set via command line
// npx cypress run --env apiUrl=https://api.example.com
 
// Set in cypress.env.json (gitignored)
{
  "apiUrl": "http://localhost:3001/api",
  "adminUser": "admin@test.com"
}

<!-- Don't rely on CSS classes -->
<button class="btn btn-blue-lg">Submit</button>
 
<!-- Use test-specific attributes -->
<button class="btn btn-blue-lg" data-cy="submit-form">Submit</button>

// Bad
cy.wait(5000)
 
// Good
cy.intercept('POST', '/api/submit').as('submit')
cy.get('[data-cy="submit"]').click()
cy.wait('@submit')

// Clean state before each test, not after
beforeEach(() => {
  cy.request('POST', '/api/reset-db')
  cy.loginByApi('user@test.com', 'password')
})

// Bad - test depends on previous test
it('should create user', () => {
  /* ... */
})
it('should see created user', () => {
  /* depends on above */
})
 
// Good - each test is self-contained
it('should create user', () => {
  cy.createUser('new@test.com')
  cy.visit('/users')
  cy.contains('new@test.com')
})

// cypress/fixtures/users.json
{
  "validUser": {
    "email": "test@example.com",
    "password": "SecurePass123"
  },
  "adminUser": {
    "email": "admin@example.com",
    "password": "AdminPass123"
  }
}

// In test
cy.fixture('users').then((users) => {
  cy.login(users.validUser.email, users.validUser.password)
})

// Slow - using UI for login in every test
beforeEach(() => {
  cy.visit('/login')
  cy.get('#email').type('user@test.com')
  cy.get('#password').type('password')
  cy.get('#submit').click()
})
 
// Fast - use API for login
beforeEach(() => {
  cy.loginByApi('user@test.com', 'password')
})