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

# CircleCI

> Run Momentic tests from CircleCI, with sharding and secrets.

This page shows an example config for running Momentic on
[CircleCI](https://circleci.com/). More reference configs live in
[momentic-ai/examples](https://github.com/momentic-ai/examples).

Given this root `package.json`:

```json package.json theme={null}
{
  "name": "my-momentic-repo",
  "scripts": {},
  "devDependencies": {
    "momentic": "latest"
  }
}
```

Create a file called `.circleci/config.yml` in your repository with the
following contents:

```yaml config.yml theme={null}
version: 2.1
orbs:
  node: circleci/node@5.0.2
workflows:
  test:
    jobs:
      - test
jobs:
  test:
    docker:
      - image: cimg/node:22.12
    steps:
      - checkout
      - node/install-packages

      - run:
          name: Install browsers
          command: npx momentic install-browsers --all

      - run:
          name: Run Momentic tests
          command: npx momentic run
          when: always

      - run:
          name: Upload results
          command: npx momentic results upload test-results
          when: always
```

## Authentication

To run any commands, you must authenticate with Momentic. Set the
`MOMENTIC_API_KEY` environment variable in your CircleCI project settings.

1. Create an API key in the
   [Momentic dashboard](https://app.momentic.ai/settings/api-keys).

<Frame>
  <img src="https://mintcdn.com/momentic-docs/N47HcAM-4dLVFPuL/images/create-api-key.png?fit=max&auto=format&n=N47HcAM-4dLVFPuL&q=85&s=54eb9f3c01e00a3ae7d71996760dcd39" alt="Create an API key in Momentic settings" width="3616" height="2434" data-path="images/create-api-key.png" />
</Frame>

Copy the value. You add it as a CI secret in the next step.

2. Go to your CircleCI project settings and click the **Environment Variables**
   tab. Create a new secret called `MOMENTIC_API_KEY` and enter your API key.

<Frame>
  <img src="https://mintcdn.com/momentic-docs/N47HcAM-4dLVFPuL/images/ci/cci-env-var-page.png?fit=max&auto=format&n=N47HcAM-4dLVFPuL&q=85&s=3e83e686070e40d2c8cdd65887f9d5c6" alt="CircleCI project settings showing the Environment Variables tab" width="3636" height="2532" data-path="images/ci/cci-env-var-page.png" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/momentic-docs/N47HcAM-4dLVFPuL/images/ci/cci-add-env-var.png?fit=max&auto=format&n=N47HcAM-4dLVFPuL&q=85&s=07f8fd6de33c0e5468ad36b02f72cbb0" alt="CircleCI Add Environment Variable dialog" width="3636" height="2532" data-path="images/ci/cci-add-env-var.png" />
</Frame>

3. CircleCI automatically loads environment variables stored in project settings
   into the CI environment. The CI file needs no changes.

## Sharding

If you have a large test set, use sharding to run tests in parallel across CI
jobs and shorten total run time.

To shard your tests, pass the `--shard-index` and `--shard-count` options to the
`momentic run` command. The `--shard-index` is the index of the current shard
(starting from 1), and `--shard-count` is the total number of shards.

To collect test results inside a single run group in the Momentic dashboard, add
a separate step after all tests complete to merge and upload results.

```yaml config.yml theme={null}
version: 2.1
orbs:
  node: circleci/node@5.0.2

jobs:
  run-tests:
    parallelism: 2
    docker:
      - image: cimg/node:22.12
    steps:
      - checkout
      - node/install-packages

      - run:
          name: Install browsers
          command: npx momentic install-browsers --all

      - run:
          name: Run tests
          command: |
            mkdir -p test-results/shard-${CIRCLE_NODE_INDEX}
            set +e
            npx momentic run \
              --output-dir test-results/shard-${CIRCLE_NODE_INDEX} \
              --shard-index $(($CIRCLE_NODE_INDEX+1)) \
              --shard-count ${CIRCLE_NODE_TOTAL}
            test_status=$?
            echo "$test_status" > test-results/shard-${CIRCLE_NODE_INDEX}/exit-code

      - store_artifacts:
          path: ./test-results

      - persist_to_workspace:
          root: .
          paths:
            - test-results

      - run:
          name: Restore test exit code
          command: exit "$(cat test-results/shard-${CIRCLE_NODE_INDEX}/exit-code)"

  upload-results:
    docker:
      - image: cimg/node:22.12
    steps:
      - checkout
      - node/install-packages

      - attach_workspace:
          at: .

      - run:
          name: Merge test results
          command: npx momentic results merge --output-dir test-results/merged test-results

      - run:
          name: Upload test results
          command: npx momentic results upload test-results/merged

workflows:
  test:
    jobs:
      - run-tests
      - upload-results:
          requires:
            - run-tests:
              - success
              - failed
```


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