> ## 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.

# Smoke test preview deploys

> Run a smoke suite against every preview deployment as soon as it is ready.

Preview deploys exist so you can exercise a change before merge. This recipe
waits for the provider's deployment status, overrides the tests' base URL at the
preview, and reports back as a PR check.

## The tests

```yaml tests/smoke/signup.test.yaml theme={null}
fileType: momentic/test/v2
id: signup-smoke
labels: [smoke]
steps:
  - navigate: /signup
  - act:
      goal: Complete the new-user signup flow using a fresh email
      postcondition: The welcome screen is visible
```

Smoke tests have no hardcoded `url`: `--url-override` points them at whichever
deployment fired the event.

## The workflow

The job installs `momentic` from `devDependencies`, so your lockfile pins the
CLI version. Add it once with `npm install -D momentic`.

```yaml .github/workflows/preview-smoke.yml theme={null}
name: Preview smoke

on:
  deployment_status:

jobs:
  test:
    if: >-
      github.event.deployment_status.state == 'success' &&
      github.event.deployment.environment != 'Production'
    runs-on: ubuntu-latest
    timeout-minutes: 15
    env:
      MOMENTIC_API_KEY: ${{ secrets.MOMENTIC_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22.12.0
      - run: npm install
      - run: npx momentic install-browsers chromium

      - name: Smoke test the preview
        run: |
          npx momentic run --labels smoke -y --upload-results \
            --url-override "${{ github.event.deployment_status.environment_url }}" \
            --custom-headers \
              "x-vercel-protection-bypass=${{ secrets.VERCEL_AUTOMATION_BYPASS_SECRET }}" \
              "x-vercel-set-bypass-cookie=true"
```

* `deployment_status` fires for Vercel and any provider that posts a GitHub
  deployment. `environment_url` is the preview URL. For providers that do not
  post deployments, poll for the URL first: see the
  [Next.js on Vercel](/docs/guides/frameworks/nextjs-vercel) guide for the
  wait-for-preview variant.
* `deployment.environment != 'Production'` keeps staging and production
  deployments from re-running the preview suite. Match the environment names
  your provider posts (Vercel uses `Preview` and `Production`).
* `--url-override` replaces each test's `url` and each environment's `baseUrl`.
* Drop the `--custom-headers` pair when the preview is public. For
  protection-bypass details, see
  [Vercel preview auth](/docs/guides/auth/vercel-previews).

## Decisions

* **Labels vs selection.** `--labels smoke` is a fixed list; `--ai-select` picks
  tests from the diff. Use the label for a fast universal gate, selection when
  the suite is large, or both.
* **What belongs in smoke.** A handful of end-to-end happy paths that finish in
  minutes. If the preview job takes longer than a reviewer waits, it is doing
  regression work. Move those tests to the
  [nightly suite](/docs/guides/use-cases/run-a-nightly-regression-suite).
* **Failure is not rollback.** A preview failure blocks a merge; it does not
  roll anything back. For post-deploy rollback gating, see the deploy-gate
  workflow in [Common CI setups](/docs/guides/common-setups).

## Related

* [Common CI setups](/docs/guides/common-setups)
* [Next.js on Vercel](/docs/guides/frameworks/nextjs-vercel)
* [Vercel preview auth](/docs/guides/auth/vercel-previews)
* [Gate pull requests on critical flows](/docs/guides/use-cases/gate-pull-requests-on-critical-flows)