cypress

Cypress Best Practices

Cypress is our go-to for robust E2E testing. Follow these rules to ensure our test suite remains fast, stable, and easy to maintain.

1. Code Organization & Structure

Adhere to the standard Cypress folder structure. This promotes consistency and discoverability.

Rule: Keep a single cypress.config.ts at the root. Rule: Place E2E tests in cypress/e2e. Rule: Store reusable commands in cypress/support/commands.ts. Rule: Use cypress/fixtures for static test data.

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

export default defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000', // Always set a global base URL
    retries: {
      runMode: 2, // Allow retries in CI for flaky tests
      openMode: 0,
    },
    setupNodeEvents(on, config) {
      // Implement cy.task() here for server-side operations
    },
  },
});

2. Test Isolation

Each test (it block) must be independent and not rely on the state of previous tests. This enables parallelization and makes debugging straightforward.

❌ BAD: Dependent tests

// test-suite.cy.ts
describe('User Flow', () => {
  it('should register a user', () => { /* ... */ }); // Creates user
  it('should log in the registered user', () => { /* ... */ }); // Depends on previous test
});

✅ GOOD: Isolated tests using beforeEach

// test-suite.cy.ts
describe('User Management', () => {
  beforeEach(() => {
    // Programmatically create user and log in via API or custom command
    cy.apiLogin('[email protected]', 'password123');
    cy.visit('/dashboard');
  });

  it('should display user dashboard', () => {
    cy.getBySel('dashboard-header').should('contain', 'Welcome, Test User');
  });

  it('should allow user to update profile', () => {
    cy.getBySel('profile-link').click();
    cy.getBySel('name-input').type('New Name');
    cy.getBySel('save-button').click();
    cy.getBySel('success-message').should('be.visible');
  });
});