Diagnose the local QA toolchain (Node, Android SDK/emulator, Xcode/simctl, WDA) and stale-client symptoms; run it first when setup fails.

Open a QA session for the low-level tools (qa_snapshot, qa_act, flows); qa_test_this opens its own. projectRoot defaults to MCP roots > SWIPIUM_PROJECT_ROOT > CLAUDE_PROJECT_DIR > a project-like cwd. Default budget: 30 min / 60 actions / 40 screenshots. fixtures declare preconditions; unmet ones report blocked, not failed.

Prepare an Android Emulator and the app under test: bind or boot the device, Metro + adb reverse for RN/Expo, install, launch, verify. One combined consent covers boot/install; long steps return a jobId. bindOnly stops after bind/boot.

Control an iOS Simulator (macOS): list, boot (binds it to the session), install (.app), launch, terminate, openurl, logs, privacy_reset, erase (wipes it). install, privacy_reset and erase are consent-gated. A slow cold boot returns status:"booting" (poll qa_wait for:"simulator_booted"). Structured iOS automation: qa_wda.

Set up and manage iOS WebDriverAgent (WDA), needed for structured iOS tap/type/snapshot; start with action:"setup": it reuses a running WDA, else builds (if no build exists) and starts it as one consent-gated job (poll qa_job_status, then qa_wda attach). build/start are consent-gated; attach takes an external webDriverAgentUrl; status/doctor/diagnose/logs/tune inspect.

Read-only device info. Android: model, SDK, ABIs, locale, screen, orientation (listPackages:true adds third-party packages; logs:{…} captures filtered logcat). iOS Simulator: name, runtime, state, screen.

Set orientation (Android Emulator only): portrait, landscape, or auto. Logged as an environment change.

Spoof the GPS location (Android Emulator only; consent-gated, logged as an environment change).

Test offline/online behavior via airplane mode (Android 11+). action: status, offline/online (consent-gated), restore. The original state is restored on qa_report, on restore, and on server shutdown.

Manage the Metro bundler for debug RN/Expo builds: status, diagnose (adds RedBox/logcat evidence and fixes), start (consent-gated: adb reverse + Metro), stop. After start, relaunch with qa_prepare_target.

Control the app under test: launch, foreground, background, force_stop, restart (force_stop + launch, for persistence checks), clear_data and fresh_start (wipe data: destructive, consent-gated; RN/Expo also need acknowledgeBundleRisk).

Record the screen to an mp4 artifact: start (consent-gated; avoid password/OTP screens), status, stop. save:"on_failure" keeps only failing runs. One recording per session; Android stops after ~3 min.

Save a screenshot as a session artifact and return its swipium:// URI. Withheld on password/OTP screens unless force:true. Counts against the screenshot budget. inline:true also returns the image (JPEG, long edge 1568 px, scale in the text) for clients that can see images.

Read the current screen as addressable elements (@e1, @e2...) for qa_act, with a snapshotQuality verdict; call it before acting and after navigation. Interactive elements only, capped on busy screens (filter finds the rest). A trailing " -" marks a non-clickable element. Refs stay stable while the element stays.

Inspect one element: full attributes (class, ids, text, bounds, flags) of an @eN ref from the last qa_snapshot.

Tap, type, clear, swipe, scroll, press a key, open a URL or wait: one UI step, then it waits for the screen to settle and reports changed/settled, snapshot quality, health, new elements. Target: an @eN ref from qa_snapshot, text, id, a native selector (WDA iOS), or x/y. For 3+ known steps, batch them in one qa_flow_run {flowYaml}. Details: docs/tools.md#qa_act.

Clear what blocks the screen (keyboard, LogBox, permission dialog, toast); strategy "auto" handles the topmost. targetRef checks whether that element is still obstructed. Returns what was cleared and what remains.

Health check of the current screen: crash, ANR, error boundary, error surface, app still in the foreground. High-severity findings are real bugs. qa_act runs it automatically.

Poll or wait on a background job (qa_test_this, qa_prepare_target, qa_explore, qa_build run, ...): status, progressDetail, and result/error when finished (qa_test_this: state completed/blocked/unsafe/needs_input, reportUri, suite, smoke, health). waitMs long-polls until the job leaves "running" (else waited.timedOut:true).

Cancel a running background job and abort its child processes (build/boot/install/record). Returns {jobId, cancelled}; cancelled:false means it already finished or is unknown. Side effects already applied are not rolled back.

Fetch a session artifact (screenshot, report, dump, log, recording) by its swipium://session/// URI when the client lacks MCP resources. Text is inline (over 1 MB: the head, or the tail for logs). Binaries return metadata; mode:"inline" returns the bytes (images as JPEG, long edge 1568 px, scale in the text).

Record the outcome of one workflow for the report. Use outcome:"blocked" + missingPrecondition rather than a false failure; category says why. A pass/fail note captures a checkpoint screenshot and links the steps since the last note; extra evidence goes in artifactUris (this session's URIs only, others are dropped).

Screenshot checks where the UI tree fails (maps, canvases, WDA-less iOS). mode: assert, baseline (.swipium/baselines/.png), diff, find_text (OCR, consent-gated), find_image. Finds return device coordinates + coordinateSpace; tap:true taps it (recorded + budgeted). Password/OTP screens need force:true; unverified credential screens: assert/diff not saved. Details: docs/tools.md#qa_visual.

Validate a flow (flow name/path or flowYaml) without running it: schema errors with the offending step, plus warnings. Per-backend preview: qa_flow_run mode:"plan".

Run a YAML flow (saved, or inline flowYaml to batch known steps) on the prepared app; mode:"plan" previews per-backend support without a device. Server-side, fail-fast, with setup/teardown; mutating and OCR steps are consent-gated; a failure returns the step, screenshot, failureCode, and health. Pass flow (name/path) or flowYaml, plus variables. Steps: docs/flows.md#step-reference.

Generate reusable test assets from the actions recorded in this session. target: flow (Flow V2 YAML), pom (page objects), suite (POM suite under .swipium/, compiled to flows, replay-gated), testcases (TC catalog), appium (WebdriverIO or Python project; can bootstrap from projectRoot). mode:"plan" previews. Durable repo suite: qa_suite_generate.

Run a smoke test server-side: optionally launch, run the baseline (snapshot quality + health + evidence screenshot), then every saved flow in .swipium/flows. Records a qa_note per workflow; call qa_report after. Needs a prepared device.

Build the session report: returns a short summary + URIs (reportMdUri = report.md to read; reportUri = full JSON, inline with format:"json" minus steps; reportHtmlPath = report.html, give the user that path). format adds an export: markdown, json, junit, sarif, github-summary, flow, playwright (deprecated). CI: docs/ci-reports.md.

Start here to test a mobile app (Android/iOS): finds or builds the app, picks an emulator/simulator, runs prepare > smoke > explore > report > suite as a job (mode:"execute", default; pass waitForCompletion:true or poll qa_job_status). mode:"plan" only plans, no side effects. One consent covers boot/install/build; every terminal state has a report. iOS without WDA: visual-only smoke.

Prepare an iOS Simulator: boot, install a simulator .app (consent-gated), launch, verify, and report whether WDA structured automation or visual-only mode is available. .ipa files are refused.

Compile a POM suite on disk (.swipium/suites/.yaml) into runnable flows under .swipium/flows/ and validate them. No session needed; qa_generate target:"suite" already compiles what it generates.

Explore the prepared app automatically as a job (poll qa_job_status): taps ranked safe actions, checks health, builds a screen graph, updates the app map, and records taps for qa_generate. Destructive actions (delete/pay/send/logout) are skipped unless one candidate is approved; an auth wall without credentials returns needs_input.

Get past a first-run gate (login, sign-up, OTP, onboarding, permissions, paywall). mode:"plan" (default, read-only) classifies the screen and returns a safe plan. mode:"continue" runs bounded steps: generated data only in test/staging, never purchases, one needs_input question on OTP. Needs a prepared device.

Session status and the next tool to call; cheap, call between steps. Without sessionId: first-call orientation (how to drive Swipium: first call, polling, stop rules, tool groups). With sessionId: compact state (device, app, budget left, counters, findings, last job, workarounds, readiness) and nextBestAction (tool, args, why); goal biases it.

Explain a failureCode in plain language: what it means, who owns the fix (app / environment / Swipium / user), whether it is retry-safe or Swipium can fix it, and the recovery step.

Answer a needs_input question (credentials, OTP, platform, device, monorepo target) and get the next call. Secrets (passwords/OTP/tokens) are redacted at once and never echoed or logged (flows use ${VAR}). Non-secret choices map onto the re-invocation args. Returns accepted, ignored[], projectRoot, nextAction; with no new consent needed it starts the resumed job (jobId).

Build or update .swipium/app-map.json: a static scan of routes and screens (Expo Router, React Navigation, Android, SwiftUI/UIKit, Flutter), plus the latest exploration graph when sessionId is given.

Read a compact app-map section: summary (default) | screens | features | auth | automation | testSuite | full; featureId or screenId drills into one node. Large sections come back as a resource URI.

Search the app map (features, screens, code, tests) with a natural-language query. Returns ranked results with sources and the suggested next tool call.

Resolve a feature (featureId, or a query like "checkout") to a test scope: code, screens, existing tests, coverage gaps, strategy, ranked candidates. Works without a map (code scan). Read-only.

Targeted app-map edits without a rebuild: add a note, register test cases, link an automation suite, set the environment, or override a feature's coverage. A matching id/path is overwritten.

Track bugs across runs in the project issue ledger (.swipium/issues-log.jsonl). mode: history (default, filterable), log (record an observation; re-observing a fixed issue reopens it), mark_fixed, verify_fixed (needs current-run evidence), suppress (expires; unsuppress:true lifts it), metrics (trends). Transitions take issueId or fingerprint.

Release-readiness audit: plan (default, no device) or execute. profile: smoke, account_cycle (create/logout/login/reset on a disposable account), store_compliance, resilience (offline/relaunch/rotation; airplane mode is consent-gated), release_gate (all). execute needs a prepared session, logs failed/blocked checks to the issue ledger, passes nothing without evidence.

Read the repo suite (.swipium/test-suite.json), filtered by functionality/status, as a summary, json, or markdown, plus a resource URI for the full suite.

Add or update cases in the repo test suite: a case matching feature + objective + steps is updated, new ones get stable TC ids. mergeMode decides whether generated fields overwrite curated ones.

Generate cases from this session (recorded actions, outcomes, exploration coverage) and merge them into the durable repo suite .swipium/test-suite.json (re-runs update, no duplicates). Returns cases, skipped features, and coverage gaps. Per-run assets: qa_generate.

Export the repo test suite as markdown, yaml, json, or junit; save:true writes it under .swipium/test-suite-export/.

Lint the repo test suite (missing results, stale links, duplicate ids, brittle automation, unsafe adversarial cases) and generated page objects (fragile locators). Returns errors and warnings.

Repair a failed flow step: suggest a stronger locator and app changes (testID/accessibilityIdentifier); apply:true patches simple selector steps at high/medium confidence (low confidence: refused, applied:false + a note).

Test one named feature (e.g. login, checkout). mode:"execute" (default): a job that explores toward it, records pass/fail/blocked per case, and writes a report (poll qa_job_status). mode:"plan" (read-only): scope, cases, fixtures, plan. Without sessionId it bootstraps from projectRoot (consent-gated). Auth, paywall, or missing-fixture gates report blocked, not failed.

Find the best installable build (.apk/.aab/.ipa/.app) in Gradle/Flutter/Xcode outputs. Returns ranked candidates (build type, installability, app id, warnings) and the paths searched. Side-effect free.

Pick the emulator/simulator to test on, deterministically (honors platform, device, artifact; prefers an online one, else plans a boot). Returns selected, reason, alternatives, willBoot. include: context (framework, artifacts, devices, toolchain) and/or plan (READY/BLOCKED/UNSAFE workflows). Boots nothing; physical phones are unsupported.

Build the app from source. mode:"plan" (default, no side effects): commands, cwd, expected artifacts, toolchain status. mode:"run" (consent-gated job, needs sessionId): runs them, stores the build log, re-resolves the artifact. Failures are typed (GRADLE_FAILED, XCODEBUILD_FAILED, ...) and are not test failures.

Convert an .aab into an installable APK with bundletool (cached in .swipium/artifacts/) before qa_prepare_target. Default: a universal APK; connectedDevice:true builds a device APK set, install:true installs it (consent-gated). Runs as a job.

Wait for a setup condition instead of shell sleep: device_online (adb), metro_ready, wda_ready (after qa_wda start returned status:"starting"), or simulator_booted (the bound iOS Simulator, after qa_ios boot returned status:"booting"). Returns satisfied, or timedOut:true (call again). Jobs: qa_job_status waitMs.