// ALWAYS: Use Page Object Model for E2E test maintainability
// tests/e2e/pages/dashboard.page.ts
 
import { type Page, type Locator, expect } from "@playwright/test";
 
export class DashboardPage {
  readonly page: Page;
  readonly heading: Locator;
  readonly projectList: Locator;
  readonly createProjectButton: Locator;
  readonly searchInput: Locator;
  readonly emptyState: Locator;
 
  constructor(page: Page) {
    this.page = page;
    this.heading = page.getByRole("heading", { name: "Dashboard" });
    this.projectList = page.getByTestId("project-list");
    this.createProjectButton = page.getByRole("button", { name: "New Project" });
    this.searchInput = page.getByPlaceholder("Search projects...");
    this.emptyState = page.getByTestId("empty-state");
  }
 
  async goto() {
    await this.page.goto("/dashboard");
    await expect(this.heading).toBeVisible();
  }
 
  async searchProjects(query: string) {
    await this.searchInput.fill(query);
    // Wait for debounced search to complete
    await this.page.waitForResponse((res) =>
      res.url().includes("/api/projects") && res.status() === 200
    );
  }
 
  async createProject(name: string) {
    await this.createProjectButton.click();
    const dialog = this.page.getByRole("dialog");
    await dialog.getByLabel("Project name").fill(name);
    await dialog.getByRole("button", { name: "Create" }).click();
    await expect(dialog).toBeHidden();
  }
 
  async getProjectCount(): Promise<number> {
    return this.projectList.getByRole("article").count();
  }
}

// ALWAYS: Use custom fixtures for reusable test setup
// tests/e2e/fixtures/auth.fixture.ts
 
import { test as base, expect } from "@playwright/test";
import { DashboardPage } from "../pages/dashboard.page";
 
interface AuthFixtures {
  authenticatedPage: DashboardPage;
  adminPage: DashboardPage;
}
 
export const test = base.extend<AuthFixtures>({
  authenticatedPage: async ({ page, context }, use) => {
    // Set auth cookies from stored state
    await context.addCookies([{
      name: "session",
      value: process.env.TEST_SESSION_TOKEN!,
      domain: "localhost",
      path: "/",
    }]);
 
    const dashboardPage = new DashboardPage(page);
    await dashboardPage.goto();
    await use(dashboardPage);
  },
 
  adminPage: async ({ browser }, use) => {
    const context = await browser.newContext({
      storageState: "tests/e2e/.auth/admin.json",
    });
    const page = await context.newPage();
    const dashboardPage = new DashboardPage(page);
    await dashboardPage.goto();
    await use(dashboardPage);
    await context.close();
  },
});
 
export { expect };

// ALWAYS: Mock external APIs at the network level with MSW
// tests/mocks/handlers.ts
 
import { http, HttpResponse } from "msw";
 
export const handlers = [
  http.get("/api/users/:id", ({ params }) => {
    return HttpResponse.json({
      data: {
        id: params.id,
        name: "Test User",
        email: "test@example.com",
        role: "member",
      },
    });
  }),
 
  http.post("/api/orders", async ({ request }) => {
    const body = await request.json();
    return HttpResponse.json({
      data: {
        id: "order-123",
        ...body,
        status: "pending",
        createdAt: new Date().toISOString(),
      },
    }, { status: 201 });
  }),
];
 
// tests/integration/components/order-form.test.tsx
import { render, screen, waitFor } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { server } from "../../mocks/server";
import { http, HttpResponse } from "msw";
import { OrderForm } from "@/components/orders/order-form";
 
describe("OrderForm", () => {
  it("submits order and shows success message", async () => {
    const user = userEvent.setup();
    render(<OrderForm />);
 
    await user.type(screen.getByLabelText("Product"), "Widget");
    await user.type(screen.getByLabelText("Quantity"), "5");
    await user.click(screen.getByRole("button", { name: "Place Order" }));
 
    await waitFor(() => {
      expect(screen.getByText("Order placed successfully")).toBeInTheDocument();
    });
  });
 
  it("displays validation errors for invalid input", async () => {
    const user = userEvent.setup();
    render(<OrderForm />);
 
    await user.click(screen.getByRole("button", { name: "Place Order" }));
 
    expect(screen.getByText("Product is required")).toBeInTheDocument();
    expect(screen.getByText("Quantity must be at least 1")).toBeInTheDocument();
  });
 
  it("handles server error gracefully", async () => {
    server.use(
      http.post("/api/orders", () => {
        return HttpResponse.json(
          { error: { code: "INTERNAL_ERROR", message: "Server error" } },
          { status: 500 },
        );
      }),
    );
 
    const user = userEvent.setup();
    render(<OrderForm />);
 
    await user.type(screen.getByLabelText("Product"), "Widget");
    await user.type(screen.getByLabelText("Quantity"), "5");
    await user.click(screen.getByRole("button", { name: "Place Order" }));
 
    await waitFor(() => {
      expect(screen.getByRole("alert")).toHaveTextContent(
        "Something went wrong. Please try again.",
      );
    });
  });
});

// ALWAYS: Use typed factories instead of inline test data
// tests/factories/user.factory.ts
 
import { faker } from "@faker-js/faker";
 
interface User {
  id: string;
  name: string;
  email: string;
  role: "admin" | "member" | "viewer";
  createdAt: Date;
}
 
export function createUser(overrides: Partial<User> = {}): User {
  return {
    id: faker.string.uuid(),
    name: faker.person.fullName(),
    email: faker.internet.email(),
    role: "member",
    createdAt: faker.date.recent({ days: 30 }),
    ...overrides,
  };
}
 
export function createUsers(count: number, overrides: Partial<User> = {}): User[] {
  return Array.from({ length: count }, () => createUser(overrides));
}
 
// Usage in tests
const admin = createUser({ role: "admin" });
const teamMembers = createUsers(5, { role: "member" });

// ALWAYS: Include accessibility assertions in E2E tests
import { test, expect } from "@playwright/test";
import AxeBuilder from "@axe-core/playwright";
 
test.describe("Accessibility", () => {
  test("dashboard has no critical accessibility violations", async ({ page }) => {
    await page.goto("/dashboard");
    await page.waitForLoadState("networkidle");
 
    const results = await new AxeBuilder({ page })
      .withTags(["wcag2a", "wcag2aa", "wcag21aa"])
      .exclude(".third-party-widget") // Exclude third-party content
      .analyze();
 
    expect(results.violations).toEqual([]);
  });
 
  test("modal trap focus correctly", async ({ page }) => {
    await page.goto("/dashboard");
    await page.getByRole("button", { name: "New Project" }).click();
 
    const dialog = page.getByRole("dialog");
    await expect(dialog).toBeVisible();
 
    // Verify focus is trapped in modal
    const firstInput = dialog.getByLabel("Project name");
    await expect(firstInput).toBeFocused();
 
    // Tab through all focusable elements
    await page.keyboard.press("Tab");
    await page.keyboard.press("Tab");
    await page.keyboard.press("Tab");
 
    // Focus should cycle back within dialog
    const focusedElement = page.locator(":focus");
    await expect(focusedElement).toHaveAttribute("role", /(button|textbox|combobox)/);
    expect(await dialog.evaluate(
      (el, focused) => el.contains(focused),
      await focusedElement.elementHandle(),
    )).toBe(true);
  });
});

# ALWAYS: Shard E2E tests for parallel execution
# .github/workflows/test.yml
name: Tests
on: [pull_request]
 
jobs:
  unit-integration:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm vitest run --coverage
 
  e2e:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        shard: [1/4, 2/4, 3/4, 4/4]
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm exec playwright install --with-deps
      - run: pnpm exec playwright test --shard=${{ matrix.shard }}
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-report-${{ strategy.job-index }}
          path: playwright-report/