Swipium

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.

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

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

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

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.

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

Fetch a session artifact (screenshot, report, dump, log, recording) by its swipium://session/<id>/<kind>/<name> 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).

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

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.

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.

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.

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

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.

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.

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.

Record the outcome of one workflow for the report. Use outcome:"blocked" + missingPrecondition rather than a false failure; category says why. Attach evidence in artifactUris.

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

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.

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.

Build the session report (release risk, health, outcomes, findings, evidence, env changes) as an artifact; returns a summary + URIs (read reportMdUri, report.md; the full JSON is reportUri, inline with format:"json"). format adds an export: markdown, json, junit, sarif, github-summary, playwright, or flow. qa_test_this execute calls it for you. CI: docs/ci-reports.md.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

Screenshot checks where the UI tree fails (maps, canvases, WDA-less iOS). mode: assert, baseline (.swipium/baselines/<name>.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.

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.

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.