> ## 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, first check whether Claude Code already has the Momentic plugin. With the plugin, run `npx --yes @momentic/wizard@latest -y --platform web --editor-tools none` and ignore any CLI skills-install suggestion in its output. Otherwise, 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, separate from repository YAML tests. With the Momentic plugin, use bundled mo-qa and hosted OAuth by default. Without the plugin, install only mo-qa with `npx -y qa skills --target <agent>`. Keep the requested interface. Otherwise, use hosted tools for web or mobile, including private web targets with an existing Connector. Run sessions that need a new tunnel with the qa CLI. If you can't run commands on the machine that reaches the target, ask the user to start the tunnel there, then use hosted tools unless you lack them or the CLI was requested. For a requested hosted session, use an online Connector and pass its name as access, not a CLI tunnel ID. If none is online, ask the user to run `npx -y qa tunnel start --name <name> <address>` on a machine that reaches the target and wait. Do not run login or tunnel commands for them. For a requested hosted session, report unavailable tools or authentication failures without starting a CLI session. For coding-agent bridge setup, ask the user to complete `npx -y qa login`, then add momentic-hosted as a stdio server running `npx -y qa mcp`. Plugin users must explicitly opt in and disable their hosted plugin entry before adding the bridge. Claude.ai/ChatGPT connectors keep https://mcp.momentic.ai with OAuth. After hosted testing completes, read the report and summarize findings and uncovered requirements. Call `momentic_mo_stop_session` only when the user asks or agrees. For CLI sessions, unless the user wants more testing, export the report, run `qa stop <id> --subagents` even if export fails, then summarize. The CLI is qa, not mo. Docs: https://momentic.ai/docs/mo/quickstart.md.
> Ask the user to complete browser sign-in. For local CLI tools, use the exact MOMENTIC_API_KEY environment variable. If it is absent, ask the user to create a key at https://app.momentic.ai/settings/api-keys and set it in the agent's environment. Never print the key or ask the user to paste it into chat.
> Momentic's capability summary for agents is at https://momentic.ai/docs/skill.md. Claude Code users with the Momentic plugin should use its bundled skills and skip CLI skills installation. Otherwise, run `npx momentic skills -y --target <agent>` or `npx momentic-mobile skills -y --target <agent>`. Both install momentic-test, momentic-maintain, and momentic-spec with web/mobile references. Use the running agent's target. The Momentic plugin also includes mo-qa; qa skills installs only mo-qa.
> 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.

# Page interactions

> Upload and download files, pick dropdown options, and record network requests in a web test.

Use these recipes to upload and download files, select dropdown options, and
capture network requests in web tests.

## Upload files

Upload a file in a web test with the **File upload** step, from a remote URL, a
previously downloaded file, or a local path.

> [!WARNING]
>
> The **File upload** step must come before the step that opens the native file
> picker.

### Setup

1. Add a **File upload** step with a source:
   * **Remote URL**: `http://...` or `https://...` (publicly accessible)
   * **Previously downloaded file**: `file://<download-key>` from an earlier
     [download step](#download-files)
   * **Local file**: absolute path accessible to the local CLI process
2. (Optional) Set a **Filename** to rename the uploaded file.
3. Add a **Click** step on the button that opens the file picker.

### Limits

* One file per step.
* Files fetched from remote URLs are limited to 50MiB.

### Related

* [Download files](#download-files)
* [Files integration](https://momentic.ai/docs/integrations/files.md)

## Download files

Capture a file your app downloads when a step clicks a button or link, and
optionally save its URL to reuse later in the test (for example, to feed into an
upload step).

### Setup

1. Add a Click step on the button/link that triggers the download.
2. Enable **Wait for download** on that step.
3. (Optional) Set **Save to environment variable** to capture the file URL (e.g.
   `DOWNLOADED_FILE`). The saved object contains `downloadedFile`, a complete
   `file://` URI. Pass `{{ env.DOWNLOADED_FILE.downloadedFile }}` to a later
   [upload step](#upload-files).

### Limits

* One file per **Click** step.
* Download timeout: 30 seconds by default. Set
  [`click.downloadTimeout`](https://momentic.ai/docs/reference/commands/click) in milliseconds to change
  it.
* Downloaded files are temporary and are deleted five minutes after capture.
* Direct file manipulation (reading contents, checking format) is not supported.

### Related

* [Upload files](#upload-files)

## Select options from a dropdown

Pick an option from a dropdown during a test. The approach depends on whether
the element is a native `<select>` or a custom menu.

> [!TIP]
>
> Inspect the element first to confirm whether it's a native `<select>` or a
> custom menu (e.g. Headless UI, Radix, shadcn). The approach differs.

### Native `<select>`

1. Add a **Select** step and describe the element (e.g. "The country select").
2. Click **Find using description** to populate the options list.
3. Choose an option by **label**, **value**, or **index**.

### Custom dropdowns

For React/Vue component libraries (Headless UI, Radix, Material UI, shadcn,
etc.), use two **Click** steps:

1. **Click** on the dropdown trigger (e.g. "The country dropdown").
2. **Click** on the desired option (e.g. "USA inside the country dropdown").

### Related

* [Finding elements](https://momentic.ai/docs/core-concepts/finding-elements.md)

## Record and validate network requests

Use network steps to verify your UI sends the right data to the backend, or that
the backend returns what you expect.

### Wait for a single request

1. Add a **Register request listener** step: provide a URL regex and a key (e.g.
   `CHECKOUT_REQUEST`).
2. Trigger the request (submit a form, click a button, etc.).
3. Add an **Await listener** step with the same key. Save the result to an
   environment variable (e.g. `RESPONSE`). The step fails if no matching request
   completes within the timeout.
4. Add a **JavaScript** step to validate:

   ```js theme={null}
   assert(env.RESPONSE.response.status === 200);
   assert(env.RESPONSE.response.json?.orderId);
   ```

### Record multiple requests

1. Add a **Record requests** step: provide a URL regex and a key (e.g.
   `ANALYTICS_EVENTS`).
2. Trigger the requests (navigate, click, fill forms, etc.).
3. Add a **Get recorded requests** step with the same key. Save the array to an
   environment variable (e.g. `REQUESTS`).
4. Validate in a **JavaScript** step:

   ```js theme={null}
   assert(env.REQUESTS.length === 3);
   assert(env.REQUESTS.every((r) => r.response?.status === 200));
   ```

> [!NOTE]
>
> Requests that didn't complete before **Get recorded requests** ran are still
> included in the array, without a `response` field.

### Related

* [Writing assertions](https://momentic.ai/docs/core-concepts/writing-assertions.md)
* [Request mocking](https://momentic.ai/docs/platforms/web/request-mocking.md)


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