e2e-test-runner

name	e2e-test-runner
description	Run and debug end-to-end tests for web, iOS, and Android platforms. Use when running e2e tests, demonstrating features to leadership, debugging test failures, checking test status, or when user mentions testing, e2e, Playwright, Maestro, demo, demonstration, or test automation.

E2E Test Runner Skill

This skill helps you run and debug end-to-end tests for the Happy/VibeBox project.

Note: All commands in this document assume you are running from the project root directory.

Platforms Supported

• Web: Playwright-based OAuth authentication tests
• iOS: Maestro tests (future)
• Android: Maestro tests (future)

When to Use This Skill

Automatically activates when:

• User asks to run e2e tests
• User wants to demonstrate features (especially to leadership)
• User mentions test failures or debugging
• User talks about OAuth, authentication testing
• User mentions Playwright or Maestro
• User asks about test status or running tests

Core Workflow

Step 1: Check Prerequisites

Before running tests, ALWAYS verify:

1. Docker services (Postgres + Logto) are running
2. Next.js server is running on correct port with correct env
3. Expo web client is running with correct configuration
4. Happy Server configuration is correct

Use the check-services.sh script or manually verify:

# Check Docker
docker ps | grep -E "postgres|logto"

# Check Next.js server (should be on 3003)
lsof -ti:3003

# Check Expo web (should be on 8081)
lsof -ti:8081

# Verify server env
grep HAPPY_SERVER_URL server/.env.local

Expected configuration:

• Docker: localhost:3001 (Logto), localhost:3002 (Postgres)
• Next.js: localhost:3003 with HAPPY_SERVER_URL=https://api.cluster-fluster.com
• Expo web: localhost:8081 with EXPO_PUBLIC_API_URL=http://localhost:3003
• Happy Server: https://api.cluster-fluster.com (default, DON'T override)

Step 2: Start Missing Services

If services are not running, start them in correct order:

# 1. Start Docker (if needed)
cd docker
docker compose up -d

# 2. Start Next.js server (if needed)
cd server
yarn dev

# 3. Start Expo web with correct env (if needed)
cd client
EXPO_PUBLIC_API_URL=http://localhost:3003 yarn web

CRITICAL:

• NEVER set EXPO_PUBLIC_HAPPY_SERVER_URL - let it use the default official URL
• ALWAYS set EXPO_PUBLIC_API_URL=http://localhost:3003 for local testing

Step 3: Run the Test

For web OAuth tests:

cd client/tests/e2e/web
EXPO_PUBLIC_API_URL=http://localhost:3003 node oauth-authentication.test.js

The test will:

• Open a browser window
• Navigate to VibeBox at http://localhost:8081
• Click "Sign In with Logto"
• Create a new user account automatically
• Complete the full OAuth flow
• Verify authentication state
• Take screenshots at each step
• Display success/failure clearly

Step 4: Interpret Results

Success indicators:

• ✅ All steps show green checkmarks
• ✅ Final URL is http://localhost:8081/ (NOT /callback)
• ✅ localStorage contains ID token
• ✅ Authentication state shows isAuthenticated=true
• ✅ No 404 or 500 errors in the logs

Common issues:

• If final URL is /callback → Check env configuration
• If 404 errors on /api/* → Check EXPO_PUBLIC_API_URL
• If CORS errors on /v1/* → Check Happy Server URL (should NOT be localhost)
• If test hangs → Check all services are running

See TROUBLESHOOTING.md for detailed error resolution.

Key Files and Locations

• Test file: client/tests/e2e/web/oauth-authentication.test.js
• Test docs: client/tests/e2e/web/README.md
• Screenshots: client/tests/e2e/web/tmp/oauth-redirect/
• Server config: server/.env.local
• API client: client/sources/services/api.ts
• Happy Server config: client/sources/sync/serverConfig.ts

Environment Variables Reference

Client (Expo)

• EXPO_PUBLIC_API_URL - VibeBox Platform API (set to http://localhost:3003 for local dev)
• EXPO_PUBLIC_HAPPY_SERVER_URL - Happy Server API (DON'T set, use default https://api.cluster-fluster.com)

Server (Next.js)

• HAPPY_SERVER_URL - Happy Server API (set to https://api.cluster-fluster.com in .env.local)

Best Practices

1. Always check prerequisites first - Don't assume services are running
2. Use correct environment variables - Wrong config causes 90% of issues
3. Read the full test output - Don't just look at the final status
4. Check for 404/500 errors - Success status doesn't mean no errors
5. Verify final URL - Should be / not /callback
6. Take screenshots - Tests save screenshots automatically for debugging

Demonstration Mode

When user asks to "demonstrate to leadership" or similar:

1. Ensure all services are running perfectly
2. Run the test with full output visible
3. Highlight key success indicators
4. Show screenshots if needed
5. Emphasize the complete OAuth flow (no popups, full redirect)

Related Documentation

• Prerequisites: See PREREQUISITES.md
• Troubleshooting: See TROUBLESHOOTING.md
• Service check script: scripts/check-services.sh