E2E Testing Guidelines

⚠️ CRITICAL: Always Use Docker for E2E Tests

NEVER run Playwright tests directly on your local machine for this project. Always use Docker.

Why Docker Only?

1. •Screenshot Consistency: Playwright screenshots are OS-dependent. Running tests on macOS will generate darwin screenshots, while CI runs on Linux and generates linux screenshots.
2. •CI Compatibility: Our CI pipeline runs tests in Docker with Linux. Local screenshots won't match CI screenshots.
3. •Font Rendering: Different operating systems render fonts differently, causing pixel-perfect screenshot comparisons to fail.
4. •Reproducibility: Docker ensures everyone gets identical test results regardless of their local environment.

Running E2E Tests

Update Screenshots (Most Common)

When you've made visual changes and need to update the baseline screenshots:

npm run test:e2e:docker:update

This will:

• •Build the app with VITE_TYPEWRITER_SPEED=0 (disables animations)
• •Run ALL Playwright tests
• •Update screenshot baselines in test/**/*-linux.png

Update Specific Test Screenshots

To update screenshots for a specific test file only:

./scripts/playwright-docker.sh test/e2e-mobile.test.ts --update-snapshots

Run Tests Without Updating

To verify tests pass without changing screenshots:

npm run test:e2e:docker

Run Specific Test

./scripts/playwright-docker.sh test/e2e-mobile.test.ts

Environment Variables

VITE_TYPEWRITER_SPEED

Set to 0 to disable the typewriter animation effect during tests. This eliminates timing issues and race conditions.

• •Already configured in scripts/playwright-docker.sh
• •Already configured in playwright.config.ts webServer command
• •Applied during build time via Vite

How It Works

// src/hooks/useTypewriter.ts
const envSpeed = import.meta.env.VITE_TYPEWRITER_SPEED;
if (envSpeed === "0") {
  // Text appears instantly instead of character-by-character
}

Common Pitfalls

❌ DON'T: Run tests locally

# This will create darwin screenshots - DON'T DO THIS
npm run test:e2e
npx playwright test --update-snapshots

✅ DO: Run tests in Docker

# Always use the Docker script
npm run test:e2e:docker:update
./scripts/playwright-docker.sh --update-snapshots

❌ DON'T: Commit darwin screenshots

# If you accidentally created darwin screenshots
rm -rf test/**/*-darwin.png
git status  # Should only show *-linux.png files

✅ DO: Only commit linux screenshots

git status
# Should show files like:
#   test/e2e-mobile.test.ts-snapshots/01-mobile-bios-mobile-chrome-linux.png

Test File Organization

test/
├── e2e-mobile.test.ts              # Mobile-specific tests
├── e2e-desktop.test.ts             # Desktop-specific tests (if exists)
└── e2e-mobile.test.ts-snapshots/   # Auto-generated by Playwright
    ├── 00-mobile-ascii-welcome-mobile-chrome-linux.png
    ├── 01-mobile-bios-mobile-chrome-linux.png
    └── ...

Mobile Test Helpers

dismissBiosIfPresent()

Always call this helper after dismissing the ASCII welcome screen in mobile tests:

await page.locator("[data-e2e=mobile-ascii-welcome]").tap();
await dismissBiosIfPresent(page);

This handles the BIOS startup screen that shows once per session.

Timeouts

Mobile tests use longer timeouts to account for the typewriter effect (even though it's disabled in tests, we keep timeouts for safety):

• •Dialog appearance: 15000ms
• •Options appearing: 15000ms
• •Message typing: 10000ms

Debugging Failed Tests

1. •Check Docker is running: docker ps
2. •Check screenshots: Look at the diff images in test results
3. •Run specific test: ./scripts/playwright-docker.sh test/e2e-mobile.test.ts --debug
4. •Check environment variables: Ensure VITE_TYPEWRITER_SPEED=0 is set

CI Integration

The CI pipeline automatically:

1. •Runs npm run test:e2e:docker
2. •Compares screenshots against committed *-linux.png files
3. •Fails if screenshots don't match (visual regression detected)

Visual Regression Testing

When you change UI:

1. •Make your changes
2. •Run npm run test:e2e:docker:update
3. •Review the updated screenshots carefully
4. •Commit the updated *-linux.png files
5. •NEVER commit *-darwin.png or *-win32.png files

Quick Reference

Remember: If you see darwin or win32 in your git status, you did something wrong. Only linux screenshots should be committed.