| 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:
- Run:
python "<skill-dir>/scripts/skill_installer.py" --project-dir "<project-root>"
- Parse the JSON output — if
success is true, tell user to restart Claude Code
- If failed, show the error and direct user to 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 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 above). If auto-setup fails, direct the user to references/setup.md and run doctor.ps1.
Detailed Workflows
See references/qa-workflows.md for more examples, locator strategy, and common patterns.
Setup
See references/setup.md for UFO installation, MCP configuration, and diagnostics.
