Preview Testing

Deploy a feature branch to Vercel preview, run E2E tests, create and merge a PR, then verify the main preview. This skill is executed by the orchestrator directly in Claude Code.

Prerequisites

• gh CLI installed and authenticated
• VERCEL_TOKEN environment variable set
• VERCEL_BYPASS_SECRET environment variable set (for Vercel Deployment Protection bypass)
• E2E tests exist (falls back to smoke test if none)

STOP. Verify all prerequisites above before running any deployment commands. Missing prerequisites cause silent failures at deploy time.

Flow

1. Push Branch

git push -u origin <branch>

Capture SHA:

git rev-parse HEAD

2. Discover Preview URL

Use the Vercel REST API to find the deployment by commit SHA:

curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
  "https://api.vercel.com/v6/deployments?meta-gitCommitSha=<sha>"

Or via CLI:

vercel ls --meta gitCommitSha=<sha> --token $VERCEL_TOKEN

Poll until deployment state is READY. Timeout: 10 minutes.

3. Run E2E Tests

BASE_URL=<preview-url> pnpm test:e2e

If no E2E tests exist, run the smoke test instead (see below).

4. Handle E2E Failure

Fix issues, push again, retry from step 2. Max 3 retries. If exhausted -> add awaiting-input label + post @Ameet comment with failure details.

5. Create PR

gh pr create --base main --title "feat: <issue-title> [PROJ-<id>]" --body "Closes PROJ-<id>"

Wait for CI to pass.

6. Merge

gh pr merge --squash --delete-branch

7. Capture Merge SHA

gh pr view --json mergeCommit --jq '.mergeCommit.oid'

8. Poll Main Preview

Discover the main preview deployment by merge SHA using the same Vercel API as step 2. Poll until READY. Timeout: 10 minutes.

9. Run E2E on Main Preview

BASE_URL=<main-preview-url> pnpm test:e2e

10. Handle Result

• Pass -> Done. Move Linear issue to Done.
• Fail -> Add awaiting-input label + post @Ameet comment with failure details. No revert -- preview only, not production.

Smoke Test (Fallback)

When no E2E tests exist, use Playwright MCP:

1. Navigate to the app's primary route (e.g., /dashboard or /)
2. Verify HTTP 200 response
3. Verify no uncaught JS errors in browser console
4. Verify the page renders non-empty content (snapshot shows meaningful UI)

Vercel Deployment Protection Bypass

If Vercel Deployment Protection is enabled, append the bypass secret to test URLs:

<preview-url>?x-vercel-protection-bypass=$VERCEL_BYPASS_SECRET

Or set x-vercel-protection-bypass header in Playwright config's extraHTTPHeaders.

Failure Paths

Failure	Action
E2E fails 3x on preview	awaiting-input + @Ameet with failure details
Vercel polling times out (10 min)	awaiting-input + @Ameet
CI fails after PR creation	Fix CI issues, push, retry
E2E fails on main preview	awaiting-input + @Ameet (no revert)

Transitional Pattern

This skill is the baseline for projects without CI/CD automation. When this skill runs 10+ times without needing adaptive fixes, consider migrating to GitHub Actions with automated preview testing.

Related

• webapp-testing skill -- local testing (localhost). This skill handles deployed environments.
• standards/core/linear-lifecycle.md -- Preview Testing status definition
• standards/reference/environments.md -- Three-environment model (local, preview, production)