APAW/.kilo/commands/e2e-test.md

description

description
Run E2E tests with browser automation in Docker using Playwright

E2E Testing Workflow

End-to-end tests using Playwright in Docker containers. Supports form filling, navigation, screenshots, and visual regression.

Parameters

Parameter	Required	Default	Description
url	Yes	—	Target URL
test	No	all	Test scenario: smoke, login, register, booking, visual, all
issue	No	—	Gitea Issue number for results
viewport	No	desktop	mobile, tablet, desktop

Docker Infrastructure

All tests run inside Docker using mcr.microsoft.com/playwright:v1.52.0-noble.

Local app testing (bridge network)

docker compose -f docker/docker-compose.web-testing.yml run --rm \
  -e TARGET_URL=http://host.docker.internal:3000 -e GITEA_ISSUE=42 visual-tester

External site testing (host network for DNS)

NETWORK_MODE=host DNS_RESOLUTION_ORDER=hostname-first \
docker compose -f docker/docker-compose.web-testing.yml run --rm \
  -e TARGET_URL=https://example.com -e GITEA_ISSUE=42 visual-tester

Available Services

Service	Image	Purpose
visual-tester	playwright:v1.52.0-noble	Full pipeline: screenshots + elements + compare + errors
screenshot-baseline	playwright:v1.52.0-noble	Capture baselines
screenshot-current	playwright:v1.52.0-noble	Capture current screenshots
visual-compare	node:20-alpine	Pixelmatch comparison only
console-monitor	playwright:v1.52.0-noble	Console/network errors

DNS Note

External sites require NETWORK_MODE=host because Chromium inside Docker cannot resolve external DNS by default. The --dns-resolution-order=hostname-first flag is added automatically via lib/browser-launcher.js.

Test Scripts

Script	Description
tests/scripts/visual-test-pipeline.js	Capture + elements + compare + errors + Gitea
tests/scripts/capture-screenshots.js	baseline/current screenshot capture
tests/scripts/compare-screenshots.js	Pixelmatch PNG comparison
tests/scripts/console-error-monitor-standalone.js	Console/network errors + Gitea
tests/scripts/lib/browser-launcher.js	Shared Playwright launch (DNS fix, UA)
tests/scripts/lib/gitea-client.js	Gitea API client (comments, attachments)

Test Scenarios

Smoke Test

docker compose -f docker/docker-compose.web-testing.yml run --rm \
  -e TARGET_URL=https://example.com -e PAGES=/ visual-tester

Login Flow

Invoke @visual-tester or @browser-automation with:

• URL of login page
• Test credentials (from env vars, never hardcoded)
• Expected redirect after login

Use Task tool with subagent_type: "visual-tester"
prompt: "Test login flow at {url} with credentials from env, post results to Gitea Issue #{issue}"

Gitea Integration

When GITEA_ISSUE is set, test results are automatically posted:

• Comment body: Markdown summary table with metrics
• Attachments: Diff screenshots uploaded as issue assets
• Auth: GITEA_TOKEN env var or Basic Auth via GITEA_USER/GITEA_PASSWORD

Required env vars for Gitea

Variable	Description
GITEA_ISSUE	Issue number to post results
GITEA_TOKEN	Pre-existing API token (preferred)
GITEA_USER	Username for Basic Auth (if no token)
GITEA_PASSWORD	Password for Basic Auth (if no token)

Agent Flow

/e2e-test <url>
      ↓
@visual-tester — runs pipeline in Docker
      ↓
[issues found?]
      ↓ yes
@the-fixer — fixes bugs
      ↓
@visual-tester — re-runs to verify

Before Starting (MANDATORY)

1. Check git history for similar E2E tests
2. Verify target URL is accessible from Docker (curl inside container)
3. Use NETWORK_MODE=host for external sites
4. Create baseline screenshots if visual regression needed

Gitea Commenting (MANDATORY)

Post a comment after test completion with:

• Test name and URL
• Step results table
• Screenshot attachments
• Pass/fail status