browser-testing

Browser Testing Methodology

1. When to Write a Browser Test vs Unit Test

Browser test (Playwright):

• Cross-component flows (sidebar click updates chat panel)
• SSE streaming verification (message send → streaming indicator → response rendered)
• Real API calls through the full stack (client → Express → Agent SDK)
• CSS/layout regressions visible only in a real browser
• Browser-specific behavior (keyboard shortcuts, focus management)

Unit test (Vitest):

• Individual component rendering and props
• Hook logic and state transitions
• Service functions and data transformations
• Schema validation (Zod)
• Pure utility functions

Rule of thumb: If the behavior spans multiple FSD layers or requires a real server, it's a browser test.

2. Page Object Model Patterns

POMs live in apps/e2e/pages/ and are injected as Playwright fixtures via fixtures/index.ts.

Each POM encapsulates locators and interaction methods for one page or component:

// apps/e2e/pages/FeaturePage.ts
import type { Page, Locator } from '@playwright/test';

export class FeaturePage {
  readonly page: Page;
  readonly primaryAction: Locator;

  constructor(page: Page) {
    this.page = page;
    this.primaryAction = page.getByRole('button', { name: /action/i });
  }

  async doAction() {
    await this.primaryAction.click();
  }
}

Register in fixtures:

// apps/e2e/fixtures/index.ts
import { test as base } from '@playwright/test';
import { FeaturePage } from '../pages/FeaturePage';

export const test = base.extend<{ featurePage: FeaturePage }>({
  featurePage: async ({ page }, use) => {
    await use(new FeaturePage(page));
  },
});

Test files import from fixtures, never from @playwright/test directly:

import { test, expect } from '../../fixtures';

3. Selector Strategy

Priority order:

1. getByRole() — Best: semantic, resilient to UI changes

   page.getByRole('button', { name: /send/i });
   page.getByRole('textbox', { name: /message/i });
   page.getByRole('tab', { name: /settings/i });