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 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

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.