test-e2e-account

Account Service E2E Test Executor

Execute E2E tests for the ClaudeMix account service with complete workflow management.

When to Use

• User asks to "run E2E tests for account"
• User requests "test account service"
• User wants to verify account functionality
• After implementing account-related features
• Before committing account service changes

Execution Workflow

1. Pre-flight Check

Verify environment readiness:

• Confirm project directory
• Check if dev server is running on port 8788
• Kill existing server if necessary for clean state

Optional: Clean Wrangler cache (if previous tests had issues):

npm run clean:wrangler

This clears .wrangler/state/v3 and reapplies D1 migrations, resolving cache-related issues.

2. Start Development Server

npm run dev:wrangler

Wait criteria:

• Build completion message appears
• "Ready on http://127.0.0.1:8788" confirmation
• Minimum 10 seconds after ready message

Why: Server needs time to initialize Wrangler runtime and D1 database.

3. Execute Tests

npx playwright test tests/e2e/account \
  --config=tests/e2e/playwright.config.ts \
  --reporter=list

Critical flags:

• --config=tests/e2e/playwright.config.ts - MANDATORY (project-specific config)
• --reporter=list - Recommended (suppresses HTML report generation)

4. Report Results

Provide clear summary:

Per-test status:

• ✅ Passed: Test name
• ❌ Failed: Test name + concise error

Overall summary:

• Total tests: X
• Passed: X
• Failed: X
• Duration: X seconds

5. Cleanup (CRITICAL)

Always stop dev server:

1. Locate background task ID
2. Execute kill command
3. Verify server stopped

Why critical: Leaving server running causes port conflicts in next execution.

Troubleshooting Guidance

If Connection Errors Occur

Symptoms:

• ERR_CONNECTION_REFUSED
• All tests fail immediately
• "Cannot navigate to invalid URL"
• Server shows "Ready" but connections timeout

Diagnosis: Windows/Wrangler cache issue

Solution (try in order):

1. First attempt: Clean Wrangler cache

   npm run clean:wrangler
   

   Then retry the test execution.

2. If issue persists: Recommend PC restart to user

Why this order: Cache cleanup resolves most issues quickly. PC restart is needed only for deeper Windows/Wrangler process problems.

Evidence: Historical cases (2025-12-26, 2025-12-28):

• Navigation test failures → Cache clean → Resolved
• Modal rendering issues → PC restart → Resolved
• FlashMessage problems → PC restart → Resolved
• Login SESSION_KV errors → Cache clean → Resolved

If Specific Tests Fail

Provide:

• Error context analysis
• Specific failure reason
• Suggested fix (if code issue)
• PC restart recommendation (if Windows/Wrangler issue)

Success Criteria

• Server started successfully
• Tests executed with correct configuration
• Results clearly reported to user
• Server cleanly stopped
• Any failures diagnosed with actionable guidance

Related Resources

• E2E test guidelines: CLAUDE.md lines 142-208
• Playwright config: tests/e2e/playwright.config.ts
• Test files: tests/e2e/account/*.spec.ts

Common Pitfalls to Avoid

1. Server not stopped: Port 8788 remains occupied
2. Insufficient wait time: Tests start before server ready
3. Missing config flag: Wrong configuration used
4. Ignoring Windows cache: Repeated failures without PC restart