{"id":"eaa88f25-503b-4174-b722-ca236a905d19","shortId":"vZ7fzS","kind":"skill","title":"unity-ui","tagline":"UI 開発・検査・自動テストワークフロー。uitree で構造把握→pytest E2E テスト生成→PlayMode テストに移植。\nUse for: \"UI確認\", \"UI Toolkit\", \"uGUI\", \"E2Eテスト\", \"UI操作\", \"uitree\", \"スクリーンショット\"","description":"# unity-ui\n\n> **PREREQUISITE:** `../unity-shared/SKILL.md`（Relay Server 経由で Unity Editor が起動/アクティブであること）\n>\n> skill 経由のコマンドは必ず `-i ` を付ける (unity-shared #インスタンス指定)。\n>\n> uitree コマンドは Play Mode 中のみ動作する。必ず `u -i play` してから実行すること。\n\n## UI テストの種別\n\n| 種別 | 検証内容 | 手法 | スクショ |\n|------|---------|------|---------|\n| Functional | 操作→状態が正しいか | click → text で値検証 | 不要 |\n| Visual Regression | 外観が変わっていないか | screenshot → 画像比較 | 必要 |\n| Structural Snapshot | ツリー構造が変わっていないか | dump --json → diff | 不要 |\n| Smoke | 最低限動くか | click → console にエラーなし | 任意 |\n| Monkey | ランダム操作でクラッシュしないか | monkey → errors 確認 | 不要 |\n\n## UI システム判定\n\n| 手がかり | UI Toolkit | uGUI |\n|---------|-----------|------|\n| ファイル | `.uxml`, `.uss` | `.prefab` に Canvas |\n| コンポーネント | UIDocument | Canvas, RectTransform |\n\n## コマンドリファレンス\n\n要素の指定方法は2通り: ref ID (`ref_3`) または `-p -n `。\n\n### 構造把握\n\n```bash\nu -i uitree dump # 全パネル一覧 (contextType: Player がゲーム側)\nu -i uitree dump -p \"PanelSettings\" # パネルのツリー (各要素の ref/name/type/classes が見える)\nu -i uitree dump -p \"PanelSettings\" --json # JSON 出力 (snapshot用)\nu -i uitree query -p \"PanelSettings\" -t Button # type で検索 (VisualElement ベースのボタンはヒットしない → -c で検索)\nu -i uitree query -p \"PanelSettings\" -n \"BtnStart\" # name で検索\nu -i uitree query -p \"PanelSettings\" -c \"action-btn\" # USS class で検索\nu -i uitree query -p \"PanelSettings\" -t Button -c \"primary\" # AND 条件\nu -i uitree inspect -p \"PanelSettings\" -n \"BtnStart\" # 要素詳細\nu -i uitree inspect ref_5_48 # ref ID で指定\nu -i uitree inspect ref_5_48 --style # resolvedStyle 含む\nu -i uitree inspect ref_5_48 --children # 子要素情報含む\n```\n\n### テキスト取得\n\n```bash\nu -i uitree text -p \"PanelSettings\" -n \"ToastMessage\" # name で指定\nu -i uitree text ref_5_12 # ref ID で指定\n```\n\n### 操作\n\n```bash\nu -i uitree click -p \"PanelSettings\" -n \"BtnContinue\" # name で指定\nu -i uitree click ref_5_48 # ref ID で指定\nu -i uitree click ref_5_48 --count 2 # ダブルクリック\nu -i uitree click ref_5_48 --button 1 # 右クリック\nu -i uitree scroll -p \"PanelSettings\" -n \"ScrollArea\" --y 100\n```\n\n### モンキーテスト\n\n```bash\nu -i uitree monkey -p \"PanelSettings\" -c \"action-btn\" --count 50 --seed 42\nu -i uitree monkey -p \"PanelSettings\" --duration 30 --seed 42\nu -i uitree monkey -p \"PanelSettings\" -c \"action-btn\" --stop-on-error --json\n```\n\nquery でフィルタした要素をランダムに click し、コンソールエラーを監視する。\n`-c` (USS class) か `-t` (type) のフィルタが必須（フィルタなしでは要素が見つからない）。\n事前に `u -i uitree query -p -c ` で有効な class 名を確認してから monkey に渡す。\n`--seed` で操作順を再現可能。\n\n### スナップショット\n\n```bash\nu -i uitree snapshot save -p \"PanelSettings\" --name baseline # 現在のツリーを保存\nu -i uitree snapshot diff -p \"PanelSettings\" --name baseline # baseline との差分\nu -i uitree snapshot list # 保存済み一覧\nu -i uitree snapshot delete --name baseline # 削除\n```\n\ndiff 出力: 要素の追加(`+`)/削除(`-`)/classes 変化(`~`) を検出。\n\n### スクリーンショット\n\n```bash\nu -i screenshot # GameView (-s game がデフォルト)\nu -i screenshot -p \"ui-check.png\" # 保存先指定\nu -i screenshot --burst -n 5 # 連続 (アニメーション確認)\n```\n\nUI Toolkit / uGUI (Screen Space) は `-s game` でのみ映る。`-s camera` では映らない。\n\nGameView のキャプチャにはエディタのフォーカスが必要。タイムアウトする場合は再試行で解決することが多い。\n\n### uGUI の場合\n\nuitree は UI Toolkit 専用。uGUI は scene/component コマンドで操作する。\n\n```bash\nu -i scene hierarchy --depth 3\nu -i component list -t \"Canvas\"\nu -i component inspect -t \"MyButton\" -T \"UnityEngine.UI.Button\"\n```\n\n## 開発→テストフロー\n\n```text\nPhase 1: 作成 & 手動確認\n コード変更 → /unity-verify → play → dump → 操作 → screenshot → stop\n\nPhase 2: pytest E2E テスト生成\n dump で構造把握 → pytest テストファイルを生成 → 実行して確認\n\nPhase 3: PlayMode テスト移植\n 安定したシナリオを C# に書き直す → CI で回帰テスト\n```\n\n### Phase 1: 作成 & 手動確認\n\n```bash\nu -i play\nu -i uitree dump -p \"PanelSettings\" # 構造把握\nu -i uitree click -p \"PanelSettings\" -n \"BtnStart\" # 操作\nu -i uitree text -p \"PanelSettings\" -n \"StatusLabel\" # 状態確認\nu -i screenshot # 結果キャプチャ\nu -i stop\n```\n\n### Phase 2: pytest E2E テスト生成\n\nPhase 1 で確認した操作シナリオを、pytest テストとして永続化する。\nunity-cli の Python API (`UITreeAPI`, `ConsoleAPI`, `EditorAPI`) を直接使う。\n\n手順:\n1. `u -i play` + `u -i uitree dump` で構造を把握する\n2. 操作可能な要素（ボタン名、ラベル名）を特定する\n3. 以下のテンプレートに従い、`tests/integration/` にテストファイルを生成する\n4. `uv run python -m pytest tests/integration/ -v` で実行して確認する\n\nテンプレート:\n\n```python\n\"\"\"E2E tests for — pytest + unity-cli API.\"\"\"\nimport time\nimport pytest\nfrom unity_cli.api import ConsoleAPI, EditorAPI, UITreeAPI\nfrom unity_cli.client import RelayConnection\n\nPANEL = \"<パネル名>\" # u uitree dump で確認したパネル名\n\n\n@pytest.fixture(scope=\"module\")\ndef conn() -> RelayConnection:\n conn = RelayConnection(instance=\"<プロジェクト名>\", timeout=5.0)\n try:\n EditorAPI(conn).get_state()\n except Exception:\n pytest.skip(\"Relay not available\")\n return conn\n\n\n@pytest.fixture(scope=\"module\")\ndef uitree(conn: RelayConnection) -> UITreeAPI:\n return UITreeAPI(conn)\n\n\n@pytest.fixture(scope=\"module\")\ndef console(conn: RelayConnection) -> ConsoleAPI:\n return ConsoleAPI(conn)\n\n\n@pytest.fixture(scope=\"module\")\ndef editor(conn: RelayConnection) -> EditorAPI:\n return EditorAPI(conn)\n\n\n@pytest.fixture(autouse=True)\ndef _play_mode(editor: EditorAPI):\n \"\"\"Play Mode に入る。\"\"\"\n state = editor.get_state()\n if not state.get(\"isPlaying\"):\n editor.play()\n deadline = time.time() + 10\n while time.time() < deadline:\n if editor.get_state().get(\"isPlaying\"):\n break\n time.sleep(0.5)\n yield\n\n\n@pytest.fixture(scope=\"module\", autouse=True)\ndef _stop_after_all(editor: EditorAPI):\n \"\"\"全テスト後に Play Mode 終了。\"\"\"\n yield\n try:\n editor.stop()\n except Exception:\n pass\n\n\n# --- Functional テスト ---\n\nclass TestMenuButtons:\n def test_continue_shows_toast(self, uitree: UITreeAPI) -> None:\n uitree.click(panel=PANEL, name=\"<ボタン名>\")\n time.sleep(0.3)\n result = uitree.text(panel=PANEL, name=\"<ラベル名>\")\n assert result[\"text\"] == \"<期待値>\"\n\n\n# --- Smoke テスト ---\n\nclass TestSmoke:\n BUTTONS = [\"<ボタン1>\", \"<ボタン2>\", ...]\n\n def test_all_clickable_without_errors(self, uitree: UITreeAPI, console: ConsoleAPI) -> None:\n console.clear()\n for btn in self.BUTTONS:\n uitree.click(panel=PANEL, name=btn)\n time.sleep(0.2)\n errors = console.get(types=[\"error\"])\n assert errors.get(\"entries\", []) == []\n\n\n# --- Structural Snapshot ---\n\nclass TestStructure:\n def test_tab_switch_changes_tree(self, uitree: UITreeAPI) -> None:\n before = uitree.dump(panel=PANEL)\n uitree.click(panel=PANEL, name=\"<タブ名>\")\n time.sleep(0.3)\n after = uitree.dump(panel=PANEL)\n assert before != after\n```\n\n既存の `conftest.py` に `conn`, `uitree`, `editor`, `console` fixture がある場合はテンプレートの fixture 定義を省略し、conftest に委譲する。fixture の scope は conftest に合わせる（conftest が `session` なら `_play_mode` 等も同じ scope か互換性のある scope にする）。\n\n動的な値（タイムスタンプ、プログレス%等）を持つラベルは等値比較ではなくフォーマット検証を使う:\n```python\nassert result[\"text\"].endswith(\"%\") # \"65%\" 等\n```\n\nテストの種別に応じてクラスを追加する:\n- `TestMenuButtons` — Functional (click → text 検証)\n- `TestSmoke` — 全ボタンクリック + エラーなし\n- `TestStructure` — ツリー構造の変化検出\n- `TestMonkey` — ランダム操作でエラーなし\n- `TestVisual` — screenshot 撮影（画像比較は手動 or 別ツール）\n\nMonkey テスト例:\n```python\nfrom unity_cli.api.uitree_monkey import MonkeyRunner\n\nclass TestMonkey:\n def test_random_clicks_no_errors(self, uitree: UITreeAPI, console: ConsoleAPI) -> None:\n # MonkeyRunner.run() は MonkeyResult を返す。errors は list[dict]\n runner = MonkeyRunner(uitree, console)\n result = runner.run(panel=PANEL, class_filter=\"<操作対象class>\", count=50, seed=42, interval=0.2)\n assert result.errors == [], f\"Monkey errors: {result.errors}\"\n```\n\nSnapshot テスト例:\n```python\nfrom unity_cli.api.uitree_snapshot import SnapshotStore\n\nclass TestSnapshot:\n def test_save_and_diff_no_changes(self, uitree: UITreeAPI, tmp_path) -> None:\n store = SnapshotStore(snapshot_dir=tmp_path / \"snapshots\")\n data = uitree.dump(panel=PANEL, format=\"json\")\n store.save(\"baseline\", data)\n current = uitree.dump(panel=PANEL, format=\"json\")\n # diff(name, current): name は保存済みスナップショット名、current は比較対象のツリーデータ\n result = store.diff(\"baseline\", current)\n assert result[\"added\"] == []\n assert result[\"removed\"] == []\n assert result[\"changed\"] == []\n```\n\nmonkey テストの前にUIを初期状態に戻す（前のテストの副作用で Toast 等のクラスが変わることがある）。`time.sleep(2)` で Toast の hidden 復帰を待つか、テスト順序に依存しない assertion を使う。\n\n### Phase 3: PlayMode テスト移植\n\nPhase 2 の pytest で安定したシナリオを C# PlayMode テストに書き直す。\n\nPlayMode に移植する基準:\n- CI で毎回回す回帰テスト\n- フレーム精度が必要 (アニメーション完了待ち等)\n- Assert で厳密に状態検証\n- InputSystem / EventSystem 経由の操作\n\npytest E2E のまま残す基準:\n- 探索的テスト (シナリオが毎回変わる)\n- AI エージェントの自律テスト\n- Unity 外からの結合テスト\n\n手順:\n1. Phase 2 の pytest テストから安定したシナリオを選ぶ\n2. 以下のテンプレートに従い、`Assets/Tests/PlayMode/` に C# テストを生成する\n3. asmdef に UI コントローラの参照を追加する（必要に応じて）\n4. `u -i tests run play` で実行して確認する\n\nテンプレート:\n\n```csharp\nusing System.Collections;\nusing NUnit.Framework;\nusing UnityEngine;\nusing UnityEngine.TestTools;\nusing UnityEngine.UIElements;\n\nnamespace Game.Tests.PlayMode\n{\n [TestFixture]\n public class Tests\n {\n private GameObject _hudObject;\n private UIDocument _uiDocument;\n private VisualElement _root;\n\n [UnitySetUp]\n public IEnumerator SetUp()\n {\n // UIDocument を持つ GameObject を生成\n // コントローラが Awake/OnEnable で初期化するのを待つ\n _hudObject = new GameObject(\"TestHUD\");\n _hudObject.AddComponent<<コントローラ名>>();\n _uiDocument = _hudObject.GetComponent();\n\n // コルーチン初期化 (StartCoroutine in OnEnable 等) は1フレームでは完了しない\n // 2フレーム以上待つ\n yield return null;\n yield return null;\n\n _root = _uiDocument.rootVisualElement;\n Assert.IsNotNull(_root, \"Root visual element should be initialized\");\n }\n\n [TearDown]\n public void TearDown()\n {\n Object.Destroy(_hudObject);\n }\n\n // --- Functional テスト ---\n\n [UnityTest]\n public IEnumerator <ボタン名>_Shows<期待される動作>()\n {\n var btn = _root.Q(\"<ボタン名>\");\n Assert.IsNotNull(btn);\n\n Click(btn);\n yield return null;\n\n var label = _root.Q