Choose how to run Mo - Momentic

Documentation Index

Fetch the complete documentation index at: /docs/llms.txt

Use this file to discover all available pages before exploring further.

Every recipe below is the same shape: a target plus a brief, and a session that plans cases, executes them in parallel, and records verdicts and findings with evidence. What changes is where the brief comes from and which settings the run needs. The brief fields are in write a good brief; the commands are in use the Mo CLI.

Bug bash a P0 feature area

Test one product area before a release or a migration. Mo plans cases for the area and runs them in separate hosted browsers, up to the session’s concurrency limit.

  1. Pick one feature area and keep the brief narrow. Name the flows inside it, the account to use, and the areas to leave alone:
Target: https://staging.example.com
Area: order management (list, detail, refund, and export). Cover creating an order, applying a refund, filtering by status, and refreshing after each change.
Sign in with the staging QA account. Create test orders under the mo-runs customer only.
Out of bounds: billing settings, user management, and anything shared with other test accounts.
  1. Start the session:
qa start "$(cat brief.md)"

qa start prints the session JSON. Save sessionId for later commands, and open webUrl to watch. 3. Read the bugs as they land with qa status <session-id> --full, or export everything with qa report <session-id> once the session goes idle.

Review the case verdicts and coverage gaps before deciding whether the area has enough coverage. Findings include reproduction steps and available recording or screenshot metadata. See session reports.

Regression the last 24 hours of diffs

Select repositories on the Mo workspace page to give sessions read-only code context. Mo attempts to refresh their default branches at session start; a cached checkout may remain if the refresh fails. The session agent can read the code, inspect a diff window, and plan cases for the flows those commits touch. See workspace repositories.

  1. Connect GitHub in Settings > Integrations, then pick the repositories on Mo > Workspace.
  2. Give the brief a diff window instead of a feature list:
Target: https://staging.example.com
Look at the commits merged to the default branch in the last 24 hours in the checked-out repository. For each change, name the product flows it touches and verify those flows on staging. Focus on behavior a user can see; skip refactors and tests.
Sign in with the staging QA account. Do not modify shared workspace data.
  1. Start the session the same way:
qa start "$(cat brief.md)"

To inspect a release or feature branch, name it in the brief and ask Mo to fetch it and confirm the checked-out revision before reading the log. Confirm that the target deployment runs that revision too.Use a schedule to run the brief with a cron expression and time zone. Review each run’s report for findings, blocked cases, and coverage gaps.

Run Mo on a pull request

Install the Momentic GitHub App on the repository, then select the PR and its running preview with qa start --pr. Mo captures the PR revision, reads the changes, and tests the affected app behavior:

qa start "Verify cart totals and discount codes. Do not submit payment." \
  --pr acme/shop#412 --url https://preview.example.com

Provide sign-in instructions and expected behavior for the changed flows. Review the session report before merging. See use GitHub context for access and export the report for a local handoff.

Fix what it found, then recheck

qa report is built for the coding-agent loop: it exports the report as files your agent reads, so the fix and the recheck happen in one session of work.

  1. Export once the session is idle:
qa report <session-id> --require-idle --output mo-report

The directory holds report.json (a manifest into bugs.json, testCases.json, verdicts.json, and triage.json) plus available bug recordings. Static findings retain screenshot metadata in bugs.json; the export does not download those screenshots. Hand mo-report to your coding agent. 2. The agent reads each bug’s expected and actual behavior and its reproduction steps, fixes the defect in your checkout, and reruns the original reproduction locally. 3. Recheck through the same session. Name the bug and ask for the recheck with qa send:

qa send --session-id <session-id> "The fix for '<bug name>' is deployed on the same URL. Rerun the original reproduction and update the verdict."

Wait for Mo and its sub-agents to finish before exporting to a new directory:

qa wait <session-id> --json &&
     qa report <session-id> --require-idle --output mo-recheck

If qa wait exits 2, read and answer Mo’s question, then wait again before exporting. --require-idle checks the current state; it does not wait. Compare the new verdicts.json against the baseline and check whether the original reproduction passed.

The mo-qa skill encodes this whole loop, including the baseline export and the wait-for-idle rule. /mo-qa fix the bugs Mo found is the supported way to run it.

Test from an existing spec or test plan

Upload the document to the session, then point Mo at the sandbox path it prints. A local path means nothing inside the sandbox, so the upload is the handoff:

session_json=$(qa start "Test https://staging.example.com against the attached plan.") &&
  session_id=$(jq -er .sessionId <<<"$session_json") &&
  remote_path=$(qa upload --session-id "$session_id" ./release-plan.md release-plan.md) &&
  qa send --session-id "$session_id" "Derive the test cases from the plan at $remote_path."

Mo plans cases from the document. For a Confluence page, connect an MCP server that can read it, then include the page URL in your brief. You can also export the page and upload it to the session.

Test a preview deployment

Give Mo a preview URL it can access and the credentials for the flows you want tested:

qa start "Check the checkout flow on https://preview.example.com."

Provide the test account and sign-in instructions in the session chat. If the preview requires a firewall allowlist or a deployment bypass, configure access before the run. See give Mo access to your site.

Test a local branch

Start a tunnel for every address the flow needs, then start the session with the tunnel ID:

tunnel_json=$(qa tunnel start localhost:3000 api.internal:8080)
tunnel_id=$(jq -r .tunnelId <<<"$tunnel_json")
qa start "Test the checkout flow on http://localhost:3000. Sign in with the staging QA buyer." --tunnel "$tunnel_id"

Keep the exact local URL in the brief: Mo resolves it through the tunnel, not through the public internet. One tunnel holds every address it was started with, and qa tunnel stop <tunnel-id> revokes Mo’s access when the pass ends. See tunneling.

Test a mobile app

Mobile sessions require Mo mobile access in your workspace. Upload the build to a channel and a tag the same way a Momentic mobile test uses it, then select it in the composer. Give no URL: the brief describes the flows and the accounts instead. Mo installs the build on a remote simulator or emulator and runs the same agent structure as a web pass. See iOS app setup and Android emulators.

Repeat a pass on a schedule

Open Schedules in the Mo section of the app. A schedule holds a name, the prompt, a cron expression, and a time zone. Each occurrence starts a new session, and the schedule page lists the past runs and their reports. The nightly diff regression above and a weekly full-area pass are the two schedules worth starting with. Some ways of running Mo are not available yet. See not available yet.