AI による自律的な iOS アプリ QA - 自然言語テストケースを解釈し、XcodeBuildMCP で UI を操作し、期待結果を独立判定。実行と判定を分離し確認バイアスを排除

version
1.0.0
GitHub stars
5

Install

/plugin install ios-qa-agent@no-problem-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add no-problem-dev/claude-code-plugins.

Contents

Discovered from source

Skills 5

QA テストケース作成支援

作成方法

A. 対話的作成

ユーザーの口頭説明からテストケースを生成:

  1. 「何を確認したいか」をヒアリング
  2. テストケース Markdown を生成
  3. ユーザーにレビューを依頼
  4. 承認後にファイルとして保存

B. 画面観察からの作成

実行中アプリの画面を見てテストケースを提案:

  1. xbm-ui-verify で現在の画面を観察
  2. 画面の機能からテストケース候補を提案
  3. ユーザーが選択・編集
  4. ファイルとして保存

C. 既存テストスイートへの追加

  1. 既存の qa-suite.md を読み込み
  2. 新しいテストケースを追加
  3. ID を自動採番
  4. スイートファイルのテストケース一覧を更新

D. App Map からの自動生成

App Map のカバレッジ分析から、未テスト画面の自動テストケース提案:

  1. app-map.md を読み込み、全画面と遷移パスを抽出
  2. qa-suite.md と既存 TC-*.md を読み込み、現在のカバレッジを分析
  3. カバレッジギャップを検出:
    • 未到達: App Map にあるがどのテストの preconditions/操作意図にも含まれない画面
    • 未検証: テスト中に通過するが期待結果の検証対象になっていない画面
    • 未発見: App Map にまだ記録されていない画面
  4. 各ギャップに対してテストケース候補を draft ステータスで生成
  5. Priority を自動決定:
    • critical: home, session_active 等の中核画面
    • high: 複数画面を跨ぐ遷移パス、QA Issues 報告あり
    • medium: 個別画面の補助機能
  6. depends_on を App Map の遷移グラフから自動推論
  7. Operation Patterns を参照し、LLM アプリ固有パターンを補足に自動注入:
    • ストリーミング応答を伴う → 完了判定パターンを追加
    • 日本語入力を伴う → 入力パターンを追加
  8. draft テストケースをユーザーに提示してレビュー依頼
  9. 承認後にファイルとして保存し、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 スキップ)

作成のガイドライン

  1. 操作手順ではなく意図を書く: 「ボタンAをタップ」ではなく「設定画面を開く」
  2. 期待結果は検証可能に: 「正しく動く」ではなく「エラーメッセージが表示されない」
  3. LLM アプリの特性を考慮: 確率的な応答は「存在のみ検証」と明記
  4. 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: テストケースファイルの生成と登録

承認されたテストケースについて:

  1. TC-AUTO-[採番].md ファイルを生成
  2. 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
  1. ユーザーに確認を提示
  2. 最終承認後に 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: 結果の記録

  1. qa-judge の Judgment を results に追加
  2. qa-runner の Execution Report から Discoveries セクションを抽出して保管(Phase 3.5 で集約用)

アプリ状態管理(Phase 5:連続実行の安定化)

テスト実行前の状態確認ステップ

各テストケース実行前に以下を実施:

  1. screenshot() で現在画面を確認
  2. 期待する開始画面と比較
  3. 不一致の場合:
    • stop_app_sim() で停止
    • 2秒待機
    • launch_app_sim() で再起動
    • screenshot() で起動確認

State Transition Hints(App Map 活用)

前テスト結果画面 → 次テスト開始画面への遷移ヒント:

  1. App Map の Transitions セクションを参照
  2. 「home に戻る」等の推奨操作を特定
  3. 例:
    • session_active にいる → backButton タップで home に戻す
    • settings 画面 → navigationBar の戻るボタンで前画面に戻す
  4. 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 と前バージョンを比較し、以下を検出:

差分カテゴリ:

  1. 新規画面 — 現在の App Map にのみ存在

    • Screens セクションで name が増加した画面
    • 推奨アクション: テストケース追加
  2. 削除された画面 — 前回の App Map にのみ存在

    • Screens セクションで削除された画面
    • 推奨アクション: 関連テストケースの無効化(skip: true)
  3. 変更された要素 — 画面は同じだが要素が変更

    • Screens 内の要素リスト(elements など)が変更
    • 信頼度情報 [HIGH]/[MED]/[LOW] の変化
    • 推奨アクション: 関連テストケースの期待結果更新
  4. 変更された遷移 — Transitions セクションの変更

    • from/to/action の追加・削除
    • 推奨アクション: 関連テストケースの操作意図確認
  5. 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 を検査して」と明示的に要求した場合は必ず実行

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] に低下した場合
   - テストケースの期待結果や操作方法を見直し

レポート出力の原則

  1. 失敗テストを最初に: 開発者が最初に見るべき情報
  2. 推奨アクションを具体的に: 「ネットワークエラーハンドリングを確認」ではなく「PlatformLLMClient.swift のエラーハンドリングでタイムアウト時の UI フィードバックが欠けている可能性」
  3. Confidence が low のテスト: Inconclusive と同等に扱い、手動確認を推奨
  4. 成功テストは簡潔に: ID + タイトル + Confidence のテーブルのみ
  5. QA Readiness 改善提案: 次回テスト実行時にスコア向上させるための具体的アクション(Priority 1-3 順)

iOS QA ワークフロー — メインオーケストレーター

人間がスマホをポチポチして動作確認する作業を AI に委譲する。

設計原則

  1. 段階的開示 — フェーズスキルを必要な時にのみロード
  2. コンテキスト隔離 — UI 操作ログはサブエージェント内で消費
  3. 実行と判定の分離 — qa-runner が実行、qa-judge が独立判定
  4. 保守的判定 — 偽 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

回帰テストモード有効時の処理:

  1. Phase 0.5(ios-qa-prepare の App Map 差分分析)を実行
  2. 差分分析レポートを出力
  3. 影響テストケースを抽出
  4. 以下のいずれかをユーザーに提示:
    • オプション A: 影響テストケースのみを実行(高速回帰テスト)
    • オプション B: 影響テストケース + 全テストスイート実行(完全回帰テスト)
    • オプション C: すべてをスキップし、差分分析レポートのみ出力

Phase 0: QA Readiness 検査(条件付き実行)

以下のいずれかに該当する場合、Phase 0 を実行:

  • app-map.md が存在しない
  • App Map の format_version が 2 世代以上古い(format_version < 4)
  • ユーザーが明示的に「QA Readiness を検査して」と要求

Phase 0 の内容:

  1. 検査用テストケースを自動構築(「全主要画面を巡回し、主要要素を確認する」)
  2. qa-runner を Full Exploration Mode で起動し、各画面の QA Readiness を観察
  3. Execution Report から QA Readiness Observations を抽出
  4. Extended Discoveries を分析し、QA Readiness Score を計算:
    • 要素識別性([HIGH]/[MED]/[LOW] の割合)
    • 操作可能性(目に見える変化の有無)
    • 状態観測性(snapshot_ui で検出可能な割合)
  5. スコア < 50% → 警告出力、テスト推奨しない旨を報告
  6. スコア >= 50% → Phase 1 以降に進行
  7. App Map v4 フォーマットで生成し、QA Readiness Summary をフロントマターに含める

QA Readiness Score の計算式:

スコア = (HIGH要素率 × 40% + MED要素率 × 30% + 操作可能性 × 20% + 状態観測性 × 10%) × 100

Phase 1: 準備(ios-qa-prepare の知識を適用)

  1. テストスイート or テストケースを Read で読み込む
  2. app-map.md の存在確認(あれば Read で読み込み、qa-runner に提供)
  3. 前提条件プリセットを解決
  4. 依存関係を解決し、実行順序を決定(トポロジカルソート)
  5. 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 注入をワンタイムで実施:

  1. Phase 1 で app-map.md を Read したら、メモリ(コンテキスト)に保存
  2. Phase 3 ループ内で全テストケースの qa-runner prompt に同じ App Map を注入
  3. テストごとに 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 の収集と分類

  1. 全テストケースの Execution Report から Discoveries セクションを抽出
  2. 各発見を以下のカテゴリに分類:
    • [interacted] — 操作して確認済み → 即座に App Map に反映
    • [observed] — snapshot_ui のみで確認 → App Map に [unverified] マーク付きで追加
    • 信頼度変更 — 操作失敗の報告 → App Map の該当要素の信頼度を降格

Step 2: App Map への統合

  1. 既存 app-map.md がある場合:

    • [interacted] の情報: 既存記録を更新、日付を現在日時に更新
    • [observed] の情報: 新規要素の場合は [MED, unverified] マーク付きで追加
    • 信頼度変更: 該当要素の信頼度を更新、日付も更新
    • 重複排除(既知項目は追加しない)
  2. app-map.md がない場合:

    • 新規作成(初期化モード)

Step 3: Known Issues への追記

  1. Runner の Issues/Observations から以下の情報を Operation Patterns の Known Issues に追記:
    • 座標タップが必須な要素と座標
    • 操作の落とし穴(例: 自動スクロール後の座標ずれ、クレジット枯渇時の UI 変化)
    • 非ASCII 入力の必須回避パターン

Step 4: フォーマット更新

  1. App Map v5 フォーマットで出力:
    • フロントマター: format_version: 5
    • QA Readiness Summary を含める(スコア、レベル、日時)
    • 各要素に信頼度と日付を付与: [HIGH, 2026-03-15]
    • [unverified] マーク付きの要素を Operation Patterns の Known Issues に記載
  2. サイズ制御:
    • 画面数: 20以内
    • 要素数: 1画面あたり10以内
  3. メタデータ更新:
    • format_version を 5 に統一
    • version をインクリメント
    • last_updated を現在時刻に更新
    • qa_readiness_score と qa_readiness_level を更新
  4. 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)を 期待項目と照合し、各項目について判定する。

判定の情報源と優先順位
  1. Final State の Key UI Elements — テキスト内容・要素の存在・状態を確認
  2. Intermediate Screens — 操作中に通過した中間画面の要素(モデル一覧等)
  3. Final State の Screenshot — 視覚的な妥当性、レイアウトを確認
  4. Actions Performed — 操作が意図通り実行されたか
  5. Observations — エラー、警告、異常の有無
各項目の判定結果の分類
判定条件
Pass期待項目が明確に確認できた
Fail期待項目が明確に不成立
Unclear情報不足で判断できない

Step 4: 総合判定

全ての期待項目の判定結果を総合して、最終的な Verdict を決定する。

判定条件
Passすべての期待項目が Pass
Fail1つ以上の期待項目が Fail
Inconclusive1つ以上の期待項目が 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メッセージ入力フィールドが表示PassKey UI Elements に TextInput "messageField" が存在
2メッセージ本文の入力が可能PassActions Performed で type_text "[メッセージ]" → [入力確認]
3送信ボタンが有効FailKey UI Elements の Button "sendButton" に isEnabled=false
4エラーメッセージがないUnclearFinal 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 に隠れている可能性)

ルール

  1. UI 操作は一切行わない
  2. Execution Report の情報のみで判定する(Discoveries セクションは判定に使用しない)
  3. 情報が不足している場合は Unclear(Item レベル)→ Inconclusive(総合判定)
  4. 偽 Pass を避ける — 確証がない項目は Pass としない
  5. Confidence が low → Inconclusive と同等に扱うことを推奨
  6. Status による前判定ルール(crashed → Fail 等)を厳密に適用
  7. Key UI Elements が貧弱な場合は Confidence: low に落とし、Inconclusive 推奨
  8. 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]: 最初から座標タップを使用(識別が不確実なため)
  • 制限パラメータ(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 ループ)

  1. observe: snapshot_ui() で現在の UI 状態を取得
  2. think: 操作意図と現在の状態から次のアクションを決定
  3. act: tap / swipe / type_text で操作
  4. observe: snapshot_ui() で操作後の状態を取得
  5. 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

  1. [画面名] → tap "[要素名]" → [結果の画面名]
  2. [画面名] → type_text "[テキスト]" → [入力確認]
  3. ...

(操作の要約。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 の選定基準(必須カテゴリ):

  1. 操作結果の要素 — 送信操作後の userMessage バブル、assistantMessage バブル等
  2. 状態変化の要素 — ボタンの有効/無効、テキストフィールドの入力状態等
  3. エラー/警告要素 — エラーメッセージ、警告アイコン等(存在しない場合も明記)
  4. 画面特定要素 — 画面を一意に同定する要素(タイトル、タブ等)

送信操作後の必須要素:

  • 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 がない、または信頼度情報がない場合:

  1. tap(label: "...") — アクセシビリティラベルでタップ(最優先)
  2. tap(id: "...") — AXUniqueId でタップ
  3. 座標タップ — snapshot_ui で座標を取得し tap(x:, y:) でタップ(最終手段)

App Map の Accessibility Issues セクションに「座標タップが必要」と記載された要素は、 最初から座標タップを使用する(不要な失敗を回避)。

日本語入力の標準手順

  1. 対象フィールドを tap してフォーカスを当てる
  2. Bash で echo -n "テキスト" | pbcopy を実行してクリップボードにコピー
  3. key_sequence で Cmd+V ペースト
  4. snapshot_ui で入力結果を確認

判定基準:

  • ASCII のみの入力(メールアドレス、URL等)→ type_text を使用
  • 非ASCII を含む入力(日本語、特殊文字等)→ クリップボードペースト方式を使用

テキスト入力

  • フィールドに tap でフォーカスを当てた後、適切な入力方法で入力
  • 入力後は snapshot_ui で確認

ストリーミング待機の標準手順

  1. 操作実行後、3秒待機
  2. snapshot_ui を取得
  3. ActivityIndicator が存在 → 5秒間隔で再取得(最大60秒)
  4. ActivityIndicator が消失 → 3秒待機 → 再取得 → テキスト内容が不変ならストリーミング完了
  5. 完了後、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 前提条件をやり直し

ルール

  1. 判定(Pass/Fail)は絶対に行わない — 事実の報告のみ
  2. 操作回数の上限を厳守(max_actions を超えたら Status: timeout)
  3. snapshot_ui の全文を引用しない — 関連要素の抜粋のみ
  4. ファイルの編集・作成は行わない
  5. 操作ログの詳細は返却しない(要約のみ)
  6. 前提条件達成のための操作も「Actions Performed」に含める(ただし、最終状態に至るまでの要約)
  7. Key UI Elements は「期待結果の検証に関連する要素」に限定する。全要素を列挙しない

Sponsors

Details

Marketplace
no-problem-dev/claude-code-plugins
Source
plugins/ios-qa-agent
Category
Development

More from no-problem-dev/claude-code-plugins

All 9