Windows Desktop E2eSAFE

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: windows-desktop-e2e
description: E2E testing for Windows native desktop apps (WPF, WinForms, Win32/MFC, Qt) using pywinauto and Windows UI Automation.
origin: ECC
---

# Windows デスクトップ E2E テスト

**pywinauto** と Windows UI Automation(UIA)を使用したWindowsネイティブデスクトップアプリケーションのエンドツーエンドテスト。WPF、WinForms、Win32/MFC、Qt(5.x / 6.x)をカバーし、Qt固有のガイダンスは専用セクションとして提供します。

## アクティベートするタイミング

- Windowsネイティブデスクトップアプリケーションのエンドツーエンドテストを書くまたは実行するとき
- デスクトップGUIテストスイートをゼロから設定するとき
- 不安定または失敗するデスクトップオートメーションテストを診断するとき
- 既存のアプリにテスタビリティ(AutomationId、アクセシブルな名前)を追加するとき
- デスクトップエンドツーエンドをCI/CDパイプライン(GitHub Actions `windows-latest`)に統合するとき

### 使用しないタイミング

- Webアプリケーション → `e2e-testing` スキル(Playwright)を使用する
- Electron / CEF / WebView2 アプリ → HTMLレイヤーにはUIAではなくブラウザオートメーションが必要
- モバイルアプリ → プラットフォーム固有のツールを使用する(UIAutomator、XCUITest)
- 実行中のGUIを必要としない純粋なユニットまたは統合テスト

## コアコンセプト

すべてのWindowsデスクトップオートメーションは**UI Automation(UIA)**に依存します。これはWindowsに組み込まれたアクセシビリティAPIです。サポートされているすべてのフレームワークは、読み取りおよび操作可能なプロパティを持つUIA要素のツリーを公開します:

```
テスト(Python)
    └── pywinauto(UIAバックエンド)
        └── Windows UI Automation API   ← Windowsに組み込み、フレームワーク非依存
            └── アプリのUIAプロバイダー      ← 各フレームワークが独自に実装
                └── 実行中の .exe
```

**フレームワーク別UIA品質:**

| フレームワーク | AutomationId | 信頼性 | 注記 |
|-----------|-------------|-------------|-------|
| WPF | 5/5 | 優秀 | `x:Name` が直接AutomationIdにマッピング |
| WinForms | 4/5 | 良好 | `AccessibleName` = AutomationId |
| UWP / WinUI 3 | 5/5 | 優秀 | Microsoftの完全サポート |
| Qt 6.x | 5/5 | 優秀 | アクセシビリティがデフォルトで有効;クラス名が `Qt6*` に変更 |
| Qt 5.15+ | 4/5 | 良好 | Accessibilityモジュールが改善 |
| Qt 5.7–5.14 | 3/5 | 普通 | `QT_ACCESSIBILITY=1` が必要;objectNameは手動設定 |
| Win32 / MFC | 3/5 | 普通 | コントロールIDにアクセス可能;テキストマッチングが一般的 |

## セットアップと前提条件

```bash
# Python 3.8+、Windowsのみ
pip install pywinauto pytest pytest-html Pillow pytest-timeout
# オプション:画面録画
# ffmpegをインストールしてPATHに追加:https://ffmpeg.org/download.html
```

UIAが到達可能か確認:

```python
from pywinauto import Desktop
Desktop(backend="uia").windows()  # すべてのトップレベルウィンドウを一覧表示
```

**Accessibility Insights for Windows**をインストールしてください(Microsoft提供、無料)— テストを書く前にUIA要素ツリーを検査するためのDevTools相当のツールです。

## テスタビリティのセットアップ(フレームワーク別)

テストを書く前に**全てのインタラクティブなコントロールに安定したAutomationIdを設定すること**が最も効果的です。

### WPF

```xml
<!-- XAML: x:Name が自動的にAutomationIdになる -->
<TextBox x:Name="usernameInput" />
<PasswordBox x:Name="passwordInput" />
<Button x:Name="btnLogin" Content="Login" />
<TextBlock x:Name="lblError" />
```

### WinForms

```csharp
// デザイナーまたはコードで設定
usernameInput.AccessibleName = "usernameInput";
passwordInput.AccessibleName = "passwordInput";
btnLogin.AccessibleName = "btnLogin";
lblError.AccessibleName = "lblError";
```

### Win32 / MFC

```cpp
// .rcファイルのコントロールリソースIDがAutomationId文字列として公開される
// IDC_EDIT_USERNAME -> AutomationId "1001"
// 名前にはSetWindowTextを優先;より豊かなサポートにはIAccessibleを追加する
```

### Qt — 以下の専用セクションを参照

---

## ページオブジェクトモデル

```
tests/
├── conftest.py          # アプリ起動フィクスチャ、失敗時スクリーンショット
├── pytest.ini
├── config.py
├── pages/
│   ├── __init__.py      # インポートに必須
│   ├── base_page.py     # ロケーター、ウェイト、スクリーンショットヘルパー
│   ├── login_page.py
│   └── main_page.py
├── tests/
│   ├── __init__.py
│   ├── test_login.py
│   └── test_main_flow.py
└── artifacts/           # スクリーンショット、動画、ログ
```

### base_page.py

```python
import os, time
from pywinauto import Desktop
from config import ACTION_TIMEOUT, ARTIFACT_DIR

class BasePage:
    def __init__(self, window):
        self.window = window

    # --- ロケーター(優先順位順)---

    def by_id(self, auto_id, **kw):
        """AutomationId — 最も安定。第一選択として使用する。"""
        return self.window.child_window(auto_id=auto_id, **kw)

    def by_name(self, name, **kw):
        """表示テキスト / アクセシブルな名前。"""
        return self.window.child_window(title=name, **kw)

    def by_class(self, cls, index=0, **kw):
        """コントロールクラス + インデックス — 脆弱、可能なら避ける。"""
        return self.window.child_window(class_name=cls, found_index=index, **kw)

    # --- ウェイト ---

    def wait_visible(self, spec, timeout=ACTION_TIMEOUT):
        spec.wait("visible", timeout=timeout)
        return spec

    def wait_gone(self, spec, timeout=ACTION_TIMEOUT):
        spec.wait_not("visible", timeout=timeout)
        return spec

    def wait_window(self, title, timeout=ACTION_TIMEOUT):
        """新しいトップレベルウィンドウ(ダイアログ、子ウィンドウ)を待つ。"""
        dlg = Desktop(backend="uia").window(title=title)
        dlg.wait("visible", timeout=timeout)
        return dlg

    def wait_until(self, fn, timeout=ACTION_TIMEOUT, interval=0.3):
        """任意の条件をポーリング — UIAイベントが信頼できない場合に使用する。"""
        deadline = time.time() + timeout
        while time.time() < deadline:
            try:
                if fn():
                    return True
            except Exception:
                pass
            time.sleep(interval)
        raise TimeoutError(f"条件が{timeout}秒以内に満たされなかった")

    # --- アクション ---

    def click(self, spec):
        self.wait_visible(spec)
        spec.click_input()

    def type_text(self, spec, text):
        self.wait_visible(spec)
        ctrl = spec.wrapper_object()
        try:
            ctrl.set_edit_text(text)
        except Exception as e:
            # Qt 5.x フォールバック:UIA Value Pattern が不完全な場合がある
            import sys, pywinauto.keyboard as kb
            print(f"[windows-desktop-e2e] set_edit_text 失敗 ({e})、キーボードフォールバックを使用", file=sys.stderr)
            ctrl.click_input()
            kb.send_keys("^a")
            kb.send_keys(text, with_spaces=True)

    def get_text(self, spec):
        ctrl = spec.wrapper_object()
        for attr in ("window_text", "get_value"):
            try:
                v = getattr(ctrl, attr)()
                if v:
                    return v
            except Exception:
                pass
        return ""

    # --- アーティファクト ---

    def screenshot(self, name):
        os.makedirs(ARTIFACT_DIR, exist_ok=True)
        path = os.path.join(ARTIFACT_DIR, f"{name}.png")
        self.window.capture_as_image().save(path)
        return path
```

### login_page.py

```python
from pages.base

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.