e2e

name	e2e
description	Write end-to-end tests for user flows using Cypress. Use when user asks to "write e2e tests", "/e2e", "add Cypress tests", or wants to test a user flow end-to-end. Don't use for unit tests, component tests, or projects using Playwright, Puppeteer, or other non-Cypress frameworks.

End-to-End Tests (Cypress)

Detection

Run in parallel:

• Check package.json for cypress version
• Read cypress.config.ts for baseUrl and test file patterns
• Read 1-2 existing test files in cypress/e2e/ to match conventions

Workflow

1. Read existing tests and config to match project style
2. Understand the user flow — ask if unclear
3. Identify selectors (see selectors.md)
4. Write tests in cypress/e2e/ — one file per flow or feature

Format

describe('login flow', () => {
  beforeEach(() => {
    cy.visit('/login')
  })

  it('logs in with valid credentials', () => {
    cy.findByLabelText('Email').type('[e-mail]')
    cy.findByLabelText('Password').type('password')
    cy.findByRole('button', { name: 'Sign in' }).click()
    cy.url().should('include', '/dashboard')
    cy.findByRole('heading', { name: 'Dashboard' }).should('be.visible')
  })

  it('shows error with invalid credentials', () => {
    cy.findByLabelText('Email').type('[e-mail]')
    cy.findByLabelText('Password').type('wrong')
    cy.findByRole('button', { name: 'Sign in' }).click()
    cy.findByRole('alert').should('contain.text', 'Invalid credentials')
  })
})

Selector priority

Prefer @testing-library/cypress commands when installed, e.g. cy.findByRole('button', { name: 'Submit' }); use cy.get('[data-testid="submit"]') only as a last resort.

See selectors.md for the full priority guide.

Rules

• Use @testing-library/cypress selectors when available, else cy.get
• Use data-testid only as last resort
• One logical outcome per it block
• Test behavior, not implementation details
• Never use cy.wait(<number>) — use cy.findBy* auto-retry instead

Error Handling

• If cypress is not in package.json → stop and ask user to install Cypress first
• If cypress.config.ts is missing → ask user to run npx cypress open to initialize config
• If baseUrl is unreachable → verify the dev server is running before writing tests that require it