Playwright Testing for Next.js

# Playwright Testing for Next.js

Build comprehensive end-to-end test suites for your Google Antigravity applications using Playwright. This guide covers setup, page objects, visual testing, and CI/CD integration.

## Playwright Configuration

Set up Playwright with optimal configuration for Next.js:

```typescript
// playwright.config.ts
import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "./tests/e2e",
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: [
    ["html", { open: "never" }],
    ["json", { outputFile: "test-results/results.json" }],
    process.env.CI ? ["github"] : ["list"],
  ],
  use: {
    baseURL: process.env.PLAYWRIGHT_BASE_URL || "http://localhost:3000",
    trace: "on-first-retry",
    screenshot: "only-on-failure",
    video: "retain-on-failure",
  },
  projects: [
    {
      name: "chromium",
      use: { ...devices["Desktop Chrome"] },
    },
    {
      name: "firefox",
      use: { ...devices["Desktop Firefox"] },
    },
    {
      name: "webkit",
      use: { ...devices["Desktop Safari"] },
    },
    {
      name: "mobile-chrome",
      use: { ...devices["Pixel 5"] },
    },
    {
      name: "mobile-safari",
      use: { ...devices["iPhone 12"] },
    },
  ],
  webServer: {
    command: "npm run dev",
    url: "http://localhost:3000",
    reuseExistingServer: !process.env.CI,
    timeout: 120 * 1000,
  },
});
```

## Page Object Pattern

Implement maintainable page objects for your tests:

```typescript
// tests/e2e/pages/LoginPage.ts
import { Page, Locator, expect } from "@playwright/test";

export class LoginPage {
  readonly page: Page;
  readonly emailInput: Locator;
  readonly passwordInput: Locator;
  readonly submitButton: Locator;
  readonly errorMessage: Locator;
  readonly googleButton: Locator;

  constructor(page: Page) {
    this.page = page;
    this.emailInput = page.getByLabel("Email");
    this.passwordInput = page.getByLabel("Password");
    this.submitButton = page.getByRole("button", { name: "Sign in" });
    this.errorMessage = page.getByRole("alert");
    this.googleButton = page.getByRole("button", { name: /google/i });
  }

  async goto() {
    await this.page.goto("/auth/login");
    await this.page.waitForLoadState("networkidle");
  }

  async login(email: string, password: string) {
    await this.emailInput.fill(email);
    await this.passwordInput.fill(password);
    await this.submitButton.click();
  }

  async expectError(message: string) {
    await expect(this.errorMessage).toContainText(message);
  }

  async expectLoggedIn() {
    await expect(this.page).toHaveURL("/dashboard");
  }
}
```

## Test Fixtures and Helpers

Create reusable fixtures for common test scenarios:

```typescript
// tests/e2e/fixtures/auth.ts
import { test as base } from "@playwright/test";
import { LoginPage } from "../pages/LoginPage";
import { DashboardPage } from "../pages/DashboardPage";

type AuthFixtures = {
  loginPage: LoginPage;
  dashboardPage: DashboardPage;
  authenticatedPage: DashboardPage;
};

export const test = base.extend<AuthFixtures>({
  loginPage: async ({ page }, use) => {
    const loginPage = new LoginPage(page);
    await use(loginPage);
  },
  dashboardPage: async ({ page }, use) => {
    const dashboardPage = new DashboardPage(page);
    await use(dashboardPage);
  },
  authenticatedPage: async ({ page, context }, use) => {
    // Set up authentication state
    await context.addCookies([
      {
        name: "auth-token",
        value: process.env.TEST_AUTH_TOKEN!,
        domain: "localhost",
        path: "/",
      },
    ]);
    const dashboardPage = new DashboardPage(page);
    await dashboardPage.goto();
    await use(dashboardPage);
  },
});

export { expect } from "@playwright/test";
```

## Visual Regression Testing

Implement visual testing for UI consistency:

```typescript
// tests/e2e/visual/homepage.spec.ts
import { test, expect } from "@playwright/test";

test.describe("Homepage Visual Tests", () => {
  test("homepage matches snapshot", async ({ page }) => {
    await page.goto("/");
    await page.waitForLoadState("networkidle");
    
    // Wait for dynamic content to stabilize
    await page.waitForTimeout(500);
    
    await expect(page).toHaveScreenshot("homepage.png", {
      maxDiffPixelRatio: 0.01,
      animations: "disabled",
    });
  });

  test("dark mode matches snapshot", async ({ page }) => {
    await page.goto("/");
    await page.click("[data-testid=theme-toggle]");
    await expect(page).toHaveScreenshot("homepage-dark.png");
  });
});
```

## Best Practices

1. **Isolation**: Each test should be independent and not rely on previous test state
2. **Data Management**: Use test fixtures for database seeding and cleanup
3. **Selectors**: Prefer accessible selectors (getByRole, getByLabel) over CSS selectors
4. **Waiting**: Use proper wait strategies instead of arbitrary timeouts
5. **Parallelization**: Design tests to run in parallel for faster CI pipelines
6. **Reporting**: Generate comprehensive reports for debugging failures