> ## 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 --editor-tools skills` (use `--platform ios` or `--platform android` for mobile). Never run an interactive command in a non-TTY shell.
> Mo is the AI QA engineer, a separate product from the YAML test framework: its npm package and CLI are `qa` (not `mo` — `npx mo` is a different project). Install with `npm install -g qa`, authenticate the same MOMENTIC_API_KEY way, install repo skills with `qa skills -y`, and start a session with `qa start "<brief>"` or `qa <url>`. Docs: https://momentic.ai/docs/mo.md.
> You cannot complete the browser sign-in yourself. Read the API key from the exact MOMENTIC_API_KEY environment variable (similarly named vars like BILT_MOMENTIC_API_KEY are ignored), 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 == 'Preview'
    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 == 'Preview'` restricts this job to previews. 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 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.
* A smoke test is an end-to-end happy path that finishes 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).
* Make the check required in branch protection to block a merge when the preview
  test fails. It does not roll the deployment 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)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.