E2E Testing

When to Use

Activate this skill when:

• Writing E2E tests for complete user workflows (login, CRUD operations, multi-page flows)
• Creating critical path regression tests that validate the full stack
• Testing cross-browser compatibility (Chromium, Firefox, WebKit)
• Validating authentication flows end-to-end
• Testing file upload/download workflows
• Writing smoke tests for deployment verification

Do NOT use this skill for:

• React component unit tests (use react-testing-patterns)
• Python backend unit/integration tests (use pytest-patterns)
• TDD workflow enforcement (use tdd-workflow)
• API contract testing without a browser (use pytest-patterns with httpx)

Instructions

Test Structure

e2e/
├── playwright.config.ts         # Global Playwright configuration
├── fixtures/
│   ├── auth.fixture.ts          # Authentication state setup
│   └── test-data.fixture.ts     # Test data creation/cleanup
├── pages/
│   ├── base.page.ts             # Base page object with shared methods
│   ├── login.page.ts            # Login page object
│   ├── users.page.ts            # Users list page object
│   └── user-detail.page.ts     # User detail page object
├── tests/
│   ├── auth/
│   │   ├── login.spec.ts
│   │   └── logout.spec.ts
│   ├── users/
│   │   ├── create-user.spec.ts
│   │   ├── edit-user.spec.ts
│   │   └── list-users.spec.ts
│   └── smoke/
│       └── critical-paths.spec.ts
└── utils/
    ├── api-helpers.ts           # Direct API calls for test setup
    └── test-constants.ts        # Shared constants

Naming conventions:

• Test files: <feature>.spec.ts
• Page objects: <page-name>.page.ts
• Fixtures: <concern>.fixture.ts
• Test names: human-readable sentences describing the user action and expected outcome

Page Object Model

Every page gets a page object class that encapsulates selectors and actions. Tests never interact with selectors directly.

Base page object:

// e2e/pages/base.page.ts
import { type Page, type Locator } from "@playwright/test";

export abstract class BasePage {
  constructor(protected readonly page: Page) {}

  /** Navigate to the page's URL. */
  abstract goto(): Promise<void>;

  /** Wait for the page to be fully loaded. */
  async waitForLoad(): Promise<void> {
    await this.page.waitForLoadState("networkidle");
  }

  /** Get a toast/notification message. */
  get toast(): Locator {
    return this.page.getByRole("alert");
  }

  /** Get the page heading. */
  get heading(): Locator {
    return this.page.getByRole("heading", { level: 1 });
  }
}

Concrete page object:

// e2e/pages/users.page.ts
import { type Page, type Locator } from "@playwright/test";
import { BasePage } from "./base.page";

export class UsersPage extends BasePage {
  // ─── Locators ─────────────────────────────────────────
  readonly createButton: Locator;
  readonly searchInput: Locator;
  readonly userTable: Locator;

  constructor(page: Page) {
    super(page);
    this.createButton = page.getByTestId("create-user-btn");
    this.searchInput = page.getByRole("searchbox", { name: /search users/i });
    this.userTable = page.getByRole("table");
  }

  // ─── Actions ──────────────────────────────────────────
  async goto(): Promise<void> {
    await this.page.goto("/users");
    await this.waitForLoad();
  }

  async searchFor(query: string): Promise<void> {
    await this.searchInput.fill(query);
    // Wait for search results to update (debounced)
    await this.page.waitForResponse("**/api/v1/users?*");
  }

  async clickCreateUser(): Promise<void> {
    await this.createButton.click();
  }

  async getUserRow(email: string): Promise<Locator> {
    return this.userTable.getByRole("row").filter({ hasText: email });
  }

  async getUserCount(): Promise<number> {
    // Subtract 1 for header row
    return (await this.userTable.getByRole("row").count()) - 1;
  }
}

Rules for page objects:

• One page object per page or major UI section
• Locators are public readonly properties
• Actions are async methods
• Page objects never contain assertions -- tests assert
• Page objects handle waits internally after actions

Selector Strategy

Priority order (highest to lowest):

NEVER use:

• CSS selectors (.class-name, #id) -- brittle, break on styling changes
• XPath (//div[@class="foo"]) -- unreadable, extremely brittle
• DOM structure selectors (div > span:nth-child(2)) -- break on layout changes

Adding data-testid attributes:

// In React components -- add data-testid to interactive elements
<button data-testid="create-user-btn" onClick={handleCreate}>
  Create User
</button>

// Convention: kebab-case, descriptive
// Pattern: <action>-<entity>-<element-type>
// Examples: create-user-btn, user-email-input, delete-confirm-dialog

Wait Strategies

NEVER use hardcoded waits:

// BAD: Hardcoded wait -- flaky, slow
await page.waitForTimeout(3000);

// BAD: Sleep
await new Promise((resolve) => setTimeout(resolve, 2000));

Use explicit wait conditions:

// GOOD: Wait for a specific element to appear
await page.getByRole("heading"<