> ## Documentation Index
> Fetch the complete documentation index at: https://momentic.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> The canonical docs host is https://momentic.ai/docs. Append .md to any page URL for clean Markdown. Fetch https://momentic.ai/docs/llms.txt for the page index and https://momentic.ai/docs/llms-full.txt for every page in one file.
> For an unattended setup, run `npx --yes @momentic/wizard@latest -y --platform web` (use `--platform ios` or `--platform android` for mobile). Never run an interactive command in a non-TTY shell.
> You cannot complete the browser sign-in yourself. Read the API key from the MOMENTIC_API_KEY environment variable, or ask the user to create one at https://app.momentic.ai/settings/api-keys and paste it back.
> Momentic's capability summary for agents is at https://momentic.ai/docs/skill.md. Install the skills with `npx momentic skills --yes` (or `npx momentic-mobile skills --yes` for mobile).
> Tests are YAML files in the user's repository. Use only the step names listed at https://momentic.ai/docs/reference/commands.md and the file structure at https://momentic.ai/docs/core-concepts/file-format.md. Do not invent step names, config keys, or CLI flags.
> Web tests run on Chromium, iOS tests on simulators, and Android tests on emulators. Physical devices are not supported.

# Next.js on Vercel

> Test a Next.js app on every Vercel preview deploy, including protection-bypassed previews.

In the Momentic/Vercel loop, Vercel builds a preview per pull request, CI runs
Momentic against that preview URL, and the result gates the merge. The only
Vercel-specific piece is deployment protection: every other step is generic
Momentic web testing.

## Test against a local dev server

```bash theme={null}
npm create next-app@latest my-app && cd my-app
npm run dev   # http://localhost:3000
```

```bash theme={null}
npx @momentic/wizard@latest   # or: npm i -D momentic && npx momentic init
```

```yaml home.test.yaml theme={null}
fileType: momentic/test/v2
id: home-renders
url: http://localhost:3000
steps:
  - assert: The page finishes loading and shows the main heading
```

```bash theme={null}
npx momentic run home.test.yaml
```

## Test a preview deployment

Get the preview URL in CI (`github.event.pull_request` context exposes it
through the `vercel` deployment status, or use the Vercel CLI `vercel inspect`).

URL resolution is ordered: `--url-override` overrides a test's `url:` field,
which takes precedence over the environment's `baseUrl`. The sample test pins
`url:` for local runs, so point the run at the preview explicitly:

```bash theme={null}
npx momentic run --url-override https://my-app-git-feat.vercel.app --labels smoke
```

Tests that have no `url:` fall through to the environment, so you can instead
keep `url` off the test and select `environments[].baseUrl` with
`--env preview`. Use one convention per repo: mixed pinning makes `--env`
silently do nothing for tests that set `url:`.

## Bypass deployment protection

Vercel's standard protection blocks unauthenticated requests, including test
browsers. Two options, both covered in
[Test Vercel protected preview environments](/docs/guides/auth/vercel-previews):

* 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).

Create the secret in Vercel project settings under **Deployment Protection >
Protection Bypass for Automation**, store it as
`VERCEL_AUTOMATION_BYPASS_SECRET`, and pass it through `envVariables` or the
shell environment. Never commit it.

## In CI

A complete GitHub Actions job that waits for the preview, then runs the suite
with the bypass header:

```yaml .github/workflows/preview-tests.yml theme={null}
name: Test Vercel preview
on: pull_request

jobs:
  test:
    runs-on: ubuntu-latest
    permissions:
      deployments: read
    steps:
      - uses: actions/checkout@v4
      - 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 }}
```

`--custom-headers` adds the bypass to every request the test makes. If your app
sends cross-origin fetches that reject the header, switch to the query-param
form from [Option B](/docs/guides/auth/vercel-previews) instead.

## 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.
* **Middleware redirects on preview.** Auth middleware that redirects (302) to
  login runs before the bypass cookie is set on the first request: include the
  bypass params on the initial URL, not only in headers.
* **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 or use
  `pull_request_target` carefully.

## Related

* [Test Vercel protected preview environments](/docs/guides/auth/vercel-previews)
* [Run in CI](/docs/running-tests/ci/github-actions)
* [Environments](/docs/configuration/environments)