Next.js on Vercel

​

Test against a local dev server

npm create next-app@latest my-app && cd my-app
npm run dev   # http://localhost:3000

npx @momentic/wizard@latest   # or: npm i -D momentic && npx momentic init

fileType: momentic/test/v2
id: home-renders
url: http://localhost:3000
labels: [smoke]
steps:
  - assert: The page finishes loading and shows the main heading

npx momentic run home.test.yaml

​

Test a preview deployment

npx momentic run --url-override https://my-app-git-feat.vercel.app --labels smoke

​

Bypass deployment protection

• Send x-vercel-protection-bypass + x-vercel-set-bypass-cookie headers on every request (fast; can hit CORS limits).
• Append ?x-vercel-protection-bypass=<secret>&x-vercel-set-bypass-cookie=true to the base URL (works through CORS; Vercel converts it to a cookie).

​

In CI

name: Test Vercel preview
on: pull_request

jobs:
  test:
    if: github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    permissions:
      contents: read
      deployments: read
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22.12.0
      - run: npm install

      - name: Wait for Vercel preview
        uses: patrickedqvist/wait-for-vercel-preview@v1.3.2
        id: vercel
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          max_timeout: 600

      - name: Install browsers
        run: npx momentic install-browsers chromium

      - name: Run Momentic
        run: |
          npx momentic run --labels smoke -y \
            --url-override "${{ steps.vercel.outputs.url }}" \
            --custom-headers x-vercel-protection-bypass=${{ secrets.VERCEL_AUTOMATION_BYPASS_SECRET }} \
                           x-vercel-set-bypass-cookie=true
        env:
          MOMENTIC_API_KEY: ${{ secrets.MOMENTIC_API_KEY }}

​

Next.js pitfalls

• Hydration timing. next dev and React transitions can leave elements visible-but-inert briefly. Assert on the post-hydration state (“the Sign in button is clickable”) rather than adding fixed waits.
• next/image and visual assertions. Placeholder blur and lazy images make pixel-level checks racy; keep visual assertions on stable regions.
• Vercel’s deployment-protection bypass does not sign in to your app. Include the app’s login or session setup even when the deployment accepts the bypass header or query parameters.
• Preview vs production data. Point NEXT_PUBLIC_* env vars at staging backends for previews so tests exercise realistic data without touching production.
• VERCEL_AUTOMATION_BYPASS_SECRET in forks. GitHub does not pass secrets to workflows from forks; gate the test job with if: on same-repo PRs. Do not switch to pull_request_target: it runs with your repo’s secrets while checking out fork-controlled code, which exposes those secrets.

​

Related

• Test Vercel protected preview environments
• Run in CI
• Environments