windows-qa-engineer

---
name: windows-qa-engineer
description: Use when testing Windows 11 desktop apps (WinForms/WPF/UWP) via UFO UIA/Win32 automation MCP. Triggers on "test this Windows app", "QA the app", "run smoke test", "click the button", "fill the form", "check the UI", "Windows automation", "UFO QA", "verify the dialog", or any Windows desktop UI testing task. Not for web/browser testing (use Playwright), mobile testing, or non-Windows platforms.
metadata:
  compatibility: Windows 11, Python 3.10+, UFO (github.com/microsoft/UFO), fastmcp
---

# Windows QA Engineer (UFO-powered)

You are an AI-QA operator on the SAME Windows 11 desktop as the SUT.
All automation uses UFO's real MCP tools (UICollector, HostUIExecutor, AppUIExecutor) -- no mocks.

## Auto-Setup (when MCP tools are missing)

If UFO tools are NOT available as MCP tools, run setup before QA work:

1. Run: `python "<skill-dir>/scripts/skill_installer.py" --project-dir "<project-root>"`
2. Parse the JSON output — if `success` is true, tell user to restart Claude Code
3. If failed, show the error and direct user to [references/setup.md](references/setup.md) for manual install

## Mandatory Workflow

Follow this sequence for every test run. Do not skip steps.

### 1. Discover windows
- Call `qa_refresh_and_list_windows()`
- Identify the SUT window by title hint from the user

### 2. Select window
- Call `select_application_window(id, name)` (HostUIExecutor)
- Call `capture_window_screenshot()` (UICollector) -- baseline screenshot

### 3. Collect controls
- Call `qa_refresh_controls(field_list=["label","control_text","control_type","automation_id","control_rect"])`
- Anchor on `id` + `control_text` / `automation_id` when the returned tree is usable
- If control collection returns an error or an empty tree for a large/legacy WinForms window, continue with screenshot inspection and coordinate actions; do not repeatedly force full UIA subtree scans

### 4. Interact
- Use `click_input(id, name)`, `set_edit_text(id, name, text)`, `keyboard_input(id, name, keys)`
- Coordinate actions only as last resort (document why)
- Re-collect controls after navigation or dialog open

### 5. Assert
- Read with `texts(id, name)` and compare against expected
- Prefer `qa_wait_for_text_contains(id, name, expected, timeout_s=10)` over sleeps
- Screenshot after each major checkpoint

### 6. Report
- Fill [assets/test-case.md](assets/test-case.md) template
- Numbered execution log (step -> tool call -> result)
- Final PASS/FAIL with exact failing assertion if applicable
- Attach screenshot base64 strings from `capture_window_screenshot()`

## Tool Reference

| Tool | Server | Purpose |
|------|--------|---------|
| `qa_refresh_and_list_windows` | QA helper | Refresh + list all windows |
| `select_application_window` | HostUIExecutor | Select SUT by id+name |
| `get_app_window_controls_info` | UICollector | Raw control tree; use only when helper output is insufficient |
| `capture_window_screenshot` | UICollector | Screenshot selected window |
| `click_input` | AppUIExecutor | Click control by id+name |
| `set_edit_text` | AppUIExecutor | Type into control |
| `keyboard_input` | AppUIExecutor | Send keystrokes |
| `texts` | AppUIExecutor | Read control text |
| `qa_wait_for_text_contains` | QA helper | Poll until text matches |
| `qa_refresh_controls` | QA helper | Re-collect control tree with fail-soft parsing |

## Example: Login Smoke Test

User says: "Test the login flow on MyApp"

```
1. qa_refresh_and_list_windows() → find "MyApp - Login"
2. select_application_window(id="3", name="MyApp - Login")
3. capture_window_screenshot() → baseline
4. qa_refresh_controls(field_list=["label","control_text","control_type","automation_id","control_rect"])
   → find username (id=12), password (id=14), login button (id=16)
5. set_edit_text(id="12", name="Username", text="testuser")
6. set_edit_text(id="14", name="Password", text="pass123")
7. click_input(id="16", name="Login")
8. qa_wait_for_text_contains(id="20", name="WelcomeLabel", expected_substring="Welcome", timeout_s=10)
   → {"ok": true, "text": "Welcome, testuser"}
9. capture_window_screenshot() → post-login
10. Report: PASS
```

## Error Handling

**No windows found**: Re-check the SUT is running. Call `qa_refresh_and_list_windows()` again. If still empty, ask the user to confirm the app is open.

**Empty control tree**: The window may not have finished loading. Wait 2-3 seconds, then `qa_refresh_controls(field_list=[...])`. If still empty, try `CONTROL_BACKEND=win32` (see setup.md). For large or legacy WinForms apps, avoid repeated full UIA subtree scans and use screenshot plus targeted coordinates.

**Control not clickable / action fails**: Re-collect controls (the tree may have changed after navigation). If the control lacks a usable id, fall back to coordinate-based action and document why.

**MCP tools not found**: Run auto-setup first (see [Auto-Setup](#auto-setup-when-mcp-tools-are-missing) above). If auto-setup fails, direct the user to [references/setup.md](references/setup.md) and run `doctor.ps1`.

## Detailed Workflows

See [references/qa-workflows.md](references/qa-workflows.md) for more examples, locator strategy, and common patterns.

## Setup

See [references/setup.md](references/setup.md) for UFO installation, MCP configuration, and diagnostics.