Host

Android Emulator

iOS Simulator

macOS

Supported

Supported (Xcode with a Simulator runtime)

Linux

Supported

Not available

Windows

Experimental and untested; some process-cleanup helpers rely on ps

Not available

Your app

What Swipium needs

React Native / Expo, debug build

Metro serving this project's JS bundle. qa_metro can start it (consent-gated); otherwise the run stops with METRO_REQUIRED, on Android and for iOS simulator builds without an embedded bundle alike. A Metro on port 8081 serving another project is METRO_WRONG_PROJECT. Expo dev-client builds must be connected to Metro by hand for now; when this project's Metro is already serving, the blocker gives the dev-client deep link to open.

React Native / Expo release, or native Android / iOS

An installable artifact (APK or .aab for Android, a simulator .app for iOS; a device .ipa is refused) or a project Swipium can build.

Expo managed (no android/ or ios/)

Nothing extra: the build (npx expo run:android --device <AVD> or npx expo run:ios, consent-gated) generates the native project first. If that prebuild step fails, the build fails with EXPO_PREBUILD_REQUIRED; run npx expo prebuild yourself and retry.

Only a built app, no source

Put the simulator .app or the .apk in a directory and pass that directory as projectRoot (Testing a prebuilt build).

Flutter

A buildable Flutter project, or a built APK / .app.

Goal

Prompt

Smoke test

"Use Swipium to smoke test this app: qa_test_this with goal smoke and waitForCompletion, then summarize the report."

Test login

"Use Swipium to test login with goal test_login. Don't ask me for the password: type ${SWIPIUM_TEST_EMAIL} and ${SWIPIUM_TEST_PASSWORD} with qa_act." (set both in the server env; placeholders expand server-side and secret values are redacted)

Reproduce a bug

"Use Swipium to reproduce this bug with goal reproduce_bug and goalText: 'checkout button does nothing after adding a coupon'. Attach the evidence."

Save a flow

"Turn the last Swipium run into a flow named login-smoke with qa_generate and save it."

Release gate

"Run Swipium with goal release_gate and tell me whether the release gate passes."

Group

Tools

Start

qa_test_this, qa_status, qa_job_status, qa_job_cancel, qa_explain_blocker, qa_continue_from_blocker, qa_get_artifact

Setup

qa_doctor, qa_start_session, qa_prepare_target, qa_prepare_ios_target, qa_ios, qa_wda

Build

qa_resolve_target, qa_resolve_artifact, qa_build, qa_bundletool

Device

qa_device_info, qa_orientation, qa_geolocation, qa_network, qa_metro, qa_app_control, qa_screen_record

Drive

qa_snapshot, qa_inspect, qa_act, qa_clear_overlay, qa_check_health, qa_screenshot, qa_note, qa_visual, qa_wait

Run

qa_smoke, qa_explore, qa_report

App map

qa_app_map_build, qa_app_map_read, qa_app_map_query, qa_app_map_feature_scope, qa_app_map_update

Feature

qa_test_feature

Flows

qa_flow_check, qa_flow_run, qa_flow_compile, qa_flow_repair

Generate

qa_generate

Test suite

qa_suite_read, qa_suite_update, qa_suite_generate, qa_suite_export, qa_suite_lint

Issues

qa_issue_log, qa_mobile_audit

First run

qa_first_run

Variable

Purpose

SWIPIUM_PROJECT_ROOT

Absolute path of the app repository when the client provides no MCP roots.

CLAUDE_PROJECT_DIR

Set by Claude Code; used as the project root after SWIPIUM_PROJECT_ROOT.

ANDROID_HOME, ANDROID_SDK_ROOT

Android SDK location, searched for adb, emulator, and aapt2 (see Requirements).

BUNDLETOOL_JAR

Path to bundletool.jar for converting .aab files. A bundletool launcher on PATH also works.

DEVELOPMENT_TEAM, XCODE_DEVELOPMENT_TEAM

Apple team ID for signing WDA (ios.wda.developmentTeam in .swipium/config.json takes precedence).

APPIUM_HOME

Extra location searched for an Appium-installed WDA (besides ~/.appium and global npm).

WDA_PROJECT_PATH, WEBDRIVERAGENT_PROJECT

Extra WebDriverAgent.xcodeproj candidates reported by qa_doctor and qa_wda status (to build one, pass wdaProjectPath).

SWIPIUM_ALLOW_REMOTE_WDA

Comma-separated exact non-loopback WDA base URLs you pre-approve. Set it in your client config, never in the repository.

SWIPIUM_TEST_*

Test-account values: _EMAIL, _USERNAME, _PASSWORD, _OTP, _TOKEN, _PIN (and _DEEP_LINK for the starter flows). Flows and qa_act use ${SWIPIUM_TEST_EMAIL}; fixtures.json uses "var": "SWIPIUM_TEST_EMAIL". Child processes Swipium starts (builds, Metro, xcodebuild, adb, OCR and mask commands) don't inherit them; fixture seed scripts do.

Other SWIPIUM_*

Flows and fixtures read only SWIPIUM_* names from the environment (never ${HOME} or ${AWS_SECRET_ACCESS_KEY}). Names with a credential part (password, secret, token, otp, pin, cvv, key, code and similar, matched per name part, so SWIPIUM_SHIPPING_ADDRESS is not one; rule) are secrets and redacted. Child processes other than seed scripts don't inherit SWIPIUM_SECRET_* or any of these secret names.

SWIPIUM_OCR_CMD

OCR command for qa_visual find_text (none bundled; consent-gated). {image} becomes a PNG path; it prints [{"text","confidence","bbox"}] JSON. ocrCommand in config.json wins.

SWIPIUM_VISUAL_MASK_CMD

Masks screenshots before OCR and visual providers see them (visualMaskCommand in config wins).

SWIPIUM_REQUIRE_ELICITATION=1

Refuse every consent-gated action (CONSENT_REFUSED) when the client can't show a real consent prompt. Operator pre-approval still applies.

SWIPIUM_CONSENT_PREAPPROVE

Comma-separated exact consent action names approved without a prompt (for example prepare_plan,test_this_plan), for headless clients such as codex exec or claude -p that answer prompts automatically. No wildcards; unknown names are ignored with a warning. Actions that run code also need SWIPIUM_CONSENT_PREAPPROVE_RUN_CODE=1, and wda_non_loopback is never accepted (use SWIPIUM_ALLOW_REMOTE_WDA). Read only from the server process env, never the repository. Each approval is still single-use and is logged at warn with the exact command. See Operator pre-approval.

SWIPIUM_CONSENT_PREAPPROVE_RUN_CODE

1 lets SWIPIUM_CONSENT_PREAPPROVE cover actions that run repository- or model-chosen code (build_from_source, flow_mutation_run, ocr_run, start_metro, suite_fresh_state_replay, wda_build, wda_start, and a test_this_plan that includes a build). Under codex exec that code runs outside the client's sandbox. Trusted repositories only.

SWIPIUM_RETENTION_DAYS

Age limit in days for ~/.swipium/runs session directories (default 30). 0 or off disables the automatic prune; swipium gc still works.

SWIPIUM_RETENTION_KEEP

Number of newest sessions per project kept regardless of age (default 20), while the project's root still exists. Sessions of deleted roots, such as temporary directories, age out by SWIPIUM_RETENTION_DAYS alone.

SWIPIUM_MAX_WAIT_MS

How long one qa_job_status long-poll, qa_wait, or qa_test_this {waitForCompletion:true} may block, in ms (default 50000, clamped to 1000 to 230000). Set it just under your client's tool timeout; swipium init claude writes 110000. See Server settings.

SWIPIUM_TOOLS

core lists only the core tools (the swipium init codex set); all (default) lists every tool. Tool counts then count the listed tools.

SWIPIUM_DEVICE

Pins the server to one device: an adb serial, AVD name, or simulator UDID or exact name (case-insensitive in every tool; a simulator name several simulators share is refused with MULTIPLE_DEVICES, so pin by UDID). Runs and auto-binding use only that device, a call naming another device (low-level qa_ios, qa_wda and qa_bundletool actions included) is refused with DEVICE_PINNED, and SWIPIUM_CONSENT_PREAPPROVE therefore only applies to it. Set it on shared CI runners. Read only from the server env (Device pin).

SWIPIUM_ANDROID_DUMPER

agent turns on the opt-in persistent Android UI dumper (about 2x to 7x faster snapshots, depending on host load; pushes a small jar to the emulator; blocks other UiAutomation clients while it runs). See android-agent/README.md.

SWIPIUM_EMULATOR_GPU

-gpu mode for emulators Swipium boots (default auto). Use swiftshader_indirect on hosts without a usable GPU.

SWIPIUM_EMULATOR_COLD_BOOT

1 boots emulators cold (-no-snapshot-load) instead of quick-booting from the AVD snapshot.

SWIPIUM_LOG_LEVEL

Minimum stderr log level: debug, info (default), warn, or error. debug adds one line per tool call (tool, session, duration, error code; never argument values).

JAVA_HOME

JDK used by Gradle builds; qa_doctor flags a missing JDK under Codex.

CODEX_HOME

Where swipium init codex finds config.toml (default ~/.codex).

CLAUDE_CONFIG_DIR

Where swipium init claude --scope user installs the skill (<dir>/skills/, default ~/.claude).

CI

When set, reports label the run environment as CI.

GITHUB_SHA, GITHUB_REF_NAME, GITHUB_SERVER_URL, GITHUB_REPOSITORY, GITHUB_RUN_ID, CI_COMMIT_SHA, CI_COMMIT_REF_NAME, CI_PIPELINE_URL, BITBUCKET_COMMIT, BITBUCKET_BRANCH

Source revision (commit, branch, run URL) recorded in reports and the issue ledger.

SWIPIUM_DISABLE_DEVICE_DISCOVERY

Test-suite isolation only: disables device auto-discovery. Not for normal use.

Command

What it does

swipium (alias swipium serve)

Start the stdio MCP server. Unrecognized flags alone (such as --stdio) are ignored with a warning; an unknown subcommand prints usage and exits 2, and so do flags placed before a subcommand (swipium -y init claude prints the corrected command).

swipium init <client> [--apply] [--scope local|user|project] [--cwd <dir>] [--no-skill] [--trust-local]

Preview (default) or apply the registration for claude, codex, gemini, cursor, or vscode. claude and codex also install the swipium-qa skill (--no-skill skips it); --trust-local (claude, local or user scope) pre-approves the consent actions that run no code. --flag value and --flag=value both work. Exits 2 on an unknown or incomplete option, a missing --cwd, or a config file it won't edit, and 1 when the apply fails or claude already has a different registration (it prints the remove and add commands). See docs/mcp-server.md.

swipium init flows [--root <dir>] [--force]

Write starter flow templates into .swipium/flows/ (existing files kept unless --force). A --root that doesn't exist exits 2, and so do the registration flags (--scope, --apply, --cwd, --no-skill, --trust-local).

swipium verify

Start the server over stdio, check that every tool is listed, and run qa_doctor, listing every failed check. Exits 1 when the server or a tool is missing, qa_doctor errors, or Node.js is too old; --help prints usage.

swipium scan [path] [--check | --dry-run | --no-write]

Print a readiness report: READY, PARTIAL (for example no installable build yet, but qa_test_this will build one from source), or BLOCKED. Creates .swipium/ and merges its results into .swipium/config.json (your keys are kept) unless the result is BLOCKED or a no-write flag is set. Exits 0 on READY or PARTIAL, 1 on BLOCKED, 2 on a bad path or option.

swipium suite <lint|compile|init> [projectRoot] [--suite <file>] [--strict] [--force]

lint flags brittle page-object locators, unresolved references, and coordinate-only steps (exits 0 clean or with warnings only, 1 on errors or, with --strict, any finding, 2 with no .swipium/pages). compile turns a POM suite into flows under .swipium/flows/, keeping a flow you edited by hand (new output in <slug>.yaml.new; --force overwrites; writing a flow removes a leftover .yaml.new); it exits 0 when every test compiled, else 2. init explains suites. Step numbers in messages start at 1. An option the subcommand doesn't take (lint takes --strict, compile takes --suite and --force, init none), including a typo such as --stirct, prints usage and exits 2, as do an unknown subcommand (with a "did you mean" hint for a one-letter typo) and --suite without a value. --help prints usage and exits 0. The file layout is in docs/flows.md.

swipium report --format html|junit|sarif|github-summary|markdown|json

Render a saved report (--latest default, --session, --report, --root, --out, --max-age <minutes>, --fail-on-gate). Exits 1 when the gate blocks with --fail-on-gate, 2 on usage error (--fail-on-gate=false included), no report, a report older than --max-age, newer sessions without a report under --latest --fail-on-gate (without --max-age), a failed --out write, or an invalid .swipium/policy.json.

swipium gc [--dry-run] [--days N] [--keep N]

Delete old ~/.swipium/runs session directories and stale ~/.swipium/projects.json entries. The newest --keep sessions are kept only for projects whose root still exists. --days and --keep take a non-negative integer; an empty (--days=) or non-integer value exits 2 and deletes nothing. Exits 1 when some entries could not be processed.

swipium --help / -h, --version / -v

Print usage or the version.

failureCode

Meaning

What to do

PROJECT_ROOT_UNRESOLVED

Swipium can't tell which app to test.

Name the absolute path in the prompt or set SWIPIUM_PROJECT_ROOT (project root).

STALE_CLIENT

The client runs a pre-upgrade server or uses a removed tool.

Restart the MCP client.

ADB_NOT_FOUND

Android platform-tools can't be found.

Install them via Android Studio; set ANDROID_HOME in the server env for GUI clients or non-default locations.

NO_DEVICE

No emulator is online and none can be booted, the requested device doesn't exist, or the bound device went away.

Create an AVD or iOS Simulator; qa_test_this boots it for you.

DEVICE_PINNED

The call names a device other than the one SWIPIUM_DEVICE pins.

Omit device, or change SWIPIUM_DEVICE in the server env.

PHYSICAL_DEVICE_UNSUPPORTED

Only a real phone is available.

Start an emulator, or unplug the phone.

METRO_REQUIRED

A debug RN/Expo build needs Metro serving.

Start Metro (qa_metro {action:"start"} or npx react-native start / npx expo start), then retry. If Metro is already serving and an Expo dev client just isn't connected, open the deep link the blocker gives (or tap the server in the dev client).

METRO_WRONG_PROJECT

The Metro on port 8081 serves another project.

Stop the other project's Metro, start this project's, then retry.

EXPO_PREBUILD_REQUIRED

Generating the Expo native project failed during the build.

Run npx expo prebuild to see the error, fix it, then retry.

WDA_UNREACHABLE

WebDriverAgent isn't running or answering (or hung after the launch).

qa_wda {action:"status"}, then start or attach. A hung WDA: qa_wda {action:"stop"}, then setup and attach. For a plain smoke check, use goal:"smoke", which works visual-only.

DEVICE_UNRESPONSIVE

The Android emulator didn't answer adb in time (stalled or overloaded); an input may have partly landed.

qa_screenshot to see the screen, then restart the app or the emulator and retry.

BACKEND_UNSUPPORTED

The action needs WDA (iOS visual-only mode).

Attach WDA with qa_wda, or use qa_visual and qa_screenshot.

CONSENT_DECLINED / CONSENT_CANCELLED / CONSENT_REFUSED

Nothing ran: you declined, the prompt was dismissed, timed out or failed (elicitationFailure says why), or SWIPIUM_REQUIRE_ELICITATION=1 blocked it.

Re-call for a fresh prompt if you want the action. likelyAutomatic: true means a headless client answered in under 1.5 s: don't loop, pre-approve the named action with SWIPIUM_CONSENT_PREAPPROVE (Headless runs).

NOT_TESTED

The run never reached or exercised the app (a launch plus an agent's pass note is not a test), so its report fails the release gate.

Fix the blocker the report names, or run qa_smoke or a flow, then re-run.

BLANK_SCREEN

The app showed no UI after launch (about 15 s, up to 30 s while Metro is serving), or was still on its splash or loading screen at the end of the wait, so the launch is not verified.

Check that Metro serves the bundle (qa_wait {for:"metro_ready"}) and read the logs (qa_device_info {logs:{buffer:"crash"}}). A canvas or game screen with no accessibility nodes looks blank too: check it with qa_visual.

TEXT_INPUT_MISMATCH

After typing, the field holds other text (reordered, characters dropped, or old text left).

Snapshot again and retry the whole value in replace mode (never repeat a failed append); type long text in shorter parts. A max length or input mask that only cuts or reformats the text is a warning, not this code.

BUDGET_EXHAUSTED

The session's action, screenshot, or time budget is spent; the call did nothing (ok:false).

Call qa_report, or start a session with a larger budget.

CANCELLED

The call or job was cancelled. Not a failure, never recorded as a finding.

Re-call if you still want it. Cancelling a call doesn't stop a background job; qa_job_cancel does.

INVALID_ARGUMENT

An undeclared, missing, or wrong-typed argument, an unknown sessionId, jobId or artifact URI, or a tool hidden by SWIPIUM_TOOLS=core. Nothing ran.

Fix the argument; the result lists acceptedParameters. Over-large waitMs / timeoutMs values are clamped to the cap (50000 by default) with a note, not rejected.

STALE_REF

The @eN ref's element is no longer on screen.

Take a new qa_snapshot, or use one of the candidates in the error.