Swipium

Swipium

コーディングエージェントが Android エミュレーターと iOS シミュレーター上でモバイルアプリの QA を行える MCP サーバーです。

Swipium は、AI コーディングエージェント（Claude Code、Codex、Gemini CLI、Cursor、VS Code、その他の MCP クライアント）に、QA エンジニアが使うツールを提供します。アプリを見つけるかビルドし、シミュレーターを起動して、アプリをインストールして起動し、画面を読み取り、実際のユーザーフローに沿ってタップや入力を行い、スクリーンショット、ログ、UI ダンプに基づいたレポートを作成できます。実行内容は、繰り返し実行できるフロー、テストスイート、または Appium コードに変換できます。

TestFlight や Play Console にビルドを提出する前に、エージェントに壊れたログイン画面を見つけてもらいたいモバイル開発者向けです。ローカルで実行されます（stdio を使用し、サーバーはネットワークポートを開きません。また、iOS 用に管理する WebDriverAgent は 127.0.0.1 上のコマンドのみを受け付けますが、画面ストリームのポートはネットワークからアクセス可能です。Security を参照してください）。Appium ではなく adb、simctl、WebDriverAgent を通じてデバイスを操作し、副作用を伴う操作の前にはユーザーの同意を求めます。swipium.com

セッションの概要

You:    Smoke test this app on Android with Swipium.
Agent > qa_test_this { goal: "smoke", waitForCompletion: true }      (runs by default)
        🔐 Consent required (low): • boot_emulator: emulator -avd Pixel_8_API_35 -no-audio -no-snapshot-save -no-boot-anim -gpu auto -no-window
                                   • install_apk: adb -s <Pixel_8_API_35 once booted> install -r -g android/app/.../app-release.apk
You:    Approve                                               (one prompt covers boot + install)
        state: "running", sessionId: "3f9c2a1b", jobId: "a41c09e2"
Agent > qa_job_status { sessionId: "3f9c2a1b", jobId: "a41c09e2", waitMs: 45000 }
        status: "done", result.state: "completed"
        reportHead: "RELEASE RISK: SHIP … app: PASS … coverage: COVERED … tool: PASS …"
        nextRecommendedAction: qa_get_artifact { uri: "swipium://session/3f9c2a1b/report/…-summary.md" }
Agent:  The app launched and passed the smoke checks with no crashes or error screens.

呼び出しは 3 回です。実行を開始し、完了を待ち、インラインの概要だけでは不十分な場合に限り report.md を読み取ります。この概要の元となるレポートは、npx swipium report --latest --format markdown でレンダリングすると、次のようになります。

**Release risk: 🟢 SHIP**

**App status:** PASS - No high-severity app/native finding observed in this run.
**Coverage status:** COVERED - Structured smoke/workflow evidence was collected.
**Tool status:** PASS - No Swipium/MCP limitations or tool errors recorded in this run.

目次

要件 · クイックスタート · スタータープロンプト · 仕組み · ツール · 結果の保存先 · 設定 · CLI · CI · アップグレード · トラブルシューティング · セキュリティ

要件

Node.js 22.12 以降。 古い Node.js ではサーバーが stderr に警告を出力し、swipium verify は失敗します。Swipium が対応するのはエミュレーターとシミュレーターのみです。実機は PHYSICAL_DEVICE_UNSUPPORTED で拒否されます（理由）。構造化された iOS 自動化には WebDriverAgent 6.0 以降が必要です（qa_wda {action:"setup"} でビルドして起動できます）。これがない場合、iOS Simulator はビジュアル操作のみとなります。

MCP： プロトコルリビジョン 2025-06-18、2025-11-25、2026-07-28 に対応する stdio サーバーです。クライアントの最初のメッセージで使用するリビジョンが決まります。Claude Code 2.1.285 以降は 2026-07-28 で、Codex 0.146 は 2025-06-18 で接続します。stdio に対応する MCP クライアントであれば、どれでも動作するはずです（プロトコルのバージョン）。

ホスト	Android Emulator	iOS Simulator
macOS	対応	対応（Simulator ランタイムを含む Xcode が必要）
Linux	対応	利用不可
Windows	実験的で、未テストです。一部のプロセスのクリーンアップ用ヘルパーは ps に依存します	利用不可

アプリ	Swipium に必要なもの
React Native / Expo、デバッグビルド	このプロジェクトの JS バンドルを配信する Metro。qa_metro で起動できます（同意が必要）。そうでない場合、Android と、バンドルが埋め込まれていない iOS Simulator ビルドのどちらでも、実行は METRO_REQUIRED で停止します。このプロジェクトとは別のプロジェクトをポート 8081 で配信する Metro は METRO_WRONG_PROJECT となります。現時点では、Expo dev-client ビルドを手動で Metro に接続する必要があります。このプロジェクトの Metro がすでに配信中の場合、ブロッカーに dev-client を開くためのディープリンクが表示されます。
React Native / Expo のリリースビルド、またはネイティブ Android / iOS	インストール可能なアーティファクト（Android は APK または .aab、iOS は Simulator 用の .app。デバイス用の .ipa は拒否されます）、または Swipium がビルドできるプロジェクト。
Expo managed（android/ または ios/ がない場合）	追加のものは不要です。ビルド（npx expo run:android --device <AVD> または npx expo run:ios。同意が必要）で、まずネイティブプロジェクトが生成されます。この prebuild 手順に失敗すると、ビルドは EXPO_PREBUILD_REQUIRED で失敗します。自分で npx expo prebuild を実行してから、再試行してください。
ビルド済みアプリのみで、ソースがない場合	Simulator 用の .app または .apk をディレクトリに置き、そのディレクトリを projectRoot として渡してください（ビルド済みアプリのテスト）。
Flutter	ビルド可能な Flutter プロジェクト、またはビルド済みの APK / .app。

• Android： platform-tools、Emulator、および少なくとも 1 つの AVD（通常は Android Studio から用意します）。PATH に adb があればそれを使用し、なければ $ANDROID_HOME、$ANDROID_SDK_ROOT、または SDK のデフォルトの場所（~/Library/Android/sdk、~/Android/Sdk、%LOCALAPPDATA%\Android\Sdk）にある SDK 付属のものを使用します。AVD を起動する emulator バイナリと aapt2 は、まず SDK から取得します。.aab ファイルには bundletool が必要です。
• iOS（macOS のみ）： Xcode とシミュレーター。タップ、文字入力、UI ツリーのスナップショットには WebDriverAgent（WDA。Appium が使用する、シミュレーター上で動作する自動化サーバー）が必要です。これがない場合、iOS はビジュアル操作のみとなります（iOS のモード）。

クイックスタート

1. クライアントに Swipium を登録します。 アプリのリポジトリから、Claude Code の場合は次のようにします。

npx -y swipium init claude --scope project           # preview; changes nothing
npx -y swipium init claude --scope project --apply   # writes .mcp.json and the skill, then runs `swipium verify`

Claude Code の場合、init は SWIPIUM_MAX_WAIT_MS=110000 も設定します（1回の呼び出しで最大110秒待機できるため、ほとんどの実行が1回の呼び出しで完了します）。また、swipium-qa agent skill を .claude/skills/ にインストールします（--scope user の場合は ~/.claude/skills/、--no-skill を指定するとインストールされません）。--trust-local（ローカルまたはユーザースコープのみ）を指定すると、プロジェクトコードを実行しない同意アクションも事前承認されるため、ビルド、Metro、WebDriverAgent では引き続き確認が求められますが、起動とインストールでは確認が表示されなくなります。同じサーバーとスキルを含む Claude Code プラグインは plugin/ にあります。Swipium は io.github.GeroPalombo/swipium として MCP Registry にも登録されているため、レジストリ対応クライアントから検索してインストールできます。

同じコマンドで codex、gemini、cursor、vscode にも対応します（swipium init <client> --apply）。Claude Desktop、Windsurf、手動設定、クライアントごとの詳細については、docs/mcp-server.md を参照してください。

Codex： swipium init codex --apply は、タイムアウトを長めに設定し、env_vars 行を含む [mcp_servers.swipium] ブロックを ~/.codex/config.toml（または $CODEX_HOME/config.toml）に追記し、スキルを .agents/skills/ にインストールします。Codex はシェル環境を MCP サーバーに渡さないため、この行がないと SWIPIUM_TEST_*、ANDROID_HOME、JAVA_HOME は Swipium に届きません。ブロックがすでにある場合、init は追加する行を表示します。tool_timeout_sec = 600 はそのままにしてください（Codex のセットアップ）。

ヘッドレス実行（codex exec、claude -p、CI）：これらのクライアントは同意の確認に自動で応答するため、サーバー環境の SWIPIUM_CONSENT_PREAPPROVE でアクションを正確に指定して事前承認しない限り、承認が必要な操作（起動、インストール、ビルド）は実行されません。チャットで承認しても効果はありません。事前承認はデバイスに紐付かないため、複数のエミュレーターやシミュレーターがあるマシンでは、SWIPIUM_DEVICE も指定してデバイスを固定してください（ヘッドレス実行）。

2. クライアントを再起動し、 qa_test_this、qa_doctor、qa_report が一覧に表示されることを確認します。

3. エージェントにアプリのテストを依頼します：

Use Swipium to smoke test this app: qa_test_this with goal "smoke" and
waitForCompletion true, poll qa_job_status while it is running, and
summarize the report.

qa_test_this はデフォルトで実行されます（mode:"execute"。2.3.0 以降）。副作用のないプレビューを行うには mode:"plan" を指定してください。最速で実行するには goal:"smoke" を指定します。goal を指定しない場合、qa_test_this はスモークチェックを実行してから、テストスイートの生成を試みます。スキルをインストール済みであれば、「Swipium でこのアプリをテストして」と頼むだけで十分です。

ツールが PROJECT_ROOT_UNRESOLVED を返す場合は、プロンプトでプロジェクトの絶対パスを指定するか、サーバー設定で SWIPIUM_PROJECT_ROOT を設定してください（プロジェクトルート）。

表示される内容

• 承認確認は1回です。 ビルド、起動、インストールで実行する正確なコマンドが一覧表示されます。MCP elicitation に対応するクライアントでは確認画面が表示されます。それ以外のクライアントは requiresConsent を返すため、エージェントがその内容をユーザーに伝える必要があります。
• 初回のビルドには数分かかることがあります。 実行はバックグラウンドジョブとして行われます。waitForCompletion はデフォルトで約45秒間（init claude が設定する SWIPIUM_MAX_WAIT_MS=110000 がある場合は約105秒間）待機します。エージェントが waitMs を渡さない限り、qa_job_status のポーリングはすぐに返ります。Swipium はエージェントに 45000 を渡すよう指示し、ポーリングの上限は50秒間（この設定がある場合は110秒間）です。
• 状態は2種類あります。 ジョブの status は running、done、failed、cancelled のいずれかです。実行の result.state は completed または needs_input（ジョブは done）、あるいは blocked または unsafe（ジョブは failed）です。needs_input は、ログイン資格情報など、ユーザーへの質問が1つあることを意味します。
• レポートには、アプリ、カバレッジ、Swipium 自体について、個別の判定が含まれます。完了した実行では、判定と証拠 URI 付きの主な検出事項を含む短い概要がインライン表示され、エージェント向けに report.md が保存されます。ブロックされた実行では、修正方法が示されます。npx swipium report --latest --format markdown を実行して、自分で確認できます。

スタータープロンプト

目的	プロンプト
スモークテスト	"Swipium を使って、このアプリをスモークテストしてください。qa_test_this を goal smoke と waitForCompletion で実行し、その後レポートを要約してください。"
ログインのテスト	"Swipium を使って、goal test_login でログインをテストしてください。パスワードは聞かないでください。qa_act で ${SWIPIUM_TEST_EMAIL} と ${SWIPIUM_TEST_PASSWORD} を入力してください。"（両方をサーバーの env に設定してください。プレースホルダーはサーバー側で展開され、シークレット値はマスキングされます）
バグの再現	"Swipium を使って、goal reproduce_bug と goalText: 'クーポン追加後にチェックアウトボタンが何も実行しない' でこのバグを再現してください。証拠を添付してください。"
フローの保存	"直近の Swipium 実行を、qa_generate で login-smoke という名前のフローに変換して保存してください。"
リリース判定	"goal release_gate で Swipium を実行し、リリース判定に合格するかどうかを教えてください。"

MCP プロンプトに対応したクライアントでは、代わりに次の組み込みプロンプトを使用できます：swipium_setup_check、swipium_guardrail_validation、swipium_full_smoke、swipium_bug_repro、swipium_test_feature、swipium_generate_suite、swipium_convert_run_to_flow。

仕組み

qa_test_this {waitForCompletion:true}  >  consent  >  job
                                                       │
         qa_job_status {waitMs}  <─── still running ───┘
           ├─ completed          >  reportHead inline; more in report.md (qa_get_artifact)
           ├─ blocked / unsafe   >  the fix in nextRecommendedAction
           └─ needs_input        >  ask you one question  >  qa_continue_from_blocker (resumes the run)

qa_test_this はアプリを検索またはビルドし、シミュレーターを起動してアプリをインストール・起動し、スモークチェック（さらに goal に応じて探索またはスイート生成）を実行して、必ずレポートを出力します。失敗には failureCode が付与され、その内容は qa_explain_blocker で説明されます。エージェントが直接操作する場合は、セッション（qa_start_session）を開始し、qa_snapshot で画面を読み取り、@e3 などの要素参照（要素が画面上にある間は安定しています）を操作し、既知のステップが3つ以上ある場合は qa_flow_run {flowYaml} でまとめて実行します。

概念の説明は docs/concepts.md をご覧ください。

• プロジェクトルート： テスト対象のリポジトリです。projectRoot 引数、MCP ルート、SWIPIUM_PROJECT_ROOT、CLAUDE_PROJECT_DIR、またはサーバーの作業ディレクトリから取得されます。
• 同意： ビルド、起動、インストール、データ消去、ネットワーク変更、リポジトリ提供のコマンドには、その都度1回限りの承認が必要です。
• セッションとジョブ： セッションには1回の実行に使うデバイス、アプリ、証拠が保持されます。長時間の処理はジョブとして実行し、ポーリングで状態を確認します。
• シークレットとマスキング： テキスト出力では認証情報がマスキングされますが、スクリーンショットではマスキングされません。
• iOS モード： simctl による画面表示のみの操作、または WDA による完全な操作が選べます。
• アプリマップは Swipium がアプリの画面について保持する永続的な記録です。フローは再生可能な YAML スクリプト（docs/flows.md）で、POM スイートは生成されたページオブジェクトテストスイートです。用語集をご覧ください。

ツール

機能別にグループ化されています（引数なしで実行した場合の qa_status も同じグループを返します）。各ツールのパラメーターと動作については、docs/tools.md をご覧ください。swipium verify を実行すると、インストール済みバージョンが公開している内容を確認できます。

グループ	ツール
開始	qa_test_this, qa_status, qa_job_status, qa_job_cancel, qa_explain_blocker, qa_continue_from_blocker, qa_get_artifact
セットアップ	qa_doctor, qa_start_session, qa_prepare_target, qa_prepare_ios_target, qa_ios, qa_wda
ビルド	qa_resolve_target, qa_resolve_artifact, qa_build, qa_bundletool
デバイス	qa_device_info, qa_orientation, qa_geolocation, qa_network, qa_metro, qa_app_control, qa_screen_record
操作	qa_snapshot, qa_inspect, qa_act, qa_clear_overlay, qa_check_health, qa_screenshot, qa_note, qa_visual, qa_wait
実行	qa_smoke, qa_explore, qa_report
アプリマップ	qa_app_map_build, qa_app_map_read, qa_app_map_query, qa_app_map_feature_scope, qa_app_map_update
機能	qa_test_feature
フロー	qa_flow_check, qa_flow_run, qa_flow_compile, qa_flow_repair
生成	qa_generate
テストスイート	qa_suite_read, qa_suite_update, qa_suite_generate, qa_suite_export, qa_suite_lint
問題	qa_issue_log, qa_mobile_audit
初回実行	qa_first_run

すべてのツールに MCP アノテーションが付与されています。読み取り専用ツールでは readOnlyHint:true と openWorldHint:false が宣言されるため、クライアントで自動承認できます。それ以外のツールでは destructiveHint と idempotentHint も宣言されます。

結果の保存先

• <your repo>/.swipium/: アプリマップ、フロー、テストスイート、問題台帳、ビジュアルのベースライン、生成ファイル、WebDriverAgent のビルドキャッシュ（cache/wda-derived-data。プロジェクトあたり約 200 MB。ios.wda.derivedDataPath で場所を変更できます）、および設定（config.json、fixtures.json、policy.json）が保存されます。swipium scan は結果を config.json にマージし、設定したすべてのキー（WDA のチーム、OCR およびマスクのコマンド、appId）を保持します。ファイルを再生成することはありません。appId に appIdSource がない場合、appIdSource:"config.json" の場合、または scanAppId（前回のスキャンで検出され、スキャンによって隣に保存された ID）と異なる場合は、ユーザーが設定した値として扱われます。その場合はスキャン時の appIdSource が残っていても値が保持され、appIdSource は config.json になります。以前のスキャンで書き込まれ、変更していない値は更新されます。2.3.0 より前のスキャンで作成された設定には scanAppId がありません。この場合、スキャン時の appIdSource が設定されたままの手動編集済み appId も置き換えられ、スキャンによって replaced appId <old> in config.json (written by an earlier scan from <source>; ...) と表示されます。ユーザーが設定した値を保持するには、appIdSource を削除してください。Git リポジトリで初めて Swipium がアプリマップ、問題台帳、または WDA ビルドキャッシュを書き込むと、.gitignore に .swipium/ が追加されます。自動的に削除されることはありません。
• ~/.swipium/runs/: セッションごとの状態と証跡（スクリーンショット、ログ、UI ダンプ、レポート）が保存され、swipium:// URI として返されます。サーバープロセスが初めてセッションレジストリを読み込むと、バックグラウンドで（起動ごとに最大 2 秒間）SWIPIUM_RETENTION_DAYS より古いセッションディレクトリが削除されます。ただし、登録済みのセッションと、ルートがまだ存在するプロジェクトごとの最新 SWIPIUM_RETENTION_KEEP 件は保持されます。swipium gc を実行すると、必要に応じてクリーンアップできます。セッションファイルは 0700 のディレクトリ内で 0600 に設定され、~/.swipium の registry.json、projects.json、processes.json も同様です。

設定と環境変数

これらは MCP サーバーの env ブロック（または CLI コマンドの場合はシェル）に設定してください。以下は Swipium が読み取る変数の一覧です。 Codex は、env_vars に記載された名前（および HOME や PATH などの固定ホワイトリスト）だけを転送します。swipium init codex を実行すると、この行が自動的に追加されます。CLAUDE_PROJECT_DIR、SWIPIUM_DISABLE_DEVICE_DISCOVERY、および承認許可（SWIPIUM_CONSENT_PREAPPROVE、SWIPIUM_CONSENT_PREAPPROVE_RUN_CODE、SWIPIUM_ALLOW_REMOTE_WDA）は意図的に除外されています。これらは env = { ... } に明示的に設定してください。そうすることで、継承されたシェルのエクスポートや、クローンしたリポジトリ内の direnv ファイルによって承認が許可されるのを防げます。独自のカスタム SWIPIUM_* フロー変数（デバイスを固定する場合は SWIPIUM_DEVICE も）をリストに追加してください。詳細は、docs/mcp-server.md をご覧ください。

変数	用途
SWIPIUM_PROJECT_ROOT	クライアントが MCP ルートを提供しない場合の、アプリリポジトリの絶対パスです。
CLAUDE_PROJECT_DIR	Claude Code によって設定されます。SWIPIUM_PROJECT_ROOT の次にプロジェクトルートとして使用されます。
ANDROID_HOME, ANDROID_SDK_ROOT	Android SDK の場所です。adb、emulator、aapt2 を検索する際に使用されます（要件を参照）。
BUNDLETOOL_JAR	.aab ファイルの変換に使用する bundletool.jar のパスです。PATH 上の bundletool ランチャーも使用できます。
DEVELOPMENT_TEAM, XCODE_DEVELOPMENT_TEAM	WDA の署名に使用する Apple チーム ID です（.swipium/config.json の ios.wda.developmentTeam が優先されます）。
APPIUM_HOME	Appium がインストールした WDA の追加検索場所です（~/.appium およびグローバル npm に加えて検索されます）。
WDA_PROJECT_PATH, WEBDRIVERAGENT_PROJECT	qa_doctor と qa_wda のステータスで報告される、WebDriverAgent.xcodeproj の追加候補です（ビルドするには wdaProjectPath を渡します）。
SWIPIUM_ALLOW_REMOTE_WDA	事前に許可する、ループバック以外の WDA ベース URL をカンマ区切りで指定します。クライアント設定で設定し、リポジトリ内では設定しないでください。
SWIPIUM_TEST_*	テストアカウントの値です：_EMAIL、_USERNAME、_PASSWORD、_OTP、_TOKEN、_PIN（スターターフローでは _DEEP_LINK も使用します）。フローと qa_act は ${SWIPIUM_TEST_EMAIL} を使用します。fixtures.json では "var": "SWIPIUM_TEST_EMAIL" を使用します。Swipium が起動する子プロセス（ビルド、Metro、xcodebuild、adb、OCR、マスクコマンド）には継承されませんが、フィクスチャのシードスクリプトには継承されます。
その他の SWIPIUM_*	フローとフィクスチャが環境から読み取るのは、SWIPIUM_* という名前の変数のみです（${HOME} や ${AWS_SECRET_ACCESS_KEY} は読み取りません）。認証情報を表す要素（password、secret、token、otp、pin、cvv、key、code など。名前の各要素に基づいて判定するため、SWIPIUM_SHIPPING_ADDRESS は該当しません。ルールを参照）は秘密情報として扱われ、マスクされます。シードスクリプト以外の子プロセスには、SWIPIUM_SECRET_* やこれらの秘密情報名は継承されません。
SWIPIUM_OCR_CMD	qa_visual の find_text に使用する OCR コマンドです（同梱されていません。明示的な同意が必要です）。{image} は PNG のパスに置き換えられ、[{"text","confidence","bbox"}] 形式の JSON を出力します。config.json の ocrCommand が優先されます。
SWIPIUM_VISUAL_MASK_CMD	OCR とビジュアルプロバイダーに渡す前にスクリーンショットをマスクするコマンドです（設定の visualMaskCommand が優先されます）。
SWIPIUM_REQUIRE_ELICITATION=1	クライアントが実際の同意プロンプトを表示できない場合、同意が必要なすべてのアクションを拒否します（CONSENT_REFUSED）。オペレーターによる事前承認は引き続き適用されます。
SWIPIUM_CONSENT_PREAPPROVE	プロンプトなしで承認する同意アクション名を、完全一致でカンマ区切りに指定します（例：prepare_plan,test_this_plan）。codex exec や claude -p など、プロンプトに自動応答するヘッドレスクライアント向けです。ワイルドカードは使用できません。不明な名前は警告とともに無視されます。コードを実行するアクションには、SWIPIUM_CONSENT_PREAPPROVE_RUN_CODE=1 も必要です。また、wda_non_loopback は受け付けられません（SWIPIUM_ALLOW_REMOTE_WDA を使用してください）。サーバープロセスの環境からのみ読み取られ、リポジトリからは読み取られません。各承認は引き続き 1 回限りで、正確なコマンドとともに warn レベルで記録されます。オペレーターによる事前承認を参照してください。
SWIPIUM_CONSENT_PREAPPROVE_RUN_CODE	1 にすると、SWIPIUM_CONSENT_PREAPPROVE で、リポジトリまたはモデルが選択したコードを実行するアクション（build_from_source、flow_mutation_run、ocr_run、start_metro、suite_fresh_state_replay、wda_build、wda_start、およびビルドを含む test_this_plan）も承認できるようになります。codex exec では、そのコードはクライアントのサンドボックス外で実行されます。信頼できるリポジトリでのみ使用してください。
SWIPIUM_RETENTION_DAYS	~/.swipium/runs のセッションディレクトリの保存日数です（デフォルトは 30）。0 または off にすると自動プルーニングが無効になります。swipium gc は引き続き使用できます。
SWIPIUM_RETENTION_KEEP	プロジェクトのルートが存在する間、年齢にかかわらず保持する、プロジェクトごとの最新セッション数です（デフォルトは 20）。一時ディレクトリなど、削除されたルートのセッションは SWIPIUM_RETENTION_DAYS のみで期限切れになります。
SWIPIUM_MAX_WAIT_MS	1 回の qa_job_status のロングポーリング、qa_wait、または qa_test_this {waitForCompletion:true} がブロックできる時間（ミリ秒）です（デフォルトは 50000、1000～230000 に制限されます）。クライアントのツールタイムアウトより少し短く設定してください。swipium init claude は 110000 を書き込みます。サーバー設定を参照してください。
SWIPIUM_TOOLS	core を指定するとコアツールのみを一覧表示します（swipium init codex のセット）。all（デフォルト）を指定するとすべてのツールを一覧表示します。ツール数は、一覧表示されたツールの数になります。
SWIPIUM_DEVICE	サーバーを 1 台のデバイスに固定します。adb シリアル、AVD 名、またはシミュレーターの UDID か完全一致する名前を指定します（すべてのツールで大文字と小文字は区別されません。複数のシミュレーターが同じ名前を共有している場合は MULTIPLE_DEVICES で拒否されるため、UDID で固定してください）。実行と自動バインドではそのデバイスのみが使用されます。別のデバイスを指定する呼び出し（低レベルの qa_ios、qa_wda、qa_bundletool アクションを含む）は DEVICE_PINNED で拒否されるため、SWIPIUM_CONSENT_PREAPPROVE もそのデバイスにのみ適用されます。共有 CI ランナーで設定してください。サーバー環境からのみ読み取られます（デバイスの固定）。
SWIPIUM_ANDROID_DUMPER	agent を指定すると、オプトイン方式の永続的な Android UI ダンパーが有効になります（ホストの負荷によってスナップショットが約 2～7 倍高速になります。小さな JAR をエミュレーターにプッシュし、実行中は他の UiAutomation クライアントをブロックします）。android-agent/README.mdを参照してください。
SWIPIUM_EMULATOR_GPU	Swipium が起動するエミュレーターの -gpu モードです（デフォルトは auto）。使用可能な GPU がないホストでは swiftshader_indirect を使用してください。
SWIPIUM_EMULATOR_COLD_BOOT	1 にすると、AVD スナップショットからクイックブートする代わりに、エミュレーターをコールドブートします（-no-snapshot-load）。
SWIPIUM_LOG_LEVEL	標準エラー出力の最小ログレベルです：debug、info（デフォルト）、warn、error。debug ではツール呼び出しごとに 1 行追加されます（ツール、セッション、所要時間、エラーコード。引数の値は記録されません）。
JAVA_HOME	Gradle ビルドで使用する JDK です。Codex で JDK が見つからない場合、qa_doctor が警告します。
CODEX_HOME	swipium init codex が config.toml を検索する場所です（デフォルトは ~/.codex）。
CLAUDE_CONFIG_DIR	swipium init claude --scope user がスキルをインストールする場所です（<dir>/skills/、デフォルトは ~/.claude）。
CI	設定されている場合、レポートでは実行環境が 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	レポートと課題台帳に記録されるソースリビジョン（コミット、ブランチ、実行 URL）です。
SWIPIUM_DISABLE_DEVICE_DISCOVERY	テストスイートの分離専用です。デバイスの自動検出を無効にします。通常の用途では使用しないでください。
無効な SWIPIUM_MAX_WAIT_MS、SWIPIUM_TOOLS、または SWIPIUM_LOG_LEVEL はデフォルト値にフォールバックし、起動時に stderr に warn 行を出力します。

生成されたフロー、スイート、コードに認証情報の値が含まれることはありません。代わりに SWIPIUM_TEST_*、SWIPIUM_SECRET_N、または SWIPIUM_GEN_<FIELD> を参照し、リプレイ時にこれらを設定します。生成された Appium プロジェクトは、独自の変数（SWIPIUM_PLATFORM、APPIUM_HOST、ANDROID_*、IOS_*、…）を読み込みます。これらについては、各プロジェクトの README に記載されています。

CLI リファレンス

サブコマンドを指定せずに swipium を実行すると、stdio MCP サーバー（クライアントが起動するサーバー）が起動します。swipium --help を実行すると、この一覧が表示されます。

コマンド	説明
swipium（エイリアス swipium serve）	stdio MCP サーバーを起動します。認識されないフラグのみ（--stdio など）が指定された場合は、警告を表示して無視されます。不明なサブコマンドを指定すると使い方を表示して終了コード 2 で終了します。また、サブコマンドの前にフラグを置いた場合も同様で、swipium -y init claude では修正後のコマンドが表示されます。
swipium init <client> [--apply] [--scope local|user|project] [--cwd <dir>] [--no-skill] [--trust-local]	claude、codex、gemini、cursor、vscode の登録内容をプレビューします（デフォルト）。--apply を指定すると登録が適用されます。claude と codex では、swipium-qa スキルもインストールされます（--no-skill を指定するとスキップします）。--trust-local（claude、local または user スコープ）を指定すると、コードを実行しない同意アクションが事前承認されます。--flag value と --flag=value のどちらの形式も使用できます。不明または値が不足しているオプション、--cwd の値がない場合、編集対象外の設定ファイルが指定された場合は終了コード 2 で終了します。適用に失敗した場合、または claude に別の登録がすでにある場合は終了コード 1 で終了し、削除と追加のコマンドが表示されます。docs/mcp-server.md を参照してください。
swipium init flows [--root <dir>] [--force]	スターターのフローテンプレートを .swipium/flows/ に書き込みます（--force を指定しない場合、既存のファイルは保持されます）。存在しない --root を指定した場合は終了コード 2 で終了します。登録用のフラグ（--scope、--apply、--cwd、--no-skill、--trust-local）を指定した場合も同様です。
swipium verify	stdio 経由でサーバーを起動し、すべてのツールが一覧に表示されることを確認して、qa_doctor を実行し、失敗したチェックをすべて一覧表示します。サーバーまたはツールが見つからない場合、qa_doctor がエラーになる場合、または Node.js のバージョンが古すぎる場合は終了コード 1 で終了します。--help は使い方を表示します。
swipium scan [path] [--check | --dry-run | --no-write]	準備状況レポートを表示します。結果は READY、PARTIAL（たとえば、まだインストール可能なビルドはありませんが、qa_test_this がソースからビルドできます）、または BLOCKED です。結果が BLOCKED の場合、または書き込みを行わないフラグが指定されている場合を除き、.swipium/ を作成し、結果を .swipium/config.json にマージします（既存のキーは保持されます）。READY または PARTIAL の場合は終了コード 0、BLOCKED の場合は 1、不正なパスまたはオプションの場合は 2 で終了します。
swipium suite <lint|compile|init> [projectRoot] [--suite <file>] [--strict] [--force]	lint は、壊れやすいページオブジェクトのロケーター、未解決の参照、座標のみを使用するステップを検出します（問題がない場合、または警告のみの場合は終了コード 0、エラーがある場合、または --strict を指定して検出事項がある場合は 1、.swipium/pages がない場合は 2 で終了します）。compile は POM スイートを .swipium/flows/ 配下のフローに変換し、手動で編集したフローは保持します（新しい出力は <slug>.yaml.new に書き込まれます。--force を指定すると上書きされます。フローを書き込むと、残っている .yaml.new は削除されます）。すべてのテストのコンパイルに成功した場合は終了コード 0、それ以外の場合は 2 で終了します。init はスイートについて説明します。メッセージ内のステップ番号は 1 から始まります。サブコマンドが受け付けないオプション（lint は --strict、compile は --suite と --force、init はなし）を指定した場合、または --stirct のようなタイプミスがある場合は、使い方を表示して終了コード 2 で終了します。不明なサブコマンド（1 文字のタイプミスの場合は「もしかして」のヒントを表示）や、値を指定せずに --suite を指定した場合も同様です。--help は使い方を表示して終了コード 0 で終了します。ファイル構成については docs/flows.md を参照してください。
swipium report --format junit|sarif|github-summary|markdown|json	保存済みのレポートをレンダリングします（デフォルトは --latest。--session、--report、--root、--out、--max-age <minutes>、--fail-on-gate を指定できます）。--fail-on-gate によりゲートでブロックされた場合は終了コード 1 で終了します。使用方法のエラー（--fail-on-gate=false を含む）、レポートがない場合、レポートが --max-age より古い場合、--latest --fail-on-gate で新しいセッションにレポートがない場合（--max-age を指定していない場合）、--out への書き込みに失敗した場合、または無効な .swipium/policy.json がある場合は終了コード 2 で終了します。
swipium gc [--dry-run] [--days N] [--keep N]	古い ~/.swipium/runs セッションディレクトリと、古くなった ~/.swipium/projects.json のエントリを削除します。ルートがまだ存在するプロジェクトに限り、最新の --keep 件のセッションを保持します。--days と --keep には 0 以上の整数を指定します。空の値（--days=）または整数以外の値を指定すると、終了コード 2 で終了し、何も削除されません。一部のエントリを処理できなかった場合は終了コード 1 で終了します。
swipium --help / -h、--version / -v	使い方またはバージョンを表示します。

CI

swipium reportは、完了した実行をJUnit、SARIF、GitHub ジョブサマリー、Markdown、またはJSONとしてレンダリングします。.swipium/policy.jsonのリリースゲートがブロックしたときにジョブを失敗させるには、--fail-on-gateを指定します。CLIはデバイスを操作しません。CIでは引き続き、保存済みフローを再生するqa_flow_runなどのMCPツールを呼び出すエージェント（claude -pなど）が必要です。CIでは同意プロンプトに応答する人がいないため、エージェントのステップの前にワークフローでアプリをインストールするか（最も安全です）、エージェントに必要なアクションを正確に事前承認してください。手順：docs/ci-reports.md。

アップグレード

アップグレードのたびにMCPクライアントを再起動してください。古いサーバーを実行したままのクライアントでは、STALE_CLIENTエラーが発生します。

• 2.2.xから2.3.0へのアップグレード： Node.js 22.12以降が必要です。qa_test_thisとqa_test_featureはデフォルトで実行されます（mode:"plan"でプレビューできます）。要素の行では空の名前が省略され、クリックできない要素には末尾に -が付きます。qa_reportは簡易ビューを返します（完全なレポートにはformat:"json"を指定します）。何もテストしなかった実行（アプリを起動したもののワークフローを実行しなかった場合や、デバイスのエビデンスがなくqa_noteのパスしかない場合を含む）は、決してSHIPにならず、--fail-on-gateで失敗します。予算による停止はok:false（BUDGET_EXHAUSTED）となり、デフォルトの予算は30分／60アクション／40スクリーンショットです。qa_act type（およびintoを指定したフローのinputText）では、入力フィールドに入力した内容が読み戻せない場合、座標ターゲットも含めてTEXT_INPUT_MISMATCHで失敗します。起動時にアプリが何も表示しない、またはローディング画面のままの場合、BLANK_SCREENでblockedになります。~/Library、~/Downloads、/tmp、/Applicationsなどの共有フォルダーはprojectRootとして指定できません。管理対象のWebDriverAgentは、8100ではなくシミュレーターごとのポート（8101～8900）で実行されます。無効な.swipium/policy.jsonがある場合、swipium reportは終了コード2で終了します。Swipiumが起動したエミュレーターは、スナップショットから-gpu autoでクイックブートします。2.3.0のアップグレードチェックリストを参照してください。
• 2.0.xから2.2.0へのアップグレード： structuredContent内の要素リストは@eN形式の文字列になりました（オブジェクトにはresponseMode:"verbose"を指定してください）。Codexにはenv_varsの行が必要です。qa_wda buildはジョブを返し、待機は約50秒以内に終了します。2.2.0のアップグレードチェックリストを参照してください。
• 1.5.xからのアップグレード： 2.0ではツールが削除・改名され、フローとフィクスチャではSWIPIUM_*変数のみが読み取られ、インストールごとに同意を求めるようになりました。まず2.0.0のアップグレードチェックリストと移行表を確認してから、2.2.0のチェックリストに進んでください。

トラブルシューティング

すべてのエラーにはfailureCode、nextSteps、retrySafeが含まれています。qa_explain_blockerは任意のコードを説明し、qa_doctorはツールチェーンを確認します。全カタログはdocs/tools.mdにあります。

failureCode	意味	対処方法
PROJECT_ROOT_UNRESOLVED	Swipium はテスト対象のアプリを特定できません。	プロンプトで絶対パスを指定するか、SWIPIUM_PROJECT_ROOT を設定してください（プロジェクトルート）。
STALE_CLIENT	クライアントでアップグレード前のサーバーが実行されているか、削除済みのツールが使われています。	MCP クライアントを再起動してください。
ADB_NOT_FOUND	Android platform-tools が見つかりません。	Android Studio からインストールしてください。GUI クライアントまたはデフォルト以外の場所を使用する場合は、サーバーの env で ANDROID_HOME を設定してください。
NO_DEVICE	オンラインのエミュレーターがなく、起動可能なエミュレーターもない、要求されたデバイスが存在しない、またはバインドされていたデバイスが切断されました。	AVD または iOS Simulator を作成してください。qa_test_this が起動します。
DEVICE_PINNED	呼び出しで指定したデバイスが、SWIPIUM_DEVICE で固定されたデバイスと異なります。	device を省略するか、サーバーの env で SWIPIUM_DEVICE を変更してください。
PHYSICAL_DEVICE_UNSUPPORTED	実機のみが利用可能です。	エミュレーターを起動するか、実機を取り外してください。
METRO_REQUIRED	デバッグ用の RN／Expo ビルドには、Metro の実行が必要です。	Metro を起動し（qa_metro {action:"start"} または npx react-native start ／ npx expo start）、再試行してください。Metro がすでに実行中で、Expo dev client が接続されていないだけの場合は、ブロッカーに表示されたディープリンクを開くか、dev client でサーバーをタップしてください。
METRO_WRONG_PROJECT	ポート 8081 の Metro が別のプロジェクトを配信しています。	別のプロジェクトの Metro を停止し、このプロジェクトの Metro を起動してから再試行してください。
EXPO_PREBUILD_REQUIRED	ビルド中に Expo ネイティブプロジェクトの生成に失敗しました。	npx expo prebuild を実行してエラーを確認し、修正してから再試行してください。
WDA_UNREACHABLE	WebDriverAgent が実行されていないか応答していません（または起動後にハングしました）。	qa_wda {action:"status"} を実行し、続けて start または attach を実行してください。WDA がハングした場合は、qa_wda {action:"stop"} を実行し、続けて setup と attach を実行してください。単純なスモークチェックには、ビジュアルのみで動作する goal:"smoke" を使用してください。
DEVICE_UNRESPONSIVE	Android エミュレーターが時間内に adb に応答しませんでした（停止または過負荷）。入力が一部反映された可能性があります。	qa_screenshot で画面を確認し、アプリまたはエミュレーターを再起動してから再試行してください。
BACKEND_UNSUPPORTED	このアクションには WDA が必要です（iOS のビジュアルのみモード）。	qa_wda で WDA を接続するか、qa_visual と qa_screenshot を使用してください。
CONSENT_DECLINED / CONSENT_CANCELLED / CONSENT_REFUSED	何も実行されませんでした。アクションを拒否した、プロンプトを閉じた、タイムアウトした、または失敗した（理由は elicitationFailure に記載）、あるいは SWIPIUM_REQUIRE_ELICITATION=1 によってブロックされました。	アクションを実行する場合は、新しいプロンプトを表示するために再度呼び出してください。likelyAutomatic: true は、ヘッドレスクライアントが 1.5 秒未満で応答したことを意味します。繰り返し呼び出さず、SWIPIUM_CONSENT_PREAPPROVE で指定された action を事前承認してください（ヘッドレス実行）。
NOT_TESTED	実行がアプリに到達していないか、アプリを操作していません（起動とエージェントの合格メモだけではテストになりません）。そのため、レポートはリリースゲートに合格しません。	レポートに記載されたブロッカーを解消するか、qa_smoke またはフローを実行してから再実行してください。
BLANK_SCREEN	起動後（約 15 秒、Metro 実行中は最大 30 秒）にアプリの UI が表示されなかったか、待機終了時もスプラッシュ画面または読み込み画面のままで、起動を確認できませんでした。	Metro がバンドルを配信していることを確認し（qa_wait {for:"metro_ready"}）、ログを確認してください（qa_device_info {logs:{buffer:"crash"}}）。アクセシビリティノードのないキャンバスやゲーム画面も空白に見えることがあります。qa_visual で確認してください。
TEXT_INPUT_MISMATCH	入力後、フィールドに別のテキストが入っています（順序が変わった、文字が欠落した、または古いテキストが残った）。	もう一度スナップショットを取得し、置換モードで値全体を再入力してください（失敗した追加入力を繰り返さないでください）。長いテキストは短く分けて入力してください。最大長や入力マスクによってテキストが切り詰められたり書式変更されたりするだけの場合は、このコードではなく警告になります。
BUDGET_EXHAUSTED	セッションのアクション数、スクリーンショット数、または時間の予算を使い切りました。呼び出しは何も実行しませんでした（ok:false）。	qa_report を呼び出すか、より大きな budget を指定してセッションを開始してください。
CANCELLED	呼び出しまたはジョブがキャンセルされました。失敗ではなく、検出事項として記録されることもありません。	まだ必要であれば再度呼び出してください。呼び出しをキャンセルしてもバックグラウンドジョブは停止しません。停止するには qa_job_cancel を使用してください。
INVALID_ARGUMENT	宣言されていない引数、必須の引数の欠落、型の誤り、不明な sessionId、jobId、アーティファクト URI、または SWIPIUM_TOOLS=core によって非表示になったツールが指定されました。何も実行されませんでした。	引数を修正してください。結果に acceptedParameters が表示されます。大きすぎる waitMs ／ timeoutMs の値は拒否されず、注記とともに上限（デフォルトは 50000）に調整されます。
STALE_REF	@eN で参照される要素が画面に表示されなくなっています。	新しい qa_snapshot を取得するか、エラーに示された candidates のいずれかを使用してください。
クライアントでツール呼び出しがタイムアウトする場合は、ツールのタイムアウトを延長してください（Codex の場合は tool_timeout_sec = 600）。待機とジョブのポーリングは約 50 秒以内に終了しますが、大規模な qa_ios install、qa_smoke での長時間の保存済みフロー、qa_mobile_audit など、一部の同期処理にはさらに時間がかかることがあります。

セキュリティ

Swipium はローカルの stdio プロセスであり、サーバーはネットワークポートを開きません。iOS 用に管理する WebDriverAgent は 127.0.0.1 のみでコマンドを受け付けますが、WebDriverAgent では制限できないため、MJPEG 画面ストリーム（ポート = WDA ポート + 1000、例：9101）はすべてのネットワークインターフェイスで待ち受けます。信頼できないネットワークではファイアウォールを使用してください。副作用を伴う操作には、同意が必要です。各承認は 1 回のみ使用でき、セッションに紐付けられます。また、操作を事前承認できるのはサーバー自身の環境のみ（SWIPIUM_CONSENT_PREAPPROVE）であり、リポジトリ内のファイルやモデルからはできません。既知のシークレット値は、スナップショット、成果物、レポートからマスキングされ、生成された出力にもシークレットの漏えいがないか確認されます。クローンしたリポジトリの .swipium/ は信頼できないものとして扱われます。リポジトリから提供されたコマンドは同意プロンプトにそのまま表示され、フローが読み取るのは SWIPIUM_* 変数のみであり、Swipium が git を実行することはありません。スクリーンショットはマスキングされないため、それが問題となる場合は qa_start_session { sensitive: true } を使って、すべての画面キャプチャを拒否してください。詳細は脅威モデルをご覧ください。脆弱性はセキュリティポリシーに従って非公開で報告してください。

貢献とライセンス

CONTRIBUTING.md、SUPPORT.md、ドキュメントの目次、および変更履歴をご覧ください。MIT ライセンスです。詳細は LICENSEをご覧ください。