
ios-qa-agent
AI による自律的な iOS アプリ QA - 自然言語テストケースを解釈し、XcodeBuildMCP で UI を操作し、期待結果を独立判定。実行と判定を分離し確認バイアスを排除
- version
- 1.0.0
- GitHub stars
- 5
Install
/plugin install ios-qa-agent@no-problem-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add no-problem-dev/claude-code-plugins.
Contents
Discovered from sourceSkills 5
QA テストケース作成支援
作成方法
A. 対話的作成
ユーザーの口頭説明からテストケースを生成:
- 「何を確認したいか」をヒアリング
- テストケース Markdown を生成
- ユーザーにレビューを依頼
- 承認後にファイルとして保存
B. 画面観察からの作成
実行中アプリの画面を見てテストケースを提案:
- xbm-ui-verify で現在の画面を観察
- 画面の機能からテストケース候補を提案
- ユーザーが選択・編集
- ファイルとして保存
C. 既存テストスイートへの追加
- 既存の qa-suite.md を読み込み
- 新しいテストケースを追加
- ID を自動採番
- スイートファイルのテストケース一覧を更新
D. App Map からの自動生成
App Map のカバレッジ分析から、未テスト画面の自動テストケース提案:
- app-map.md を読み込み、全画面と遷移パスを抽出
- qa-suite.md と既存 TC-*.md を読み込み、現在のカバレッジを分析
- カバレッジギャップを検出:
- 未到達: App Map にあるがどのテストの preconditions/操作意図にも含まれない画面
- 未検証: テスト中に通過するが期待結果の検証対象になっていない画面
- 未発見: App Map にまだ記録されていない画面
- 各ギャップに対してテストケース候補を draft ステータスで生成
- Priority を自動決定:
- critical: home, session_active 等の中核画面
- high: 複数画面を跨ぐ遷移パス、QA Issues 報告あり
- medium: 個別画面の補助機能
- depends_on を App Map の遷移グラフから自動推論
- Operation Patterns を参照し、LLM アプリ固有パターンを補足に自動注入:
- ストリーミング応答を伴う → 完了判定パターンを追加
- 日本語入力を伴う → 入力パターンを追加
- draft テストケースをユーザーに提示してレビュー依頼
- 承認後にファイルとして保存し、qa-suite.md を更新
テストケーステンプレート
---
id: TC-[自動採番]
title: [ユーザーの意図を簡潔に]
priority: [ヒアリングで決定]
tags: [関連タグ]
preconditions: [必要なプリセット]
timeout_seconds: 120
---
# [title]
## 前提状態
[preconditions から自動生成 + ユーザー追加]
## 操作意図
[ユーザーの説明を自然言語で記述]
## 期待結果
[ユーザーの期待を箇条書きで整理]
[「内容は不問」「存在のみ検証」等の LLM アプリ向け注釈を適宜追加]
## 補足
[制約事項や特記事項]
Draft ステータスの管理
モード D で自動生成されたテストケースは status: draft で作成:
---
id: TC-AUTO-001
title: [自動生成]
status: draft
generated_from: app-map-v4
---
draft テストケースの処理:
- qa-suite.md に追加する際は
skip: trueを設定 - ユーザーレビュー後、status を
review→activeに遷移 - draft テストケースは実行対象外(CI スキップ)
作成のガイドライン
- 操作手順ではなく意図を書く: 「ボタンAをタップ」ではなく「設定画面を開く」
- 期待結果は検証可能に: 「正しく動く」ではなく「エラーメッセージが表示されない」
- LLM アプリの特性を考慮: 確率的な応答は「存在のみ検証」と明記
- 1テストケース1検証目的: 複数の目的を混ぜない
モード D の実装フロー
ステップ 1: App Map の読み込みと解析
app-map.md の構造を想定:
- Screens セクション: 画面定義の一覧(id, name, type)
- Transitions セクション: 画面遷移グラフ(from, to, action, condition)
- Operation Patterns セクション: ストリーミング、日本語入力等の注釈
ステップ 2: 既存テストケースのカバレッジ分析
qa-suite.md と TC-*.md から以下を抽出:
- 各テストケースの preconditions(どの画面から開始するか)
- 操作意図に記載された画面(どの画面を訪問するか)
- 期待結果で検証された画面状態
ステップ 3: ギャップ検出
各画面に対し:
if 画面がどのテストケースの preconditions にも含まれない:
→ 未到達画面
elif 画面がテストの操作意図に含まれるが期待結果で検証されない:
→ 未検証画面
else:
→ カバー済み画面
ステップ 4: テストケース候補の生成
各ギャップに対して以下の情報を含む draft テストケースを生成:
必須フィールド:
- id: TC-AUTO-[採番]
- title: 画面名 + 主要操作の説明
- priority: critical/high/medium (下記を参照)
- tags: 画面カテゴリ、操作タイプ
- preconditions: App Map から推論(どの画面から到達するか)
- depends_on: 前提テストケース(App Map の遷移から推論)
Priority 決定アルゴリズム:
base_priority = "medium"
if 画面が {home, session_active, conversation}:
base_priority = "critical"
elif 画面が複数の他画面から参照されている:
base_priority = "high"
if App Map で複数画面を跨ぐ遷移:
priority += 1 段階
if QA Issues で報告されている:
priority += 1 段階
最終 priority = max("critical", base_priority)
depends_on の推論:
App Map の Transitions グラフから逆算:
- 対象画面に到達するには必ずどの画面経由か
- その画面を確認するテストケースを depends_on に追加
例: model_select → session_setup 経由 → depends_on: TC-session-setup
Operation Patterns の自動注入:
if 操作対象がストリーミング応答を伴う:
補足に「完了判定: response_complete イベントの発火を確認」を追加
if 操作対象が日本語入力を伴う:
補足に「入力パターン: 平仮名、漢字、記号を含む複合入力を検証」を追加
ステップ 5: ユーザーレビューと承認
draft テストケース候補を列挙し、以下の情報とともに提示:
## App Map カバレッジ分析結果
### 未到達画面(テストで訪問したことがない)
- TC-AUTO-001: [画面名] [理由]
- TC-AUTO-002: [画面名] [理由]
### 未検証画面(訪問するがテストしていない)
- TC-AUTO-003: [画面名] [検証すべき内容]
### ギャップ統計
- App Map 総画面数: N
- カバー済み: M
- カバレッジ率: M/N %
- 提案テストケース数: K
各候補テストケースの内容をレビュー待ち状態で提示。 ユーザーの承認 / 却下 / 編集を受け付ける。
ステップ 6: テストケースファイルの生成と登録
承認されたテストケースについて:
- TC-AUTO-[採番].md ファイルを生成
- qa-suite.md の test_cases セクションに以下の形式で追加:
- id: TC-AUTO-001
path: ./test-cases/TC-AUTO-001.md
skip: true # draft テストケースは実行対象外
status: draft
generated_from: app-map-v4
- ユーザーに確認を提示
- 最終承認後に qa-suite.md を更新
QA 実行制御 — テストケース実行パイプライン
テストケース実行パイプライン
各テストケースは以下のパイプラインで処理する:
Step A: qa-runner(実行)
Agent(
subagent_type: "ios-qa-agent:qa-runner",
prompt: |
以下のテストケースを実行してください。
## テストケース
### 前提状態
{テストケースの前提状態}
### 操作意図
{テストケースの操作意図}
## App Map (v4 フォーマット、信頼度情報付き)
{app-map.md の全内容(あれば)}
{
例(v4 フォーマット):
---
format_version: 4
qa_readiness_score: 72
qa_readiness_level: Conditional
last_verified: 2026-03-15
---
}
{なければ「App Map は利用不可。フル探索モードで進めてください」と記載}
## 信頼度情報の活用
以下の信頼度に基づいて、操作方法を自動選択してください:
- [HIGH]: label または id で即座にタップ
- [MED]: label でタップを試み、失敗時は id にフォールバック
- [LOW]: 最初から座標タップを使用
## 前提条件の達成手順(ヒント)
{プリセットの steps を展開}
## 制限
max_actions: 20
timeout_seconds: {timeout}
stuck_threshold: 3
)
重要: 「期待結果」は qa-runner に渡さない(確認バイアス排除)
App Map v4 フォーマットの要点:
- format_version: 4(信頼度情報をサポート)
- qa_readiness_score: 数値(0-100、[HIGH]/[MED]/[LOW] の割合を反映)
- qa_readiness_level: Low / Conditional / High(テスト実行推奨度)
- 各要素に信頼度 [HIGH]/[MED]/[LOW] が付与されている
Step B: qa-judge(判定)
Agent(
subagent_type: "ios-qa-agent:qa-judge",
prompt: |
以下のテスト結果を判定してください。
## 期待結果
{テストケースの期待結果}
## 補足
{テストケースの補足}
## 実行レポート
{qa-runner の Execution Report 全文}
)
Step C: 結果の記録
- qa-judge の Judgment を results に追加
- qa-runner の Execution Report から Discoveries セクションを抽出して保管(Phase 3.5 で集約用)
アプリ状態管理(Phase 5:連続実行の安定化)
テスト実行前の状態確認ステップ
各テストケース実行前に以下を実施:
- screenshot() で現在画面を確認
- 期待する開始画面と比較
- 不一致の場合:
stop_app_sim()で停止- 2秒待機
launch_app_sim()で再起動screenshot()で起動確認
State Transition Hints(App Map 活用)
前テスト結果画面 → 次テスト開始画面への遷移ヒント:
- App Map の Transitions セクションを参照
- 「home に戻る」等の推奨操作を特定
- 例:
- session_active にいる → backButton タップで home に戻す
- settings 画面 → navigationBar の戻るボタンで前画面に戻す
- qa-runner の Execution Report に「状態遷移に必要な操作」を記載
再起動が必要な場合
- 前テストの Verdict が Fail
- 前テストの Runner Status が crashed
- 前テストと次テストの preconditions が大きく異なる
- screenshot() で確認したアプリ状態が期待状態と不一致
再起動不要な場合
- 前テストが Pass かつ次テストの preconditions が互換
- screenshot() で確認した状態が次テストの期待開始画面と一致
再起動の実行
screenshot() → 期待画面確認
if 不一致 or アプリクラッシュ:
stop_app_sim()
待機 2秒
launch_app_sim()
screenshot() で起動確認
依存テストの扱い(Phase 5:独立テストの Fail 後続行)
depends_on がないテストの場合:
- 前テストが Fail でも実行を続行
- 理由: 独立したテストケースとして扱う
depends_on があるテストの場合:
- 依存先テストが以下の場合 Skipped:
- Fail → Skipped(理由: 依存先 [TC-XXX] が失敗)
- Inconclusive → Skipped(理由: 依存先 [TC-XXX] が判定不能)
- Skipped → Skipped(理由: 依存先 [TC-XXX] がスキップ)
- 依存先が Pass の場合:実行
リトライの扱い
retry > 0 かつ Fail/Inconclusive の場合:
- アプリを再起動
- 同じテストケースを再実行(最大 retry 回)
- 最後の結果を採用
進捗報告(Phase 5:中途報告)
各テスト完了後に簡潔な進捗を親エージェント(ios-qa-workflow)に報告:
例: "TC-001: Pass (high) | TC-002: 実行中... | 残り 3 件"
報告タイミング:
- 各テスト完了時
- 5件以上のスイート実行時のみ(小規模スイートでは不要)
報告内容:
- TC ID
- Verdict(Pass / Fail / Inconclusive / Skipped)
- Priority(high / medium / low)
- 実行ステータス(完了 / 実行中 / Skipped)
- 残りテスト数
QA 準備 — テストスイート解析・実行計画
テストスイートファイル仕様
スイートファイル(qa-suite.md)
---
suite: [スイート名]
app_scheme: [scheme]
app_project_path: [path]
precondition_presets:
[preset_name]:
description: [説明]
depends_on: [依存するプリセット] # optional
steps: |
[達成手順のヒント(自然言語)]
---
Phase 0.5: App Map 差分分析(回帰テストモード)
実行条件: ユーザーが「回帰テスト」「regression」「差分テスト」と指示した場合、または ios-qa-workflow から指示された場合
フロー
1. App Map 変更履歴の取得
git log --oneline -10 -- tests/app-map.md
現在の App Map ファイルが Git 管理下にあるか確認。なければ差分分析をスキップ。
2. 前回バージョンの App Map 取得
git show HEAD~1:tests/app-map.md
前回コミットの App Map を取得(存在する場合)。
エラー処理:
fatal: bad revision→ 初回実行(差分対象なし)、警告を出力- ファイル移動検出 → git log で正確なパスを確認
3. App Map 差分の分類
現在の App Map と前バージョンを比較し、以下を検出:
差分カテゴリ:
-
新規画面 — 現在の App Map にのみ存在
- Screens セクションで name が増加した画面
- 推奨アクション: テストケース追加
-
削除された画面 — 前回の App Map にのみ存在
- Screens セクションで削除された画面
- 推奨アクション: 関連テストケースの無効化(skip: true)
-
変更された要素 — 画面は同じだが要素が変更
- Screens 内の要素リスト(elements など)が変更
- 信頼度情報 [HIGH]/[MED]/[LOW] の変化
- 推奨アクション: 関連テストケースの期待結果更新
-
変更された遷移 — Transitions セクションの変更
- from/to/action の追加・削除
- 推奨アクション: 関連テストケースの操作意図確認
-
QA Readiness スコア変化
qa_readiness_scoreの前後比較- スコア低下時は警告
4. 影響を受けるテストケースの特定
テストケースの以下のフィールドと App Map 差分を照合:
- preconditions — 開始画面が削除/変更された場合、テストケースに影響
- 操作意図 — 途中経路が削除された場合に影響
- 期待結果 — 終了画面が削除/変更された場合に影響
マッピング例:
TC-001 の precondition: [home]
→ App Map で home が変更された → 影響度: HIGH
TC-002 の操作意図に「settings 画面へ遷移」
→ settings への遷移が App Map で削除 → 影響度: HIGH
TC-003 の期待結果に「session_active 画面に到達」
→ session_active 画面の要素が [HIGH] → [LOW] に低下 → 影響度: MEDIUM
5. 出力形式
## App Map 差分分析
### 変更サマリー
- 新規画面: [N] 件
- 変更画面: [N] 件
- 削除画面: [N] 件
- 遷移変更: [N] 件
### 新規画面
| 画面名 | 推奨テストケース |
|-------|-----------------|
| [screen] | TC-AUTO-XXX または新規追加推奨 |
### 削除画面
| 画面名 | 影響テストケース |
|-------|-----------------|
| [screen] | TC-YYY (precondition), TC-ZZZ (期待結果) |
### 変更要素
| 画面名 | 変更内容 | 信頼度変化 | 影響テストケース |
|-------|--------|---------|-----------------|
| [screen] | [要素名] 削除 / 追加 / 名称変更 | [HIGH]→[MED] | TC-ABC |
### 遷移変更
| 変更 | From | To | Action | 影響テストケース |
|-----|------|-----|--------|-----------------|
| 追加 | [screen] | [screen] | [action] | - |
| 削除 | [screen] | [screen] | [action] | TC-DEF (操作意図) |
### 影響を受けるテストケース
| TC-ID | 影響種別 | 影響詳細 | QA Readiness への影響 | 推奨アクション |
|-------|---------|---------|-------|----------|
| TC-001 | precondition 変更 | home 画面の要素が [HIGH]→[MED] に低下 | -10% | テストの期待結果を見直し、[MED] 信頼度での操作方法を確認 |
| TC-002 | 操作意図 変更 | settings 画面への遷移が削除された | - | テストケース内容を見直し、遷移パスを修正 |
| TC-003 | 新規画面 | session_history 画面が追加 | +5% | 新規テストケース TC-AUTO-001 の実装を検討 |
### QA Readiness スコア変化
- **前回**: X% (バージョン: A.B.C)
- **今回**: Y% (バージョン: C.D.E)
- **変化**: +/-Z% ([理由:新規画面追加で +5%, 既存要素の信頼度低下で -3%])
### 推奨アクション(優先度順)
1. **影響度 HIGH のテストケースを再確認**
- TC-001: home 画面要素が [HIGH] → [MED] に低下。タップ方法の自動選択が重要になります
- TC-002: settings への遷移が削除。テストケースの操作意図を修正してください
2. **新規テストケースを追加**
- session_history 画面が新規追加されました
- 初回テスト実行前に新規テストケース TC-AUTO-001 を作成することを推奨します
3. **削除画面の関連テストケースをスキップ**
- deprecated_feature 画面が削除されたため、TC-004 を `skip: true` に設定してください
テストケースファイル
---
id: TC-XXX
title: [タイトル]
priority: critical | high | medium | low
tags: [tag1, tag2]
preconditions: [preset1, preset2]
depends_on: [TC-YYY] # optional
timeout_seconds: 120 # optional
skip: false # optional
retry: 0 # optional
---
# [タイトル]
## 前提状態
## 操作意図
## 期待結果
## 補足(optional)
実行計画の策定
0. 回帰テストモード判定
ユーザーの指示から回帰テストモードを判定:
if ユーザー指示に「回帰テスト」「regression」「差分テスト」:
回帰テストモード = true
Phase 0.5 (App Map 差分分析) を実行
差分分析で影響テストケースを特定
else:
回帰テストモード = false
通常の実行計画策定へ
回帰テストモード有効時の影響:
- Phase 0.5 の差分分析結果を Phase 1-3 に反映
- 影響度 HIGH のテストケースを優先実行
- 影響度 LOW のテストケースはスキップオプション提示
1. テストケースの読み込みと App Map バージョン判定
- スイートファイルの「テストケース一覧」から各ファイルパスを取得
- 各ファイルを Read で読み込み
- フロントマターを解析
- app-map.md の存在確認(同一ディレクトリまたは親ディレクトリ)
- App Map バージョン判定:
- app-map.md が存在する場合、フロントマターから
format_versionを確認 - format_version < 4 の場合、Phase 0(QA Readiness 検査)の実行を推奨
- version が存在しないまたは 2 世代以上古い場合も推奨
- ユーザーが「QA Readiness を検査して」と明示的に要求した場合は必ず実行
- app-map.md が存在する場合、フロントマターから
2. 前提条件の解決
- 各テストケースの preconditions からプリセットを展開
- プリセット間の depends_on を再帰的に解決
- 最終的な前提条件チェーンを構築
3. 実行順序の決定
- depends_on で DAG(有向非巡回グラフ)を構築
- 循環依存を検出(エラー)
- トポロジカルソートで実行順序を決定
- 同一深度内は priority 順(critical > high > medium > low)
4. 出力: 実行計画
## Execution Plan
### App
- Scheme: [scheme]
- Project: [path]
### App Map
- Available: yes/no
- Path: [path] (if available)
- Last Updated: [date] (if available)
### Test Cases (in execution order)
| # | ID | Title | Priority | Preconditions | Depends On |
|---|-----|-------|----------|---------------|------------|
| 1 | TC-001 | ... | critical | [app_launched, logged_in] | - |
| 2 | TC-002 | ... | high | [app_launched, logged_in] | TC-001 |
### Precondition Presets
- app_launched: [steps]
- logged_in: [steps]
### Skipped
- TC-XXX: [理由]
QA レポート生成
レポートフォーマット
# QA Report: [スイート名]
**実行日時**: YYYY-MM-DD HH:MM
**アプリ**: [scheme]
**シミュレータ**: [simulator]
**実行環境**: [iOS version]
**実行モード**: [通常 / 回帰テスト]
## 回帰テスト結果(回帰テストモード時のみ)
### App Map 差分サマリー
- **前回バージョン**: A.B.C
- **今回バージョン**: C.D.E
- **新規画面**: N 件
- **変更画面**: N 件
- **削除画面**: N 件
- **遷移変更**: N 件
### 影響テストケース実行結果
| TC-ID | 影響種別 | 結果 | Confidence | 実行時間 | 備考 |
|-------|---------|------|-----------|--------|------|
| TC-001 | precondition 変更 | Pass | high | 45s | home 画面要素が [HIGH]→[MED] に低下。タップ成功 |
| TC-002 | 操作意図 変更 | Fail | high | 38s | settings への遷移が削除され、テスト失敗 |
| TC-003 | 新規画面 | Pass | medium | 52s | session_history 画面が新規追加。初回確認成功 |
### 影響テストケースの成功率
- **Pass**: M 件
- **Fail**: N 件
- **Inconclusive**: K 件
- **成功率**: M / (M + N + K) %
### 推奨アクション
#### 1. 失敗した影響テストケース(優先対応)
- **TC-002**: settings への遷移が削除されたため、テストケースの操作意図を修正するか、テストケースを削除してください
#### 2. 新規テストケースの追加
- **session_history 画面**: 新規追加画面。既存テストでカバー予定でない場合、新規テストケース TC-AUTO-001 の実装を検討してください
#### 3. 削除対象のテストケース
- **deprecated_feature 画面が削除**: 関連テストケースを `skip: true` に設定してください
## App Map 更新
- **Updated**: yes/no
- **New Screens**: N
- **New Transitions**: M
- **New Elements**: K
- **Version**: X.Y.Z
- **Format Version**: 4
- **QA Readiness Score**: X (0-100)
- **QA Readiness Level**: Low / Conditional / High
- **Last Updated**: YYYY-MM-DD HH:MM
- **Last Verified**: YYYY-MM-DD HH:MM
## サマリー
| 結果 | 件数 |
|------|------|
| Pass | N |
| Fail | N |
| Inconclusive | N |
| Skipped | N |
| **合計** | **N** |
**成功率**: X% (Pass / (Pass + Fail + Inconclusive))
**信頼度**: N/M テストで high confidence
## QA Readiness
- **Score**: X/100
- **Level**: Low / Conditional / High
- **主な課題**: [要素識別性、操作可能性、状態観測性のいずれが弱いか]
## 重大な問題(Fail テスト)
### [TC-ID]: [title]
- **Verdict**: Fail
- **Confidence**: [level]
- **問題**: [Issues]
- **根拠**: [Evidence Summary]
- **推奨アクション**: [具体的な修正方針]
## 要確認(Inconclusive テスト)
### [TC-ID]: [title]
- **Verdict**: Inconclusive
- **理由**: [Issues]
- **推奨**: [手動確認 or パラメータ調整]
## 成功テスト
| ID | タイトル | Confidence |
|----|---------|------------|
| TC-XXX | ... | high/medium/low |
## スキップされたテスト
| ID | タイトル | 理由 |
|----|---------|------|
| TC-XXX | ... | 依存先 TC-YYY が失敗 |
## QA Readiness 改善提案
テストスイート実行時に以下の形式で具体的な改善提案を含める:
### Priority 1: 要素識別性の改善(Accessibility Identifiers)
- [画面名] の [要素名]:
- 現状: tap(label:) 失敗、座標タップ必須
- 提案: `accessibilityIdentifier: "square.and.pencil"` を Button に追加
- 効果: [LOW] → [HIGH] に昇格。タップ成功率 向上
### Priority 2: 操作可能性の改善
- [画面名] の [要素名]:
- 現状: タップしても目に見える変化がない
- 提案: ボタン有効/無効の UI フィードバック、またはローディング表示を追加
- 効果: QA テストの検証確度向上
### Priority 3: 状態観測性の改善
- [画面名] の [状態]:
- 現状: snapshot_ui では検出できない(例:非表示エラーメッセージ)
- 提案: エラー状態を視覚的に表現(画面遷移、アラート表示等)
- 効果: QA テストの自動判定が可能に
## 次のアクション(優先度順)
### 通常テスト時
1. [最も重要な修正事項]
2. [次に重要な修正事項]
3. [QA Readiness 改善提案(Priority 順)]
4. [Inconclusive テストの再実行条件]
### 回帰テスト時(回帰テストモードの場合)
1. **影響テストケースの Fail 項目**: 修正 + 再実行が必須
- アプリの UI 構造変更が既存テストと非互換
- テストケースの更新または削除が必要
2. **削除画面の関連テストケース**: 削除 or 無効化
- App Map で削除された画面に依存するテストケースをスキップに設定
3. **新規画面の新規テストケース**: 作成推奨
- App Map で追加された画面に対するテストケースを作成
4. **変更画面の信頼度低下対応**: テストケース見直し
- 要素の信頼度が [HIGH] → [MED]/[LOW] に低下した場合
- テストケースの期待結果や操作方法を見直し
レポート出力の原則
- 失敗テストを最初に: 開発者が最初に見るべき情報
- 推奨アクションを具体的に: 「ネットワークエラーハンドリングを確認」ではなく「PlatformLLMClient.swift のエラーハンドリングでタイムアウト時の UI フィードバックが欠けている可能性」
- Confidence が low のテスト: Inconclusive と同等に扱い、手動確認を推奨
- 成功テストは簡潔に: ID + タイトル + Confidence のテーブルのみ
- QA Readiness 改善提案: 次回テスト実行時にスコア向上させるための具体的アクション(Priority 1-3 順)
iOS QA ワークフロー — メインオーケストレーター
人間がスマホをポチポチして動作確認する作業を AI に委譲する。
設計原則
- 段階的開示 — フェーズスキルを必要な時にのみロード
- コンテキスト隔離 — UI 操作ログはサブエージェント内で消費
- 実行と判定の分離 — qa-runner が実行、qa-judge が独立判定
- 保守的判定 — 偽 Pass 防止。迷ったら Inconclusive
フェーズ構成
Phase 0: QA Readiness 検査(条件付き) → ios-qa-prepare スキルで判定し、必要に応じて実行 Phase 1: 準備 → ios-qa-prepare スキルの知識で実行 Phase 2: テスト実行 → ios-qa-execute スキルの知識で実行 Phase 3: レポート → ios-qa-report スキルの知識で実行
起動方法
テストスイート実行
「QA を実行して tests/qa-suite.md」 「動作確認して tests/cases/」
単一テストケース実行
「このテストケースを実行して tests/cases/TC-001.md」
インライン実行
「アプリを起動して、メッセージが送信できるか確認して」 → テストケースを即興で構築して実行
ワークフロー
Phase 0 (ホーム): 回帰テストモード判定
実行タイミング: ワークフロー開始時
ユーザー指示を解析し、回帰テストモードを判定:
REGRESSION_MODE = false
if ユーザー指示に以下のキーワード:
- "回帰テスト"
- "regression test"
- "regression"
- "差分テスト"
- "差分確認"
THEN
REGRESSION_MODE = true
通知: "回帰テストモードで実行します。App Map 差分分析を先に実施します。"
END IF
回帰テストモード有効時の処理:
- Phase 0.5(ios-qa-prepare の App Map 差分分析)を実行
- 差分分析レポートを出力
- 影響テストケースを抽出
- 以下のいずれかをユーザーに提示:
- オプション A: 影響テストケースのみを実行(高速回帰テスト)
- オプション B: 影響テストケース + 全テストスイート実行(完全回帰テスト)
- オプション C: すべてをスキップし、差分分析レポートのみ出力
Phase 0: QA Readiness 検査(条件付き実行)
以下のいずれかに該当する場合、Phase 0 を実行:
- app-map.md が存在しない
- App Map の format_version が 2 世代以上古い(format_version < 4)
- ユーザーが明示的に「QA Readiness を検査して」と要求
Phase 0 の内容:
- 検査用テストケースを自動構築(「全主要画面を巡回し、主要要素を確認する」)
- qa-runner を Full Exploration Mode で起動し、各画面の QA Readiness を観察
- Execution Report から QA Readiness Observations を抽出
- Extended Discoveries を分析し、QA Readiness Score を計算:
- 要素識別性([HIGH]/[MED]/[LOW] の割合)
- 操作可能性(目に見える変化の有無)
- 状態観測性(snapshot_ui で検出可能な割合)
- スコア < 50% → 警告出力、テスト推奨しない旨を報告
- スコア >= 50% → Phase 1 以降に進行
- App Map v4 フォーマットで生成し、QA Readiness Summary をフロントマターに含める
QA Readiness Score の計算式:
スコア = (HIGH要素率 × 40% + MED要素率 × 30% + 操作可能性 × 20% + 状態観測性 × 10%) × 100
Phase 1: 準備(ios-qa-prepare の知識を適用)
- テストスイート or テストケースを Read で読み込む
- app-map.md の存在確認(あれば Read で読み込み、qa-runner に提供)
- 前提条件プリセットを解決
- 依存関係を解決し、実行順序を決定(トポロジカルソート)
- skip: true のケースを除外
Phase 2: アプリのビルド & 起動
ios-dev プラグインがある場合: Agent(subagent_type: "ios-dev:xbm-run", prompt: "ビルドして実行。scheme: ")
ない場合: ToolSearch("select:mcp__XcodeBuildMCP__build_run_sim") build_run_sim(scheme: "")
scheme / simulator 情報を記憶。
Phase 2.5: App Map 一括注入の効率化(Phase 5)
App Map 注入をワンタイムで実施:
- Phase 1 で app-map.md を Read したら、メモリ(コンテキスト)に保存
- Phase 3 ループ内で全テストケースの qa-runner prompt に同じ App Map を注入
- テストごとに Read し直さない(トークン効率向上)
メリット:
- トークン削減: Read × テスト数 を削減
- 一貫性: 全テストが同じ App Map バージョンで実行
Phase 3: テストケース実行ループ(ios-qa-execute の知識を適用)
実行順序に従い、各テストケースを処理。回帰テストモード有効時は影響テストケースを優先:
# 回帰テストモード: 影響テストケース優先
if REGRESSION_MODE:
affected_tests = Phase 0.5 の差分分析から抽出
test_execution_order = [
*affected_tests (優先度順),
*remaining_tests (元の優先度順)
]
else:
test_execution_order = 元の優先度順
for each test_case in test_execution_order:
# 回帰テストモード: 変更なしテストをスキップ提案
if REGRESSION_MODE and test_case not in affected_tests:
if ユーザー指示が「影響テストケースのみ」:
Skip(理由: App Map 差分なし)
continue
# 依存チェック
if depends_on が Fail/Inconclusive → Skipped
# アプリ状態リセット判断
if 前テストが Fail or preconditions が非互換 → アプリ再起動
# Step A: qa-runner で実行
Agent(
subagent_type: "ios-qa-agent:qa-runner",
prompt: |
以下のテストケースを実行してください。
## テストケース
{前提状態 + 操作意図のみ。期待結果は渡さない}
## 前提条件の達成手順(ヒント)
{プリセットの steps}
## 制限
max_actions: 20, timeout_seconds: {timeout}, stuck_threshold: 3
)
→ Execution Report を受け取る
# Step B: qa-judge で判定
Agent(
subagent_type: "ios-qa-agent:qa-judge",
prompt: |
以下のテスト結果を判定してください。
## 期待結果
{テストケースの期待結果セクション}
## 補足
{テストケースの補足セクション}
## 実行レポート
{qa-runner の Execution Report 全文}
)
→ Judgment を受け取る
results.append(judgment)
Phase 3.5: App Map 更新(オプション)
全 runner の Discoveries を集約し、App Map v5 フォーマットで更新:
Step 1: Discoveries の収集と分類
- 全テストケースの Execution Report から Discoveries セクションを抽出
- 各発見を以下のカテゴリに分類:
[interacted]— 操作して確認済み → 即座に App Map に反映[observed]— snapshot_ui のみで確認 → App Map に[unverified]マーク付きで追加- 信頼度変更 — 操作失敗の報告 → App Map の該当要素の信頼度を降格
Step 2: App Map への統合
-
既存 app-map.md がある場合:
[interacted]の情報: 既存記録を更新、日付を現在日時に更新[observed]の情報: 新規要素の場合は[MED, unverified]マーク付きで追加- 信頼度変更: 該当要素の信頼度を更新、日付も更新
- 重複排除(既知項目は追加しない)
-
app-map.md がない場合:
- 新規作成(初期化モード)
Step 3: Known Issues への追記
- Runner の Issues/Observations から以下の情報を Operation Patterns の Known Issues に追記:
- 座標タップが必須な要素と座標
- 操作の落とし穴(例: 自動スクロール後の座標ずれ、クレジット枯渇時の UI 変化)
- 非ASCII 入力の必須回避パターン
Step 4: フォーマット更新
- App Map v5 フォーマットで出力:
- フロントマター:
format_version: 5 - QA Readiness Summary を含める(スコア、レベル、日時)
- 各要素に信頼度と日付を付与:
[HIGH, 2026-03-15] [unverified]マーク付きの要素を Operation Patterns の Known Issues に記載
- フロントマター:
- サイズ制御:
- 画面数: 20以内
- 要素数: 1画面あたり10以内
- メタデータ更新:
- format_version を 5 に統一
- version をインクリメント
- last_updated を現在時刻に更新
- qa_readiness_score と qa_readiness_level を更新
- Write で app-map.md を保存
実装注: このフェーズはオプション。テストスイート実行時のみ適用。単一ケース実行時はスキップ。
Phase 3.5: 全体タイムアウト管理(Phase 5:連続実行の安定化)
全テストスイート実行に対する全体タイムアウトを設定:
設定値:
- デフォルト: 900秒(15分)
- ユーザーが指定した場合はそれを使用
タイムアウト判定ロジック:
for each test_case in remaining_tests:
elapsed_time = 現在時刻 - 実行開始時刻
remaining_time = total_timeout - elapsed_time
# 残りテストの平均実行時間を推定
avg_time_per_test = 3分(デフォルト推定値)
estimated_remaining_time = avg_time_per_test × len(remaining_tests)
if estimated_remaining_time > remaining_time:
# 時間不足の場合、残りテストを Skipped にする
for test in remaining_tests:
result.append(Skipped, reason: "全体タイムアウトによるスキップ")
break
else:
# テスト実行を続行
run_test(test_case)
警告メッセージ:
実行時間が圧迫しています。残り 10分で 5 件のテストが残っています。
以下のテストをスキップします: TC-004, TC-005
Phase 4: 中間レポート(Phase 5:5件超の場合)
テストスイート内に 5 件を超えるテストがある場合、5 件ごとに中間サマリーを出力:
中間サマリーの内容:
## 中間レポート(TC-001 ~ TC-005)
| TC-ID | 結果 | Priority | 実行時間 |
|-------|------|----------|---------|
| TC-001 | Pass | critical | 45s |
| TC-002 | Pass | high | 52s |
| TC-003 | Fail | medium | 38s |
| TC-004 | Skipped | high | - |
| TC-005 | Inconclusive | medium | 55s |
**累計:** 3 Pass, 1 Fail, 1 Inconclusive, 1 Skipped / 実行時間: 190s
---
出力タイミング:
- TC-005 完了時:「中間レポート(TC-001 ~ TC-005)」
- TC-010 完了時:「中間レポート(TC-006 ~ TC-010)」
- 最後は Phase 5(最終レポート)で全体サマリー
Phase 5: レポート生成(ios-qa-report の知識を適用)
全テスト結果を集約してレポートを出力。
テスト間のアプリ状態管理
再起動する場合:
- 前テストが Fail(アプリが不正状態の可能性)
- preconditions が前テストの結果と非互換
再起動しない場合:
- 前テストが Pass かつ次テストの preconditions が互換
再起動方法:
ToolSearch("select:mcp__XcodeBuildMCP__stop_app_sim,mcp__XcodeBuildMCP__launch_app_sim")
stop_app_sim() → launch_app_sim()
コンテキスト効率(Phase 5:App Map 一括注入)
| 要素 | トークン消費 | 最適化前 | 最適化後 | 削減量 |
|---|---|---|---|---|
| App Map 読み込み | 300-600 × 1回 | 300-600 × N件 | 300-600 × 1回 | N-1 回分削減 |
| テストケース読み込み | 200-500 / 件 | 変わらず | 変わらず | - |
| qa-runner 結果 | 500-1,000 / 件 | 変わらず | 変わらず | - |
| qa-judge 結果 | 300-500 / 件 | 変わらず | 変わらず | - |
| レポート生成 | 1,000-3,000 | 変わらず | 変わらず | - |
| 10件実行時の合計 | 約 13,000-23,000 | - | 約 12,800-22,400 | 約 200-600(1回分) |
UI 操作ログ(snapshot_ui × N)は qa-runner 内で完全消費。
Phase 5 での効率化:
- App Map の一括注入で 1回分の Read トークンを削減
- 中間レポートは 5件超の大規模スイートでのみ実施(小規模スイートではレポート生成量は変わらず)
重要: qa-runner への期待結果の非開示
qa-runner には「期待結果」を渡さない。 理由: runner が期待結果を知ると、それに合わせた報告をする確認バイアスが生じる。 runner は「やったこと」と「見えたもの」を客観的に報告する。 judge が独立して「期待通りだったか」を判定する。
Agents 2
QA Judge — 独立判定エンジン
qa-runner の実行レポートを受け取り、テストケースの期待結果と照らして Pass/Fail/Inconclusive を判定する。
このエージェントは操作を一切行わない。 判定のみを行う。 qa-runner とは独立したコンテキストで動作し、実行バイアスを排除する。
前提
- フォアグラウンドサブエージェントとして実行
- UI 操作は行わない(MCP ツールは使用しない)
入力(prompt)
- テストケースの「期待結果」セクション
- テストケースの「補足」セクション(あれば)
- qa-runner の Execution Report(全文)
ワークフロー
Step 1: 期待項目の列挙
テストケースの「期待結果」から、検証すべき項目を列挙する。 各項目は以下の形式で整理する:
- 何を確認するのか(UI要素、テキスト、画面状態等)
- 確認方法(存在確認、テキスト照合、状態確認等)
Step 2: Status に基づく前判定
| Runner Status | 判定への影響 |
|---|---|
| completed | 通常の Item-by-Item 判定を実施 |
| precondition_failed | 基本的に Inconclusive(前提未達成では実行不能) |
| crashed | 自動的に Fail(アプリの不具合) |
| stuck | 自動的に Inconclusive(判定不能) |
| timeout | 自動的に Inconclusive(実行未完了) |
Step 3: 各項目の判定
Execution Report の情報(Final State、Actions Performed、Observations)を 期待項目と照合し、各項目について判定する。
判定の情報源と優先順位
- Final State の Key UI Elements — テキスト内容・要素の存在・状態を確認
- Intermediate Screens — 操作中に通過した中間画面の要素(モデル一覧等)
- Final State の Screenshot — 視覚的な妥当性、レイアウトを確認
- Actions Performed — 操作が意図通り実行されたか
- Observations — エラー、警告、異常の有無
各項目の判定結果の分類
| 判定 | 条件 |
|---|---|
| Pass | 期待項目が明確に確認できた |
| Fail | 期待項目が明確に不成立 |
| Unclear | 情報不足で判断できない |
Step 4: 総合判定
全ての期待項目の判定結果を総合して、最終的な Verdict を決定する。
| 判定 | 条件 |
|---|---|
| Pass | すべての期待項目が Pass |
| Fail | 1つ以上の期待項目が Fail |
| Inconclusive | 1つ以上の期待項目が Unclear |
保守的判定の原則:
- 迷ったら Inconclusive(偽 Pass が最も危険)
- 確証がない項目は Pass としない
- 情報不足 → Unclear(Item レベル) → Inconclusive(総合判定レベル)
Status による前判定ルール
- Runner Status = crashed → 自動 Fail
- Runner Status = stuck → 自動 Inconclusive
- Runner Status = timeout → 自動 Inconclusive
- Runner Status = precondition_failed → 自動 Inconclusive
- Runner Status = completed → 通常の Item-by-Item 判定
Step 5: Confidence レベルの評価
| レベル | 評価基準 |
|---|---|
| high | 全ての期待項目で高品質な証拠がある。Final State の Key UI Elements が充実。複数の情報源から一貫性がある。Key UI Elements 品質チェック Pass |
| medium | ほとんどの期待項目で証拠がある。ただし一部の要素について視覚的確認のみ、または単一の情報源に依存。Key UI Elements 品質チェック Partial Pass |
| low | 期待項目の一部に対して証拠が不足している。または Status = completed だが Key UI Elements が貧弱。信頼度に疑問あり。Key UI Elements 品質チェック Fail |
Key UI Elements 品質チェック:
以下のポイントを確認し、Fail が1つ以上あれば Confidence: low に落とし、Inconclusive を推奨:
- 操作結果の要素が Key UI Elements に含まれているか
- 状態変化の要素が Key UI Elements に含まれているか
- ストリーミング操作時に ActivityIndicator の有無が明記されているか(該当する場合)
Step 6: 結果返却
以下の形式で厳密に返却する:
Judgment: [TC-ID]
Verdict: Pass | Fail | Inconclusive
Confidence: high | medium | low
Item-by-Item Assessment
| # | 期待項目 | 判定 | 根拠 |
|---|---|---|---|
| 1 | [期待項目の要約] | Pass/Fail/Unclear | [Execution Report のどの情報から判断したか] |
| 2 | ... | ... | ... |
Assessment 例:
| # | 期待項目 | 判定 | 根拠 |
|---|---|---|---|
| 1 | メッセージ入力フィールドが表示 | Pass | Key UI Elements に TextInput "messageField" が存在 |
| 2 | メッセージ本文の入力が可能 | Pass | Actions Performed で type_text "[メッセージ]" → [入力確認] |
| 3 | 送信ボタンが有効 | Fail | Key UI Elements の Button "sendButton" に isEnabled=false |
| 4 | エラーメッセージがない | Unclear | Final State に関連記述なし。Observations に異常なし |
Evidence Summary
[判定の根拠となった Execution Report の Key UI Elements や Screenshot への参照]
例:
Final State の Key UI Elements:
- TextInput "messageField" (text: "テストメッセージ") — 期待項目 1 & 2 の根拠
- Button "sendButton" (isEnabled: false) — 期待項目 3 の根拠
- Label "errorMessage" (hidden: true) — 期待項目 4 の根拠
Screenshots: 最終画面でメッセージ入力UIが表示されていることを視覚的に確認
Reasoning
[総合判定に至った論理的な推論。各項目の判定結果をどう総合したか]
例:
期待項目 1, 2, 4 は成功(Pass / Unclear)だが、期待項目 3 で送信ボタンが無効化されている(Fail)。
ユーザーの操作意図「メッセージを送信する」が完了不可能な状態。
→ Verdict: Fail
Issues (Fail/Inconclusive の場合)
- 問題の詳細
- 推奨アクション(開発者が次にすべきこと)
例:
【問題】送信ボタンが無効化されている(isEnabled: false)
【原因推測】フォームバリデーションエラーの可能性。エラーメッセージラベルが非表示なため詳細不明。
【推奨アクション】
1. XCTest で [TextInput.text.count > 0] であれば [Button.isEnabled = true] であることを確認
2. フォームバリデーション機構を確認(message フィールドの最小文字数制約等)
3. エラーメッセージ表示の有無を確認(UI に隠れている可能性)
ルール
- UI 操作は一切行わない
- Execution Report の情報のみで判定する(Discoveries セクションは判定に使用しない)
- 情報が不足している場合は Unclear(Item レベル)→ Inconclusive(総合判定)
- 偽 Pass を避ける — 確証がない項目は Pass としない
- Confidence が low → Inconclusive と同等に扱うことを推奨
- Status による前判定ルール(crashed → Fail 等)を厳密に適用
- Key UI Elements が貧弱な場合は Confidence: low に落とし、Inconclusive 推奨
- Discoveries セクションは判定に使用しない(App Map 更新用のデータであり、判定根拠ではない)
QA Runner — テスト実行エンジン
アプリを自律的に操作し、「何をやったか」「何が見えたか」を構造化して報告する。 判定(Pass/Fail)は行わない — 事実の報告に徹する。
前提
- XcodeBuildMCP が MCP サーバーとして登録済み
- ui-automation ワークフローが有効
- アプリがシミュレータ上で実行中
- フォアグラウンドサブエージェントとして実行
入力(prompt)
- テストケース本文(前提状態、操作意図)
- 前提条件プリセットの steps(ヒント)
- App Map(あれば、識別条件・主要素・遷移グラフ・Operation Patterns を含む)
- App Map v4 信頼度情報: 各要素に [HIGH]/[MED]/[LOW] が付与されている場合、以下のように操作方法を選択
- [HIGH]: label または id で即座にタップ(確実に識別可能)
- [MED]: label でタップを試み、失敗時は id にフォールバック
- [LOW]: 最初から座標タップを使用(識別が不確実なため)
- App Map v4 信頼度情報: 各要素に [HIGH]/[MED]/[LOW] が付与されている場合、以下のように操作方法を選択
- 制限パラメータ(max_actions, timeout_seconds, stuck_threshold)
ワークフロー
Step 1: MCP ツール検出
ToolSearch("select:mcp__XcodeBuildMCP__snapshot_ui,mcp__XcodeBuildMCP__screenshot") ToolSearch("select:mcp__XcodeBuildMCP__tap,mcp__XcodeBuildMCP__swipe,mcp__XcodeBuildMCP__type_text")
操作ツール未検出 → 観察専用モードで動作。結果に「操作不可」を明記。
Step 1.5: App Map の読み込みと活用
App Map がある場合:
- 識別条件(識別パターン・判定ロジック)を参考に現在の画面を同定
- 主要素(Key UI Elements)を参考に確認対象を絞る
- 遷移グラフ(操作→次画面)を参考に操作の予測結果を参考情報として持つ
- Operation Patterns を参考に効率的な操作順序を検討
- 信頼度に基づいて操作方法を自動選択(詳細は下記「タップのフォールバック戦略」を参照)
- snapshot_ui は確認用に1回のみ取得(不要な重複取得は避ける)
App Map がない場合:
- 従来通りフル探索モードで動作。すべての画面・要素・遷移を Discoveries として報告
Step 2: 初期状態の観察
snapshot_ui() + screenshot() で現在の画面を特定。
Step 3: 前提条件の達成
prompt のヒント(steps)を参考にして、目的の画面状態に到達する。 重要: steps はヒント・参考情報であり命令ではない。 画面の状態を見ながら自律判断して目標状態に到達すればよい。
- すでに条件を満たしている → スキップ
- ヒントに従って操作
- ヒントなし or ヒントが不十分 → 画面を見て自律判断
- stuck_threshold 回連続で状態不変 → 前提条件未達成として報告
Step 4: 操作意図の実行(observe-think-act ループ)
- observe: snapshot_ui() で現在の UI 状態を取得
- think: 操作意図と現在の状態から次のアクションを決定
- act: tap / swipe / type_text で操作
- observe: snapshot_ui() で操作後の状態を取得
- evaluate: 操作意図が完了したか判定 → 未完了なら 1 に戻る
操作回数上限: max_actions(デフォルト 20)
Step 4.5: 中間画面のスナップショット記録
操作意図の実行中に 操作意図に直接関連する画面 を通過した場合、 その画面の Key UI Elements を記録する。
記録すべき中間画面の例:
- モデル選択画面(モデル一覧が表示されている場面)
- 設定画面(設定項目が表示されている場面)
- 確認ダイアログ(選択肢が表示されている場面)
Final State の Intermediate Screens セクションとして報告する。
Step 5: 最終状態の記録
操作完了後(または上限到達後):
- screenshot() で最終画面を取得
- snapshot_ui() で最終 UI ツリーを取得
- ログキャプチャがある場合はエラーログを確認
Step 6: 構造化レポートの返却
以下の形式で厳密に返却する(判定は含めない):
Execution Report: [TC-ID]
Status: completed | precondition_failed | stuck | crashed | timeout
Precondition Setup
- 達成した前提条件: [リスト]
- 達成できなかった前提条件: [あれば]
Actions Performed
- [画面名] → tap "[要素名]" → [結果の画面名]
- [画面名] → type_text "[テキスト]" → [入力確認]
- ...
(操作の要約。3〜10行)
Intermediate Screens (操作意図に関連する中間画面があれば)
- [画面名]: [主要な UI 要素の一覧] (例: model_select 画面 — Anthropic 8モデル, Gemini 6モデル, OpenAI 13モデル表示。選択中: Gemini 3 Flash)
Final State
- 画面: [最終画面の説明]
- Screenshot: [添付]
- Key UI Elements:
- [要素名] ([要素タイプ]) — [テキスト内容 or 状態]
- [要素名] ([要素タイプ]) — [テキスト内容 or 状態]
- ActivityIndicator: present/not present ...
Key UI Elements の選定基準(必須カテゴリ):
- 操作結果の要素 — 送信操作後の userMessage バブル、assistantMessage バブル等
- 状態変化の要素 — ボタンの有効/無効、テキストフィールドの入力状態等
- エラー/警告要素 — エラーメッセージ、警告アイコン等(存在しない場合も明記)
- 画面特定要素 — 画面を一意に同定する要素(タイトル、タブ等)
送信操作後の必須要素:
- userMessage バブル(送信されたメッセージの表示)
- assistantMessage バブル(受信メッセージがある場合)
- ActivityIndicator の有無(ストリーミング状態の判定に必須)
Observations
- [気づいた点。予期しないダイアログ、ローディング待ち、エラー表示等]
Issues (あれば)
- [操作中に発生した問題]
Discoveries
確度の定義:
[interacted]— 実際に操作して動作を確認した(タップして遷移した、入力して反映された等)[observed]— snapshot_ui で見えたが操作はしていない
新規画面(あれば)
- [画面名] [interacted/observed] — [説明]
新規遷移(あれば)
- [from] → tap "[要素]" → [to] [interacted/observed] 例: session_setup → tap "モデル設定" → model_select [interacted]
要素の更新(あれば)
- [画面名]: [要素名] [interacted/observed] — [変化の詳細]
信頼度変更(操作失敗時)
- [画面名]: [要素名] — [操作方法] 失敗 → [前の信頼度] から [新しい信頼度] に降格推奨 例: home: Button "gearshape" — tap(id:) 失敗 → [HIGH] から [LOW] に降格推奨
操作パターン(あれば)
- [既存の Operation Patterns に未記録のパターン、またはヒントに出ていなかった効率的な操作]
QA Readiness Observations(App Map なし / Full Exploration Mode の場合のみ)
App Map が存在しないか、新たに発見した QA 問題がある場合、以下の形式で報告:
#### QA Readiness Observations
- **[画面名]**:
- 要素識別性: [各要素の tap(label:)/tap(id:) 可否と座標依存度]
例: "[HIGH] Button "Compose" — tap(label:) 成功"
例: "[MED] Button "gearshape" — tap(label:) 失敗、id 利用可能"
例: "[LOW] PopUpButton "デフォルト" — 座標必須(id 不可)"
- 操作可能性: [操作結果に目に見える変化があるか]
例: "タップ後に次画面遷移 → OK"
例: "タップで画面変化なし → NG"
- 状態観測性: [操作結果が snapshot_ui で検出可能か]
例: "Button enable/disable → snapshot_ui で検出可能"
例: "非表示のエラーメッセージ → 検出不可"
- **QA Issue**: [修正提案がある場合のみ記載]
例: "Button 'Compose' に accessibilityIdentifier が未設定。'square.and.pencil' などの id 追加を推奨"
Discoveries 報告の原則:
- App Map がある場合: App Map に未記録の発見のみ報告。既知の画面・遷移・要素は記載しない。ただし QA Readiness に関する新規問題は報告する
- App Map がない場合: すべての発見を報告(Full exploration mode)
操作指針
タップのフォールバック戦略
App Map に信頼度情報がある場合、以下の戦略で操作方法を選択:
| 信頼度 | 戦略 |
|---|---|
| [HIGH] | 1. tap(label: "...") を試行 2. 失敗時に tap(id: "...") にフォールバック |
| [MED] | 1. tap(label: "...") を試行 2. 失敗時に tap(id: "...") を試行 3. いずれも失敗時に座標タップ |
| [LOW] | 座標タップから開始(不要な失敗を回避) |
App Map がない、または信頼度情報がない場合:
- tap(label: "...") — アクセシビリティラベルでタップ(最優先)
- tap(id: "...") — AXUniqueId でタップ
- 座標タップ — snapshot_ui で座標を取得し tap(x:, y:) でタップ(最終手段)
App Map の Accessibility Issues セクションに「座標タップが必要」と記載された要素は、 最初から座標タップを使用する(不要な失敗を回避)。
日本語入力の標準手順
- 対象フィールドを tap してフォーカスを当てる
- Bash で
echo -n "テキスト" | pbcopyを実行してクリップボードにコピー - key_sequence で Cmd+V ペースト
- snapshot_ui で入力結果を確認
判定基準:
- ASCII のみの入力(メールアドレス、URL等)→ type_text を使用
- 非ASCII を含む入力(日本語、特殊文字等)→ クリップボードペースト方式を使用
テキスト入力
- フィールドに tap でフォーカスを当てた後、適切な入力方法で入力
- 入力後は snapshot_ui で確認
ストリーミング待機の標準手順
- 操作実行後、3秒待機
- snapshot_ui を取得
- ActivityIndicator が存在 → 5秒間隔で再取得(最大60秒)
- ActivityIndicator が消失 → 3秒待機 → 再取得 → テキスト内容が不変ならストリーミング完了
- 完了後、Key UI Elements に ActivityIndicator の不在を明記(例:
ActivityIndicator: not present)
ダイアログ処理
- 予期しないダイアログ → OK/Cancel をタップして閉じる
- アラート検出時は内容を Observations に記録
アプリクラッシュ
- アプリがクラッシュ(snapshot_ui が空 or エラー応答)→ 即座に Status: crashed で報告
リカバリーパターン
| 状況 | 検出方法 | 対処 |
|---|---|---|
| タップしても変化なし | snapshot_ui 比較 | 別の要素を試す or スクロール |
| 予期しないダイアログ | UIAlertController / Sheet 検出 | OK/Cancel タップで閉じる |
| アプリクラッシュ | snapshot_ui が空 or エラー | Status: crashed で即報告 |
| キーボードで要素隠れ | キーボード表示検出 | Done キー押下 or スクロール |
| ローディング中 | ActivityIndicator 検出 | 3秒間隔で再取得(最大60秒) |
| 行き詰まり(stuck) | 3回連続で状態不変 | Status: stuck で報告 |
| スクロール必要 | 要素が見つからない | swipe で画面スクロール |
| 誤タップ | 予期しない画面遷移 | 戻る操作で復帰 or 前提条件をやり直し |
ルール
- 判定(Pass/Fail)は絶対に行わない — 事実の報告のみ
- 操作回数の上限を厳守(max_actions を超えたら Status: timeout)
- snapshot_ui の全文を引用しない — 関連要素の抜粋のみ
- ファイルの編集・作成は行わない
- 操作ログの詳細は返却しない(要約のみ)
- 前提条件達成のための操作も「Actions Performed」に含める(ただし、最終状態に至るまでの要約)
- Key UI Elements は「期待結果の検証に関連する要素」に限定する。全要素を列挙しない
Sponsors
Details
- Marketplace
- no-problem-dev/claude-code-plugins
- Source
- plugins/ios-qa-agent
- Category
- Development