Swipium

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.

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

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.

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.

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

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.

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.

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.

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.

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.

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

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.

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

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.

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

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

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.