e2e-testing

Files (1)

• SKILL.md

SKILL.md (first lines)

# E2E Testing (Playwright Visual Regression)

The assistant frontend is a Flutter web app embedded in the Rust binary.
Playwright captures screenshots of the compiled Flutter SPA at three viewport
sizes (desktop, tablet, mobile) and compares them against committed baselines.

The binary serves the Flutter web build at `/`. The `webServer` config in
`playwright.config.ts` builds the binary (which embeds `flutter build web`)
and starts it with `--auth-token test-token --listen 127.0.0.1:8787`.

## Directory Layout

```text
crates/web-ui/e2e/
  playwright.config.ts     # Config: viewports, server, reporters
  package.json             # Dependencies (playwright, @playwright/test)
  tests/
    visual-regression.spec.ts   # All visual tests
  screenshots/                  # Committed baselines (PNG)
    tests/visual-regression.spec.ts/
      login-desktop-chrome.png
      login-tablet-chrome.png
      login-mobile-chrome.png
      ...
  test-results/            # Generated on failure (diff, actual, expected PNGs)
  playwright-report/       # HTML report (gitignored)
```

## Running Tests

```bash
# From the e2e directory
cd crates/web-ui/e2e

# Run all visual tests (starts server automatically via webServer config)
npx playwright test

# Update baselines after intentional changes
npx playwright test --update-snapshots
# or use the npm script:
npm run test:update

# Run a single test
npx playwright test -g "traces page"

# Run only desktop viewport
npx playwright test --project=desktop-chrome

# Show HTML report after failure
npx playwright show-report
```

The `webServer` config in `playwright.config.ts` automatically builds and
starts the web-ui binary with `--auth-token test-token --listen 127.0.0.1:8787`.
Set `E2E_BASE_URL` to skip the auto-start and use a running server instead.

## Writing Tests

### Test Structure

```typescript
import { test, expect, Page } from "@playwright/test";

const AUTH_TOKEN = "test-token";
const MAX_DIFF_RATIO = 0.03; // 3% tolerance for cross-platform fonts
const CSS_SETTLE_MS = 300; // Wait for CSS transitions

// Authenticate via the login form
async function login(page: Page) {
  await page.goto("/login");
  await page.fill('input[name="token"]', AUTH_TOKEN);
  await page.click('button[type="submit"]');
  await page.waitForURL((url) => !url.pathname.includes("/login"));
}

// Navigate and wait for network idle + CSS settle
async function navigateAndSettle(page: Page, path: string) {
  await page.goto(path, { waitUntil: "networkidle" });
  await page.waitForTimeout(CSS_SETTLE_MS);
}
```

### Adding a New Page Test

```typescript
test("my new page (empty state)", async ({ page }) => {
  await navigateAndSettle(page, "/my-page");
  await expect(page).toHaveScreenshot("my-page-empty.png", {
    fullPage: true,
    maxDiffPixelRatio: MAX_DIFF_RATIO,
  });
});
```

Then generate baselines:

```bash
npx playwright test --update-snapshots -g "my new page"
```

This creates three files in `screenshots/` (one per project/viewport).

### Unauthenticated vs Authenticated Pages

- **Login page:** Test without calling `login()` first
- **All other pages:** Use `test.beforeEach` with `login(page)`:

```typescript
test.describe("Authenticated pages", () => {
  test.beforeEach(async ({ page }) => {
    await login(page);
  });

  test("page name", async ({ page }) => { ... });
});
```

## Cross-Platform Tolerance

From cedricziel/assistant, MIT.

More from cedricziel/assistant