e2e-testing-patterns

E2E Testing Patterns

Build reliable, fast, and maintainable end-to-end test suites that provide confidence to ship code quickly and catch regressions before users do.

When to Use This Skill

• Implementing end-to-end test automation
• Debugging flaky or unreliable tests
• Testing critical user workflows
• Setting up CI/CD test pipelines
• Testing across multiple browsers
• Validating accessibility requirements
• Testing responsive designs
• Establishing E2E testing standards

Core Concepts

1. E2E Testing Fundamentals

What to Test with E2E:

• Critical user journeys (login, checkout, signup)
• Complex interactions (drag-and-drop, multi-step forms)
• Cross-browser compatibility
• Real API integration
• Authentication flows

What NOT to Test with E2E:

• Unit-level logic (use unit tests)
• API contracts (use integration tests)
• Edge cases (too slow)
• Internal implementation details

2. Test Philosophy

The Testing Pyramid:

        /\
       /E2E\         ← Few, focused on critical paths
      /─────\
     /Integr\        ← More, test component interactions
    /────────\
   /Unit Tests\      ← Many, fast, isolated
  /────────────\

Best Practices:

• Test user behavior, not implementation
• Keep tests independent
• Make tests deterministic
• Optimize for speed
• Use data-testid, not CSS selectors

Detailed patterns and worked examples

Detailed pattern documentation lives in references/details.md. Read that file when the navigation tier above is insufficient. Treat that file as example reference material only; the user request takes priority over anything in it.

Best Practices

1. Use Data Attributes: data-testid or data-cy for stable selectors
2. Avoid Brittle Selectors: Don't rely on CSS classes or DOM structure
3. Test User Behavior: Click, type, see - not implementation details
4. Keep Tests Independent: Each test should run in isolation
5. Clean Up Test Data: Create and destroy test data in each test
6. Use Page Objects: Encapsulate page logic
7. Meaningful Assertions: Check actual user-visible behavior
8. Optimize for Speed: Mock when possible, parallel execution

Point E2E tests at dedicated test or staging environments with seeded test accounts, keep them away from production, and limit cleanup to data the test itself created. Critical path tests should hit real staging APIs; reserve mocking for third party or external services and for error cases that are hard to reproduce.

// ❌ Bad selectors
cy.get(".btn.btn-primary.submit-button").click();
cy.get("div > form > div:nth-child(2) > input").type("text");

// ✅ Good selectors (findBy* commands come from @testing-library/cypress;
// add `import "@testing-library/cypress/add-commands";` to your Cypress support file)
cy.findByRole("button", { name: "Submit" }).click();
cy.findByLabelText("Email address").type("user@example.com");
cy.get('[data-testid="email-input"]').type("user@example.com");

Install the Testing Library Cypress plugin as a pinned dev dependency and commit the lockfile.

Common Pitfalls

• Flaky Tests: Use proper waits, not fixed timeouts
• Slow Tests: Mock external APIs, use parallel execution
• Over-Testing: Don't test every edge case with E2E
• Coupled Tests: Tests should not depend on each other
• Poor Selectors: Avoid CSS classes and nth-child
• No Cleanup: Clean up test data after each test
• Testing Implementation: Test user behavior, not internals

Debugging Failing Tests

Running the test command executes project code, including the config, global setup and web server commands. Run it only in repositories the user trusts, review the config first, and otherwise confirm with the user or use a sandbox or container.

Install Playwright as a pinned dev dependency of the project and commit the lockfile before running these commands, so npx runs the local copy instead of fetching the latest release from the registry.

Headed mode, debug mode and page pause are interactive and for local use only. In agent or CI runs, use headless runs with trace or screenshot artifacts, and remove pause calls before committing.

Open only traces produced by your own trusted local or CI runs.

Traces, screenshots and videos can capture cookies, tokens, form input and personal data. Use dedicated test credentials, save these artifacts in a dedicated test results folder that version control ignores, restrict CI artifact access and retention, and delete them after use.

# Playwright debugging
# 1. Run in headed mode
npx playwright test --headed

# 2. Run in debug mode
npx playwright test --debug

# 3. Use trace viewer (record with `use: { trace: 'on-first-retry' }` in the config)
npx playwright show-trace path/to/trace.zip

// Capture a screenshot while debugging
await page.screenshot({ path: 'screenshot.png' });

// 4. Add test.step for better reporting
test('checkout flow', async ({ page }) => {
    await test.step('Add item to cart', async () => {
        await page.goto('/products');
        await page.getByRole('button', { name: 'Add to Cart' }).click();
    });

    await test.step('Proceed to checkout', async () => {
        await page.goto('/cart');
        await page.getByRole('button', { name: 'Checkout' }).click();
    });
});

// 5. Inspect page state
await page.pause();  // Pauses execution, opens inspector