Stats
Actions
Tags
From zacs-claude-skills
Deploy to Vercel preview and run Playwright E2E tests against staging database. Use when user says "vercel e2e test", "test on vercel", "deploy and test", "e2e on staging", or "preview deploy test".
How this skill is triggered — by the user, by Claude, or both
Slash command
/zacs-claude-skills:skills/vercel-e2e-testThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
> Deploy to Vercel preview and run Playwright E2E tests against staging Supabase.
Deploy to Vercel preview and run Playwright E2E tests against staging Supabase.
<when_to_use>
Invoke when user says:
Optional argument: Specific test file pattern (e.g., vercel e2e test session-creation)
</when_to_use>
| Phase | Action | Duration |
|---|---|---|
| 0 | Prerequisite checks | 5-10s |
| 1 | Deploy to Vercel preview | 60-120s |
| 2 | Extract preview URL | 2s |
| 3 | Start local worker | 20-30s |
| 4 | Start edge functions | 10-20s |
| 5 | Run Playwright tests | 2-10min |
| 6 | Stop worker & functions | 2s |
| 7 | Report results | 5s |
| 8 | Offer next steps | User decision |
CRITICAL: Phase 0 must pass before proceeding. Fail fast, don't waste 30 minutes to discover missing config.
Track progress with TodoWrite.
Run ALL checks before proceeding. STOP immediately if any fail.
# Verify .env.e2e exists (staging database config)
test -f .env.e2e && echo "✓ .env.e2e exists" || echo "✗ MISSING: .env.e2e"
# Verify supabase/.env.local exists (edge function secrets)
test -f supabase/.env.local && echo "✓ supabase/.env.local exists" || echo "✗ MISSING: supabase/.env.local"
# Check .env.e2e has staging Supabase config
grep -q "VITE_SUPABASE_URL=https://<staging-project-id>" .env.e2e && echo "✓ Staging URL configured" || echo "✗ MISSING: VITE_SUPABASE_URL in .env.e2e"
grep -q "SUPABASE_SERVICE_ROLE_KEY" .env.e2e && echo "✓ Service role key present" || echo "✗ MISSING: SUPABASE_SERVICE_ROLE_KEY in .env.e2e"
# Check supabase/.env.local has AI key for edge functions
grep -q "ANTHROPIC_API_KEY" supabase/.env.local && echo "✓ Anthropic API key present" || echo "✗ MISSING: ANTHROPIC_API_KEY in supabase/.env.local"
docker info > /dev/null 2>&1 && echo "✓ Docker is running" || echo "✗ FAILED: Docker is not running - start Docker Desktop"
# Check port 3001 (worker) is free
curl -s http://localhost:3001/health > /dev/null 2>&1 && echo "⚠ Port 3001 in use (worker may already be running)" || echo "✓ Port 3001 available"
# Check port 54321 (edge functions) is free
curl -s http://localhost:54321/functions/v1/ > /dev/null 2>&1 && echo "⚠ Port 54321 in use (edge functions may already be running)" || echo "✓ Port 54321 available"
npx vercel whoami > /dev/null 2>&1 && echo "✓ Vercel CLI authenticated" || echo "✗ FAILED: Run 'npx vercel login' first"
| Check | Required | If Failed |
|---|---|---|
| .env.e2e exists | Yes | STOP - Create from .env.e2e.example |
| supabase/.env.local exists | Yes | STOP - Create with ANTHROPIC_API_KEY |
| Staging URL in .env.e2e | Yes | STOP - Add VITE_SUPABASE_URL |
| Service role key | Yes | STOP - Add SUPABASE_SERVICE_ROLE_KEY |
| Anthropic API key | Yes | STOP - Add to supabase/.env.local |
| Docker running | Yes | STOP - Start Docker Desktop |
| Port 3001 free | No | OK if worker already running |
| Port 54321 free | No | OK if edge functions already running |
| Vercel authenticated | Yes | STOP - Run npx vercel login |
Only proceed to Phase 1 if all required checks pass.
Run the deployment command:
npx vercel
Parse output to find preview URL. Vercel output includes:
Preview: https://project-xxx.vercel.app
If deployment fails:
Capture URL from deployment output using pattern: Preview: (https://[^\s]+)
Store URL for test execution.
Start a local worker against staging Supabase so worker-dependent tests can run.
CRITICAL: Use --env-file=.env.e2e to load staging credentials. The worker will connect to whichever database is specified in its environment.
# Build worker
npm run worker:build
# Start worker with staging env and capture ALL output (stdout + stderr)
node --env-file=.env.e2e dist/worker.mjs 2>&1
Important: Run in background and capture output to a file:
node --env-file=.env.e2e dist/worker.mjs 2>&1
Wait for health check at http://localhost:3001/health (max 30 seconds).
Verify worker connection: Check worker logs for:
Starting automation worker...Connecting to Supabase with supabaseUrl: "https://<staging-project-id>.supabase.co"Supabase connectivity verified (confirms database connection)Worker started successfullyStarted pollingIf connectivity check fails, worker will retry 5 times with exponential backoff before failing.
If worker fails to start:
.env.e2e has SUPABASE_SERVICE_ROLE_KEYcurl http://localhost:3001/health)<staging-project-id>.supabase.co)Start Supabase edge functions locally so @needs-edge-functions tests can run.
Prerequisites: Ensure supabase/.env.local contains:
ANTHROPIC_API_KEY - Required for AI chat functionsSUPABASE_SERVICE_ROLE_KEY - For database access# Start edge functions in background
npx supabase functions serve --env-file supabase/.env.local
Important: Run in background with run_in_background: true.
Wait for functions to be ready by checking health (max 30 seconds):
curl -s http://localhost:54321/functions/v1/ai-chat -X OPTIONS
A 200 response indicates functions are ready.
If edge functions fail to start:
supabase/.env.local exists with required keysnpx supabase start if local Supabase isn't runningRun tests and wait for completion:
# Run all chromium projects with retries for flaky test resilience
# Use cross-env for cross-platform compatibility (Windows + Unix)
npx cross-env PLAYWRIGHT_BASE_URL="<preview-url>" npx playwright test --project=chromium --project=chromium-clean --project=chromium-admin --project=chromium-with-worker --project=chromium-with-edge-functions --retries=2
User can watch progress directly in the terminal output.
Test projects available (all 5 run by default):
| Project | Description | When to Use |
|---|---|---|
chromium | Main test suite | Default |
chromium-clean | Login/onboarding tests | Fresh browser |
chromium-admin | Admin panel tests | Admin features |
chromium-with-worker | Tests tagged @needs-worker | Worker-dependent |
chromium-with-edge-functions | Tests tagged @needs-edge-functions | Edge function tests |
All projects work because local worker and edge functions are running.
After tests complete (pass or fail), stop the local worker and edge functions.
If started with run_in_background: true: Use the KillShell tool with the task IDs returned when processes were started.
Alternative - kill by port (cross-platform):
# Stop worker
npx kill-port 3001
# Stop edge functions
npx kill-port 54321
Parse test output for:
Display summary:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Vercel E2E Test Results
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Preview URL: https://...vercel.app
Tests: 42 passed, 0 failed, 0 skipped
Status: PASS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Use AskUserQuestion to offer options:
npx playwright show-report)Vercel Preview uses staging Supabase (<staging-project-id>).
| Config | Source | Database |
|---|---|---|
| Vercel Preview | Vercel env vars | Staging |
| Playwright local | .env.e2e (auto-loaded) | Staging |
The playwright.config.ts auto-detects external URLs:
const isExternalUrl = process.env.PLAYWRIGHT_BASE_URL?.startsWith("https://");
config({ path: isExternalUrl ? ".env.e2e" : ".env.local" });
NEVER run tests against production (www.eoscrm.org).
Playwright Workers: 4 locally (configurable), 2 in CI
Since frontend runs on Vercel and tests run locally, you can increase workers:
npx playwright test --workers=8<staging_maintenance>
Keep staging Supabase in sync with production schema.
After adding new migrations to the codebase:
# Link to staging (if not already linked)
npx supabase link --project-ref <staging-project-id>
# Push migrations
npx supabase db push
If supabase/seed.sql is updated:
npx cross-env PGPASSWORD='<staging-password>' psql -h aws-0-us-west-2.pooler.supabase.com -p 5432 -d postgres -U postgres.<staging-project-id> -f supabase/seed.sql
Use pooler connection for reliability.
# Remove existing Preview value
npx vercel env rm VITE_SUPABASE_URL preview
# Add new value for Preview only
echo "<new-value>" | npx vercel env add VITE_SUPABASE_URL preview
</staging_maintenance>
| Issue | Cause | Fix |
|---|---|---|
| "Failed to fetch" in tests | Staging Supabase down or wrong env | Check .env.e2e points to staging |
| "Seed user not found" | Staging missing seed data | Re-run supabase/seed.sql on staging |
| Deployment fails | Not logged in / build error | Run npx vercel login, fix build |
| Test timeout | Vercel cold start | Increase timeout or retry |
| Auth tests fail | Dev login form not showing | Verify VITE_ENABLE_E2E_LOGIN in Vercel |
| Worker health check fails | Port 3001 in use or build stale | Kill port 3001, run npm run worker:build |
| Worker tests timeout | Worker not processing events | Check worker logs, verify staging DB |
| "Cannot connect to Supabase" | DNS/network issue, wrong URL | Check network, verify .env.e2e URL, worker will retry |
| "Invalid JWT" 401 | Supabase ES256 JWT migration (GitHub #41691) | Add verify_jwt = false to config.toml, redeploy |
| Auth cache mismatch | Local tokens used against staging | Clear playwright/.auth/*.json before running |
| CORS errors on preview | Preview URL not in allowlist | Update getCorsHeaders() to allow *.vercel.app pattern |
| Worker events stay pending | Tests using different DB than worker | Use cross-env for PLAYWRIGHT_BASE_URL (see Phase 5) |
| Edge function tests fail | Edge functions not running | Run Phase 0 checks, start supabase functions serve |
| Docker not running | Required for edge functions | Start Docker Desktop before running skill |
| Missing ANTHROPIC_API_KEY | Edge functions need AI key | Add to supabase/.env.local |
<approval_gates>
| Gate | Phase | Question |
|---|---|---|
| Prerequisites | 0 | STOP if any required check fails |
| View Report | 7 | "Open Playwright report?" |
</approval_gates>
<safety_rules>
*.vercel.app pattern</safety_rules>
<quick_reference>
# Phase 0: Prerequisite checks (run ALL before proceeding)
test -f .env.e2e && echo "✓ .env.e2e" || echo "✗ MISSING .env.e2e"
test -f supabase/.env.local && echo "✓ supabase/.env.local" || echo "✗ MISSING supabase/.env.local"
grep -q "SUPABASE_SERVICE_ROLE_KEY" .env.e2e && echo "✓ Service key" || echo "✗ MISSING key"
grep -q "ANTHROPIC_API_KEY" supabase/.env.local && echo "✓ Anthropic key" || echo "✗ MISSING key"
docker info > /dev/null 2>&1 && echo "✓ Docker running" || echo "✗ START DOCKER"
npx vercel whoami > /dev/null 2>&1 && echo "✓ Vercel auth" || echo "✗ RUN: npx vercel login"
# Phase 1: Deploy preview (only if Phase 0 passes)
npx vercel
# Build and start worker against staging (CRITICAL: use --env-file)
npm run worker:build
node --env-file=.env.e2e dist/worker.mjs 2>&1
# Start edge functions (requires Docker running)
npx supabase functions serve --env-file supabase/.env.local
# Run tests against preview (all 5 chromium projects)
# cross-env required for Windows compatibility
npx cross-env PLAYWRIGHT_BASE_URL="<url>" npx playwright test --project=chromium --project=chromium-clean --project=chromium-admin --project=chromium-with-worker --project=chromium-with-edge-functions --retries=2
# Run specific test
npx cross-env PLAYWRIGHT_BASE_URL="<url>" npx playwright test session-creation --retries=2
# Stop worker and edge functions (use KillShell tool with task ID, or kill by port)
npx kill-port 3001 54321
# View report
npx playwright show-report
</quick_reference>
<version_history>
supabase functions serve for @needs-edge-functions testscross-env for PLAYWRIGHT_BASE_URL and PGPASSWORDGet-Process | Stop-Process with npx kill-portKillShell tool for background worker processese2e-vercel-testing-patterns.mdnode --env-file=.env.e2e to load staging credentials2>&1 to capture all worker output (pino logs go to stdout)--retries=2 by default to match CI behaviorchromium-with-worker</version_history>
npx claudepluginhub enbyaugust/zacs-claude-skillsTests local web applications using Playwright: verifies frontend functionality, debugs UI behavior, captures screenshots, views logs. Mandatory before declaring implementation complete.
Guides Vitest testing for Cloudflare Workers with @cloudflare/vitest-pool-workers and Miniflare. Covers setup, binding mocks (D1/KV/R2/DO/Queues/AI), integration tests, failures, mock errors, and coverage.