Test Vercel preview deployments

1. Let Vercel tell GitHub about deployments

2. Test the pull request’s preview

name: Peeps
on:
  workflow_dispatch:
    inputs:
      mode: { type: string, required: true }
      sessionId: { type: string, required: false }
      ref: { type: string, required: false }
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read
  deployments: read # read the preview Vercel recorded
  statuses: read # tell "deployment events off" apart from "still building"
  id-token: write # OIDC: to Peeps, and to Vercel's Trusted Sources

jobs:
  peeps:
    name: "peeps ${{ inputs.mode || 'report' }} ${{ inputs.sessionId || '' }}"
    runs-on: ubuntu-latest
    container: mcr.microsoft.com/playwright:v1.59.1-jammy
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ inputs.ref || github.ref }}
      - run: npm ci
      - name: Test production
        if: github.event_name == 'push'
        env:
          PRODUCTION_URL: ${{ vars.PRODUCTION_URL }}
        run: echo "BASE_URL=$PRODUCTION_URL" >> "$GITHUB_ENV"
      - uses: Peeps-Labs/peeps-action@v1
        with:
          mode: ${{ inputs.mode || 'ci' }}
          session-id: ${{ inputs.sessionId }}
          preview: vercel

• It finds the GitHub deployment Vercel recorded for the pull request’s head commit, in the Preview environment, and waits until it succeeds: up to 10 minutes, or preview-timeout seconds.
• When the repository deploys several Vercel projects, name the one to test with preview-project, for example preview-project: web.
• When Vercel deployed the commit but recorded no GitHub deployment, it stops at once and tells you to turn on deployment_status Events (step 1).
• A BASE_URL your workflow sets itself wins.
• When Peeps starts the workflow to fix a failed test, the fix runs on the preview of the commit it checked out, so a pull request’s failure is fixed against that pull request’s own preview.

use: { baseURL: process.env.BASE_URL || "http://localhost:3000" },

3. Get through Deployment Protection

import { test as base } from "@playwright/test";

const requestUrl = process.env.ACTIONS_ID_TOKEN_REQUEST_URL;
const requestToken = process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
let cached: { token: string; expiresAt: number } | null = null;

async function trustedSourceToken(): Promise<string | null> {
  if (!requestUrl || !requestToken) return null; // not in GitHub Actions
  if (cached && Date.now() < cached.expiresAt - 60_000) return cached.token;
  const res = await fetch(requestUrl, {
    headers: { authorization: `Bearer ${requestToken}` },
  });
  if (!res.ok) throw new Error(`GitHub OIDC token request failed: ${res.status}`);
  const { value } = (await res.json()) as { value: string };
  const { exp } = JSON.parse(
    Buffer.from(value.split(".")[1]!, "base64url").toString(),
  ) as { exp: number };
  cached = { token: value, expiresAt: exp * 1000 };
  return value;
}

export const test = base.extend({
  context: async ({ context, baseURL }, use) => {
    if (baseURL && requestUrl && requestToken) {
      const origin = new URL(baseURL).origin;
      await context.route(
        (url) => url.origin === origin,
        async (route) => {
          const token = await trustedSourceToken();
          await route.continue({
            headers: {
              ...route.request().headers(),
              ...(token ? { "x-vercel-trusted-oidc-idp-token": token } : {}),
            },
          });
        },
      );
    }
    await use(context);
  },
});

export { expect } from "@playwright/test";

Pull request tests

1. Choose the Smoke tests: a selection of the tests every pull request runs. Tests the pull request adds run too.
2. Under On a pull request, your tests run against, choose That pull request’s own build.

• Vercel tells GitHub where each preview is: ticked when Vercel recorded a GitHub deployment for the pull request’s commit. If Vercel built it without one, the row tells you to turn on deployment_status Events (step 1).
• Pull requests test their own Vercel preview: ticked when the pull request’s tests ran against a Vercel deployment. If not, the row tells you to add preview: vercel (step 2).

Troubleshooting

Known limits

• The fix assistant in Peeps can’t open a protected preview. It runs in Peeps, not in your CI, so your workflow’s trusted-source token doesn’t reach it, and Peeps sends your project’s HTTP headers only to your environments’ URLs. It can still read the run’s evidence; to look at the preview itself, open it in your browser.
• A fork’s pull request is not tested on its preview. preview: vercel refuses pull requests from forks and pull_request_target, because a fork’s preview runs the fork’s code.