tapp

Tapp

**Tapp を使うと、コーディングエージェントは実際の iOS、Android、Web の画面で UI の変更を検証し、レビュー済みの証拠を決定論的な CI チェックに変換できます。**画面を調査して操作し、技術的な問題を探すために探索し、重要な操作経路を再生可能なテストとして保存できます。

探索では、検出結果、カバレッジ、証拠、制限事項を報告します。pass、fail、inconclusive を返すのは、リポジトリに接続されたゲートだけです。Tapp は、自律的なクロールを主観的な「リリース可能」スコアに変換しません。

モックではなく、実際の証拠です： この公開 DemoApp の実行では、観測されたルート操作を 3 回行い、指定された iOS 画面に到達しました。自律探索の 45 秒の動画を見るか、サニタイズ済みの Web 証拠レポート全体を確認してください。

サポート対象：

対象アプリ	実行環境
iOS	Xcode を搭載した macOS 上のシミュレーター。XCUITest とアクセシビリティを通じて操作します
Android	adb を使う、接続済みのエミュレーターまたはデバイス。UIAutomator を通じて操作します
Web	Playwright Chromium 上で動作する、自社所有のブラウザーアプリ
Windows デスクトップ	Windows UI Automation を通じた WPF、WinForms、WinUI アプリ — 初期の実行環境はパイロットを通じてセットアップします

Windows は、前提条件がインストールされていれば Android と Web のテストをホストでき、Windows デスクトップの対象環境でもあります。

Tapp をコーディングエージェントに使わせる

セットアップ後、ユーザープロンプト全体は次のとおりです。

Tapp を使ってこのアプリをテストしてください。

公式スキルは、役に立つ範囲で最小の操作を選び、複数のアプリターゲットがあるリポジトリに対応し、視覚的な証拠を確認し、探索時の観察結果とゲート判定を分けて扱うようエージェントに教えます。

Claude Code、Codex、Cursor、Copilot、その他の Agent Skills クライアント（推奨）：

npx -y skills add aarwitz/tapp --skill tapp

これにより、オープンな Agent Skills ワークフローが現在のプロジェクトにインストールされ、エージェントが npm CLI を直接実行できるようになります。調査、重点的な証拠収集、自律的な探索、決定論的なリプレイ、ゲーティングには、MCP サーバー、プラグイン、アカウント、API キー、Tapp のグローバルインストール、プロンプトブロックの貼り付けは必要ありません。ユーザー全体にインストールするには -g を追加し、クライアントを限定するには --agent claude-code、--agent codex などのセレクターを追加します。アプリのリポジトリからエージェントを起動または再起動し、上記の短いプロンプトを使用してください。

Claude Code — オプションの拡張スキルと MCP ツール：

claude plugin marketplace add aarwitz/tapp
claude plugin install tapp@tapp

このプラグインには、同じ tapp Agent Skill と、それに対応する npm ベースの MCP サーバーが同梱されています。スクリーンショットの結果をインラインで表示したい場合や、エージェントが1つの永続セッション内で任意の複数ステップの操作をインタラクティブにタップ、入力、記録する必要がある場合に追加してください。スキルから CLI を使う基本的なワークフローには必要ありません。

ライブサイト、本番環境、または所有していないサイトの場合： エージェントは tapp explore --read-only / tapp_explore {readOnly:true} を使用します。ページをレンダリングして読み取りますが、クリック、入力、送信は一切行いません。探索は、所有するアプリと環境で行ってください。

エージェント連携を使わない場合： アプリのリポジトリから npm パッケージを1行で直接実行します。

npx -y @aarwitz/tapp@latest init . --explore

VS Code： Marketplace から Tapp をインストールしてください。Copilot に同じクロスプラットフォームの Agent Skill を提供するほか、iOS シミュレーター向けの重点的なツールと、自動更新されるスクリーンショットプレビューも利用できます。このプレビューは、埋め込み型の Simulator でも動画ストリームでもありません。Android と Web も、スキルの CLI/MCP ワークフローから利用できます。

チーム： Tapp のコア部分は MIT ライセンスを維持しています。ご自身で管理するインフラストラクチャでの、リポジトリへの実践的な導入支援、重要なジャーニーのセットアップ、CI 連携を対象とした小規模な有料先行パイロットを受け付けています。 プライベートデータを共有せずに申し込む。

you:    "Add a logout button to the settings screen"
agent:  *writes the Swift*
agent:  *tapp: finds Settings in source, follows its previously observed route, screenshots it*
agent:  "Done — and here it is working on the simulator: [screenshot]"

npm CLI クイックスタート

要件：Node ≥ 18。iOS には macOS + Xcode、Android には adb と接続済みのエミュレーター／デバイス（Tapp が既存の APK をインストールするのではなく、ソースからビルドする場合は JDK 17 も必要）、Web には Playwright + Chromium が必要です。tapp doctor では、これらが個別に報告されます。

アプリのリポジトリから、一度 Tapp に基礎情報を与えたら、以降のチェックでは最小限の操作を使います。

npx -y @aarwitz/tapp@latest init . --explore # first run: detect/build, explore, and ground .tapp/ui-map.json
npx -y @aarwitz/tapp@latest look            # one current screen + screenshot
npx -y @aarwitz/tapp@latest explore --goal "Save storefront settings visible above keyboard" # source + observed-route fast path
npx -y @aarwitz/tapp@latest explore         # later broad exploration (observation, not a gate)

ソースは explore --goal に、要求された UI がありそうな場所を伝えます。ナビゲーションを許可するのは、.tapp/ui-map.json ですでに確認されているルートだけです。新しいリポジトリにそのようなルートがまだない場合、Tapp はアプリ内を推測で操作せず、ソースの証拠を返します。

Claude Code はファイル読み取りツールで保存された画像を確認できます。Codex は view_image で開けます。エージェントは、スクリーンショットが何を証明しているかを報告し、探索結果をそのまま伝える必要があります（これは観察結果であり、マージの判断ではありません。ゲート判定は tapp ci が行います）。また、HTML の証拠レポートへのリンクも提示します。この一連の作業に Tapp サーバー、アカウント、グローバルインストール、API キー、バンドル ID は必要ありません。プラットフォームのランタイムは引き続きインストールする必要があり、リポジトリの導入時には .tapp/ にレビュー済みの設定を書き込むことがあります。

製品名、実行ファイル名、パッケージのリーフ名はいずれも Tapp です。npm では @aarwitz/tapp として配布されますが、インストール後のコマンド名は tapp のままです。

保守可能なリリース用インフラストラクチャをブートストラップするには、Tapp が何かを書き込む前に、リポジトリモデルと基礎情報に基づいた計画をプレビューします。

npx -y @aarwitz/tapp@latest init . --dry-run --json-out /tmp/tapp-init.json
# Build/start the detected web target, ground the first UI Map, then stop it.
npx -y @aarwitz/tapp@latest init . --explore --platform web
# Or build/install the detected Xcode target, ground the map, and persist the validated scheme.
npx -y @aarwitz/tapp@latest init . --explore --platform ios --target .
# Or connect to an already-running owned URL:
npx -y @aarwitz/tapp@latest init . --explore --platform web --url http://127.0.0.1:4173
# If the app has roles/accounts, bind names once; values stay in local/CI secrets.
npx -y @aarwitz/tapp@latest plan actor set alice . --role member --session isolated \
  --credential email=ALICE_EMAIL --credential password=ALICE_PASSWORD
# Review-only path: tapp init . → tapp plan show → tapp plan review --approve ...

# After approved drafts replay and are promoted, establish the selected target's baseline
# through the ordinary full gate, then generate the reviewable GitHub workflow.
npx -y @aarwitz/tapp@latest ci baseline . --platform web
npx -y @aarwitz/tapp@latest ci install .

Actor のセットアップでは、既存の Actor を上書きしません。レビュー済みの役割、セッション、プロビジョニング、または認証情報のバインディングを置き換える場合に限り、--replace を指定して actor set を再実行してください。 複数のアプリ（iOS と Web など）を含むリポジトリで、明示的なターゲットを指定せずに tapp init . --explore を実行すると、検出順でターゲットを推測することはありません。以前の 選択が記録されていても同様です。対話型のターミナルでは番号付きのセレクターが表示され、 非対話型 CLI ではターゲットを選択するための正確なコマンドが出力されます。一方、MCP では 構造化された選択肢も返されます。選択する前にビルドや書き込みが行われることはありません。 選択後、モデルは検出されたすべてのターゲットを保持し、次回のターゲット指定なしの tapp explore で使うデフォルトとして選択を記録します。明示的な init --explore は、 オンボーディング／更新の操作であるため、引き続き選択を尋ねます。選択されていない ターゲットだけに該当するセットアップ上の不足は、選択した実行の失敗ではなく、参考情報として 表示されます。

ベースラインコマンドは、探索と選択したすべての決定論的なテストスイートが確実に成功した後にのみ 書き込みを行います。.tapp/baselines/<platform>/<target-id>.json に保存されます。生成された ワークフローではこの正確なターゲット ID が使われるため、同じプラットフォーム上の 2 つのアプリが ベースラインを共有することはありません。ci install は .github/workflows/tapp.yml と .tapp/ci.json を書き込みます。未解決のビルド設定や既存ファイルとの競合がある場合は処理を拒否し、 コミット、プッシュ、ブランチ保護の有効化、GitHub リソースの作成は行いません。本番環境で使う前に、 生成された Tapp リリース参照を確認し、変更されないコミット SHA に固定してください。

look と explore では、リポジトリのディレクトリ、path/to/App.app、バンドル ID、または ターゲットの指定なし（リポジトリまたはインストール済みアプリを自動検出）を指定できます。

npx -y @aarwitz/tapp@latest look [target]         # launch the app → screen summary + screenshot file
npx -y @aarwitz/tapp@latest look [target] --tree  # + the accessibility tree of the current screen
npx -y @aarwitz/tapp@latest look                  # no target on iOS: the booted simulator as it is right now

iOS では、look --tree はインストール済みアプリを調査し、ビルド、アンインストール、置き換えは 行いません。ターゲットを指定しない場合は、リポジトリに記録された iOS ターゲット、または唯一の インストール済みアプリを使用します。選択が曖昧な場合は、選択できるようインストール済みアプリの 一覧を表示します。特定のサンドボックスビルドを調査するにはバンドル ID を渡してください。 置き換える場合は tapp_build（MCP）または init . --explore を実行してください。

iOS Flow のエビデンスには、成功時と失敗時の再生での flow-final.png と、失敗したステップでの flow-failure-N.png が含まれます。ログ、JSON レポート、XCTest の結果バンドルも含まれます。

Web：npx -y @aarwitz/tapp@latest explore http://localhost:3000 (初回のみのセットアップ： npm i -g playwright && npx playwright install chromium)。--watch を追加すると、Tapp が制御する 分離された Chromium ウィンドウが開き、ページ上のポインター／アクションラベルとともにクリックを 追跡します。Tapp は保存するエビデンスのスクリーンショットからこのウォッチ UI を隠し、個人用／ デフォルトのブラウザープロファイルは自動操作しません。

Web の対象を絞った調査では、ローディング状態が落ち着くまで短時間待機します。同意または位置情報の モーダルが画面をブロックしている場合は、同じパッケージのみの呼び出しで閉じてから、確認したい コンテンツが表示されるまで待ちます。

npx -y @aarwitz/tapp@latest look https://example.com --tap "Not now" --wait-for "Dashboard"
npx -y @aarwitz/tapp@latest look https://example.com --tree --tap "Not now" --wait-for "Dashboard" --json

Android：

npx -y @aarwitz/tapp@latest explore path/to/app-debug.apk --platform android --app-id com.acme.app
npx -y @aarwitz/tapp@latest look com.acme.app --platform android

操作したジャーニーを決定論的なテストに変換するか、手書きする前に Flow の完全な形式を出力します。

npx -y @aarwitz/tapp@latest validate --example           # a complete starter Flow, with the step vocabulary
npx -y @aarwitz/tapp@latest validate .tapp/flows/smoke.yml
npx -y @aarwitz/tapp@latest run .tapp/flows/smoke.yml     # Flows, Tasks, contracts, and Scenarios all replay with `run`

Flow は $TEST_EMAIL／$TEST_PASSWORD を使うアトミックな login ステップに対応しています。 Tapp のセッションレコーダーは、認証情報の値をリポジトリに書き込まずにこのステップを作成します。

任意ですが、推奨します（テストハーネスを事前ビルドするため、初回の実行が速くなります）。

npx -y @aarwitz/tapp@latest doctor --install   # ~2 min, one time
npx -y @aarwitz/tapp@latest doctor             # verify Xcode / simulators / toolchain

MCP の接続（任意）

MCP サーバーは CLI ではできない 2 つの機能を追加します。エージェントのコンテキスト内に表示される スクリーンショット（モデルが画面を実際に確認できます）と、インタラクティブなセッションループ （タップ → ツリーを読み取る → 入力。操作の合間もアプリは開いたままです）です。

Claude Code：

claude mcp add tapp -- npx -y @aarwitz/tapp@latest mcp

Cursor／VS Code（Copilot） — ~/.cursor/mcp.json（Cursor）または .vscode/mcp.json（VS Code）に追加します。

{
  "servers": {
    "tapp": { "type": "stdio", "command": "npx", "args": ["-y", "@aarwitz/tapp@latest", "mcp"] }
  }
}

Codex CLI — ~/.codex/config.toml に追加します。

[mcp_servers.tapp]
command = "npx"
args = ["-y", "@aarwitz/tapp@latest", "mcp"]

その他の MCP クライアント： stdio コマンド npx -y @aarwitz/tapp@latest mcp。

次のようにエージェントに依頼します。

「アプリを探索して、何が壊れるか見せてください。」 「シミュレーターで com.mycompany.app を開き、ホーム画面のスクリーンショットを撮ってください。」 「[email protected] でログインし、チェックアウトまで操作して、再生可能なテストとして記録してください。」

エージェントが利用できる機能

	ツール	機能
👁	tapp_look	画面を見る — 現在の実際の画面を、画面の概要とインラインのスクリーンショットで確認します。tree:true を指定すると、アクセシビリティツリー（ID、ラベル、操作可能かどうか）が追加されます。数秒で完了します。
🕹	tapp_session	インタラクティブな操作 — action:"start" で開始し、続けて tap/type/swipe/back/wait/login を実行します（各操作で最新のツリーが返されます）。最後に "end" で終了します。save_flow は操作手順を再生可能な Flow として保存し、draft_flow は目標に基づいて Flow を提案します。
🔭	tapp_explore	自律的な探索 — 作成済みのテストを使わずに探索し、観測結果 {kind, headline, inconclusive, findingCounts, findings[]} を返します（判定やスコアはありません。判定は決定論的なゲートが行います）。readOnly:true はクリックを行いません（本番環境や所有していないサイト向けです）。goal:"…" は名前で指定された画面のソース上の位置を特定し、観測された最短経路をたどります。appBundleId（iOS）、androidAppId（Android）、または url（Web）を受け取ります。
🧭	tapp_init	リポジトリのインポート — 対象を検出し、必要に応じて実際の画面を探索して、共有 UI Map を永続化し、証拠に基づいて分類されたモデルと、根拠のあるリリース計画を構築します。
✅	tapp_plan	リリース計画のライフサイクル — show、review（承認／却下／保留）、generate、実際の対象を使った validate、明示的な promote、PR 対応の pr／adopt、および actor の設定（ロールと環境変数名のみを扱い、認証情報の値は扱いません）。テストを暗黙に編集することはありません。
🔁	tapp_run / tapp_validate	決定論的な再生 — 確定済みの Flow、再利用可能な Task、ビジネスレベルのコントラクト、または複数のアクターが関わる Scenario を実行または検証します。種別はファイルから取得します。再生時に AI は使われません。
🚦	tapp_ci	ベースラインと CI の設定 — 対象に限定したベースラインを保存するか、CLI と同じ、確認可能で対象に対応したワークフローを出力してインストールします。
🗺️	tapp_map	永続的な UI Map — 観測された状態、コントロール、遷移、来歴、カバレッジを構築、確認、統合、差分比較します。
📱	tapp_build	ビルドとシミュレーターの管理 — build、install、list_simulators、boot を実行します。最初にバンドル ID がわからなくても iOS アプリをビルドできます。
🩺	tapp_doctor / tapp_report / tapp_feedback	ツールチェーンの確認、このプロジェクトのキャプチャ履歴と証拠の確認、Tapp 自体に関する問題の報告を行います。

標準のインストール可能なスキル：skills/tapp/SKILL.md。ツールの低レベルな詳細を網羅したリファレンス：AGENTS.md。どちらも npm パッケージに含まれています。Claude プラグインまたは Agent Skill をインストールすると、指示を貼り付けなくてもワークフローを見つけられるようになります。 アプリケーションモデルとインポートの仕様： docs/application-model.md。 デスクトップの Coverage ビューは、同じ .tapp/application-model.json、 .tapp/release-plan.json、.tapp/ui-map.json を読み込み、提案の明示的なレビューにも対応します。個別のプロダクトモデルは保持しません。Map ノードは、実際の起動エントリーポイントと、変更箇所を対象にした範囲限定の再生に使う、プラットフォームごとの決定論的なナビゲーションルートの両方を識別します。

読み取れる観察、信頼できる判定

探索は観察し、ゲートは判定します。 探索は適応的であり、2回の実行で異なる経路をたどることがあります。探索が生成するのは観察結果であり、リリース可否の判定ではありません。内容は、検出事項＋カバレッジ＋証拠です。ゲートは決定論的です。同じ証拠トレース、コントラクト、ベースラインであれば、LLMを判定ループに含めず、常に同じ結果（pass、fail、またはinconclusive）を生成します。PRのゲート判定では、ベースラインに対するリグレッション差分（安定した検出事項のシグネチャ）を基準にするため、実行ごとの経路のばらつきではなく、変更された内容に反応します。重要なユーザージャーニーについては、コミット済みのタスクとフローが安定したCIスイートになります。再利用可能なセマンティックアクション、厳密なアサーション、条件ベースの待機、初期状態からの新規起動、上限時間、失敗時の証拠を備えています。これを「フレーク耐性がある」と表現しますが、魔法のようにフレークがなくなるわけではありません。バックエンドの停止、不安定なテストデータ、識別が不十分なコントロールがあれば、どのE2Eテストも失敗する可能性があります。

スコアも、曖昧な判定もありません。 探索が報告するのは、決定論的な検出事項、助言を目的とした予算上限付きのコントロールプローブ、具体的なカバレッジです。浅いクロールでは正直に得られない、0～100の数値や「準備完了／リリース可能」というラベルは付けません。マージの判定は、レビュー済みコントラクト、コミット済みのフロー／シナリオ、ベースラインに対するリグレッションだけに基づきます。

tapp_exploreはユーザーのように探索します。iOS／Androidではアクセシビリティのサーフェスを、Webでは実際のブラウザーを使い、クラッシュ、サインインの失敗、反応しないボタン、読み込みが止まった画面、エラー表示、ナビゲーションループ、行き止まりを検出します（さらにWebでは、捕捉されないJS例外、失敗または5xxのリクエスト、壊れたリンクやアセット、リンク先のないプレースホルダーリンクの表示も検出します）。観察結果では、その限界も正直に示します。

• 検出事項を提示しますが、「準備完了」とは判定しません。浅い実行が合格になることはありません。アプリの起動時にクラッシュした場合や、ログイン画面によって探索が妨げられた場合は、誤った合格判定ではなく、inconclusive: trueが返されます。検出事項がないことは、合格を意味しません。
• ゲートは、検出事項＋カバレッジ＋レビュー済みコントラクト＋ベースラインをpass／fail／inconclusiveに変換します（inconclusiveは安全側に倒して不合格になります）。決定論的であり、実行ループにLLMは含まれません。
• 探索的クロールでは、コンテンツや主張の正確性、プライバシーとAPIデータの最小化、ブランド／SEOの一貫性、主観的な視覚的信頼性を明示的に対象外とします。これらの確認には、レビュー済みコントラクト、プライバシーレビュー、人間または視覚による判断が必要です。クロールによって検証済みであるかのような印象を与えてはなりません。

「すべてのコーチが保険に加入している」といった事業上の保証には、不変条件が満たされた場合にのみ成功を返す、アプリが所有する決定論的な検証エンドポイントを使用してください。そのうえで、リリースコントラクトにそのステータスと、顧客に表示される主張の両方を必須として指定します。現行のDSLでは、任意のJSONレスポンス本文を読み取ったり、クロスオリジンAPIのペイロードをページ上の文言と直接比較したりすることはまだできません。探索によって保証を推測できると見なさず、検証エンドポイントまたは明示的なCIの事前チェックを使用してください。

ログインが必要なアプリの場合は、testEmail／testPassword（ログインフォームに自動入力されます）、appLaunchArgs（アプリがバイパスに対応している場合は、例：["--uitesting"]）、またはカスタムログインUI向けの明示的なloginStepsを渡してください。

CI ゲート

同じエンジンがマージゲートとしても動作します。すべての PR で探索し、コミット済みのリリースコントラクト、Flows、複数アクターの Scenarios を再生して、最後に結論が出たデフォルトブランチの実行結果と検出結果を比較し、リグレッションがあれば失敗し、固定表示される PR コメントを投稿して、スクリーンショット、録画、機械可読な JSON をアップロードします。

# .github/workflows/tapp.yml
name: Tapp release gate
on:
  pull_request:
  push:
    branches: [main] # refreshes the automatic baseline after merges

permissions:
  actions: read
  contents: read
  pull-requests: write

concurrency:
  group: tapp-${{ github.ref }}
  cancel-in-progress: true

jobs:
  tapp:
    runs-on: macos-15
    timeout-minutes: 45
    steps:
      - uses: actions/checkout@v4
      - uses: aarwitz/[email protected] # or pin the reviewed release commit SHA
        with:
          project: MyApp.xcodeproj # or MyApp.xcworkspace
          scheme: MyApp

プルリクエストでは、Action が GitHub から変更されたファイル一式を自動的に読み込み、名前変更されたファイルについては旧パスと新パスを保持します。critical／policy.always のコントラクトを常に実行し、レビュー済みのソース所有権、UI Map、推移的な Task 構成を通じて関連するコントラクトを追加し、スキップされたコントラクトとカバレッジの不足を tapp-pr-plan.json に記録します。選択されたコントラクトが実行されなかった場合、マージはブロックされます。意図的にすべてのコントラクトを実行する場合に限り、pr-selection: "false" を設定してください。

カバレッジが不十分な変更箇所は、直接の Web URL だけではありません。レビュー済みの Task ソース所有権により、観測された UI Map のエッジを通じて、条件待ちと安定したターゲット証拠を伴うネイティブターゲットを最大 1 つ（または Web ターゲットを最大 5 つ）コンパイルできます。ターゲットが見つからない場合や失敗した場合、実行結果は結論なしとなります。Tapp は画面名からパスを推測しません。

最初に成功し、結論が出た main での実行では、リポジトリスコープの Actions キャッシュと 90 日間のベースラインアーティファクトが生成されます。どちらもプラットフォームと安定したアプリケーションモデルのターゲット ID をキーとして使用します。プルリクエストでは自動的にこれらを復元し、新たな重大／高リスクの検出結果、または破損した Flows がある場合にのみ失敗します。ベースラインのコミットも PAT も必要ありません。レビュー済みで長期保存できるベースラインが必要な場合は、tapp ci baseline を実行して生成された .tapp/baselines/<platform>/<target-id>.json をコミットしてください。tapp ci install を実行すると、対応するジョブにその明示的なパスが設定されます。従来の .tapp/baseline.json も引き続き認識されます。ベースラインの自動復元と PR コメントには、上記のとおり actions: read と pull-requests: write が必要です。フォークからのワークフローではシークレットを利用できないため、認証が必要なアプリでは、シークレットを使わない UI テスト用の起動引数を使うか、信頼できないフォークではゲートをスキップしてください。

別のジョブですでにシミュレーターアプリをビルドしている場合や、別の CI プロバイダーを使用する場合はどうすればよいでしょうか。このポータブルコマンドは、その .app を受け取り、バンドル ID を検出して、レポートアーティファクトを書き込み、ゲートに失敗すると 0 以外の終了コードを返します。

npx -y @aarwitz/tapp@latest ci --app path/to/MyApp.app \
  --project-dir . --pr-base origin/main --pr-head HEAD \
  --target-key target_ios_myapp \
  --pr-plan-out tapp-pr-plan.json \
  --baseline path/to/last-main-report.json \
  --json-out tapp-report.json --md-out tapp-report.md

Flows、認証入力、その他の制御については、セルフテスト .github/workflows/tapp-gate-example.yml を参照してください。GitHub ホステッドの iOS 実行には macOS ランナーが必要です。最初の実行では XCUITest ハーネスもビルドするため、アプリのサイズに応じて 5～10 分ほどを見込んでください。

Android CI は、エミュレーターまたはデバイスがすでに接続された Linux 上で実行されます。Action は APK をビルドすることも、ビルド済みの APK を受け取ることもできます。

- uses: aarwitz/[email protected] # or pin the reviewed release commit SHA
  with:
    platform: android
    android-app-id: com.acme.app
    android-project: android
    android-task: :app:assembleDebug
    flows: android/.tapp/flows/*.yml

Web の場合は、platform: web と web-target: を渡すと、Tapp はアプリケーションモデルを使ってロックファイルに基づくインストール／ビルドを実行し、検出したパッケージスクリプトまたは読み取り専用の静的サーバーを起動して、準備完了を待ち、ゲートを実行し、失敗時も含めて停止します。すでに稼働中の管理対象環境を使う場合は、代わりに url: を渡してください。独立したアカウント間のジャーニーをゲートするには、scenarios: .tapp/scenarios/*.yml を追加してください。詳しくは docs/scenarios.md を参照してください。自動ベースラインはプラットフォームとターゲットごとに分離されるため、同じプラットフォーム上の 2 つのアプリが比較されることはありません。

リポジトリをエージェント検証済みにする

これをリポジトリの AGENTS.md（Codex、Cursor、Copilot、Devin、Zed などが読み込みます）に追加すると、エージェントが UI の作業を完了したと主張するだけでなく、その証拠を示すようになります。

## Verifying UI changes
This repo uses tapp (https://github.com/aarwitz/tapp) to verify UI work on a real app surface
(iOS simulator, Android emulator/device, or a browser for web). After any UI change, run `npx -y @aarwitz/tapp@latest look` from the
repo root (it finds and builds the Xcode project itself) and look at the screenshot it saves as
proof. Before declaring a feature done, run `npx -y @aarwitz/tapp@latest explore` (or `explore <url>` for web)
and report the findings + evidence. A change is not "done" until it has been seen working.
(If the tapp MCP server is connected, the tapp_* tools do the same with inline screenshots —
tapp_build builds + installs the app and returns the bundle id for tapp_explore.)

仕組み

すべてのドライバーは、ひとつのプロトコルを使用します。構造化された OCQA_* マーカー（状態、アクション、問題、遷移）をエンジンが解析し、ツリー、スクリーンショット、検出結果、カバレッジ、ゲートの結果に変換します。iOS では、汎用の XCUITest ハーネスがバンドル ID を使って任意のアプリに接続します。SDK もアプリコードの変更も不要で、アクセシビリティツリーを介して操作します。Android では、ADB と UIAutomator が同じブラックボックス型ドライバーの契約を提供します。Web では、決定論的な Playwright クローラーが実際のブラウザーで同じ処理を行います。同じ検出の考え方、同じ重複排除、同じリグレッションゲート、そして pass／fail／inconclusive という正確な結果を得られます。中核となる探索、エビデンスの収集、ゲートの評価はすべてローカルで実行されます。テレメトリーも、外部へのデータ送信もありません。AI 機能は明示的に有効化します。検出結果の拡充には TAPP_ENABLE_REMOTE_AI=1 が必要です（環境に API キーがあるだけでデータの取り扱いが変わることはありません）。また、AI フロー生成と assert_ai は、呼び出した場合にのみ実行されます。これらは、選択されたメタデータ（画面名、検出結果のタイトル）を、設定済みのモデルプロバイダーに送信します。実行時の設定には TAPP_* 環境変数を使用します。リポジトリのアーティファクトは .tapp/ に保存され、デスクトップ実行の設定には .tapp.yml を使用します。Tapp が読み取る名前はこれらだけです。名称変更前の .autotap/、.autotap.yml、AUTOTAP_* の入力は、すでにサポートされていません。古いディレクトリや設定が残っている場合は、レビュー済みの変更で .tapp の名前に変更してください。シークレットやエビデンスの形式を書き換える必要はありません。

コミット済みの Flow の再生、操作したセッションの記録、自律的な探索、厳密なアサーション、リグレッション比較、CI ゲートには、API キーも実行時のコーディングエージェントも不要です。AI は任意の作成／拡充レイヤーに限られます（tapp_session {action:"draft_flow"}、assert_ai、検出結果の拡充）。

最初のツール呼び出しでハーネスが一度だけビルドされます（約 2 分、~/.tapp にキャッシュされます。シミュレーターを切り替えた場合は自動的に再ビルドされます）。すべてのキャプチャは ~/.tapp/captures/ に保存されます。

フィードバック

Tapp は、エージェントが普段使っている方法でフィードバックを受け付けます。aarwitz/tapp の GitHub issue として送信できます。tapp feedback "short title" --body "…"（または tapp_feedback MCP ツール）を実行すると、バージョン、プラットフォームの利用可否、最新のキャプチャ ID を入力し、ホームディレクトリのパスとトークンを伏せた issue の下書きが作成されます。--submit を指定すると、認証済みの gh を使って issue を作成します。issue は公開されるため、下書きの作成がデフォルトです。エージェントは最初に下書きを提示する必要があります。自動でアップロードされるものはありません。キャプチャはお使いのマシンに保存されたままです。

ライセンス

MIT