/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 or Windows Server 2025 Desktop Experience, Python 3.10, UFO, fastmcp

Windows QA Engineer (UFO-powered)

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

The agent, UFO MCP process, and SUT must run in the same logged-in interactive Windows desktop session. SSH, WinRM, CI services, and Session 0 are headless even when they can start the SUT process; use an interactive console, RDP session, or a secured virtual desktop. Never expose RDP publicly merely to satisfy this requirement.

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, restart the MCP client 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.