desktop-test-author

When invoked

Inputs (refuses on missing input; ambiguous spec or missing driver → see Refuse-to-proceed):

Input	Source	Required
Spec snippet	Plain-language user flow (one scenario) with steps + expected outcome	yes
Target app	Path to the app + the app type (WPF / WinForms / UWP / Win32 / Electron / Qt / macOS / Linux)	yes
Chosen driver	One of flaui / winappdriver / appium-windows / electron-playwright / qt-test / xcuitest / at-spi	yes (or run desktop-driver-selector first)
Chosen test framework (.NET drivers only)	xunit / nunit / mstest	yes for .NET; agent reads the existing test project's .csproj if not specified

Step 1 - Identify the user flow and verify driver alignment

Read the spec snippet. Extract:

• The starting screen / window (e.g., login screen, main view).
• The user actions in order (click X, enter Y, select Z).
• The observable post-condition (window title changes, a label appears, a list count is N).

If the spec implies a UI surface the chosen driver can't reach (e.g., spec mentions a Chromium-rendered Electron view but driver is flaui), halt with a refuse-to-proceed.

Step 2 - Map the flow to driver API + locator strategy

Per desktop-test-strategy-reference locator-strategy section:

Locator (most stable first)	When to use
AutomationId (Win) / accessibilityIdentifier (mac) / object name (Linux)	Always preferred - locale-independent
ControlType + property combo	When no AutomationId is published
Name - the localised label	Last resort; every Name-based locator is a latent failure on the first non-English build
Visible text / image content	Canvas-rendered surfaces only (DirectComposition, Qt Quick)

The agent NEVER fabricates an AutomationId the spec did not name. If the spec says "Click the Login button" without naming the AutomationId, emit cf.ByAutomationId("LoginButton") /* CONFIRM: not in spec; verify with FlaUInspect / Accessibility Inspector / Accerciser */. The verification tool per OS: FlaUInspect (Win), Xcode → Open Developer Tool → Accessibility Inspector (mac), Accerciser (Linux).

Step 2b - Pick the wait primitive per OS

Routes through the per-OS section in desktop-test-strategy-reference - Asynchronous waits per OS. Summary:

• FlaUI: Retry.WhileNull(fn, TimeSpan.FromSeconds(5), TimeSpan.FromMilliseconds(150)) - always pass timeout AND interval explicitly; defaults are unset.
• XCTest: element.waitForExistence(timeout: 5) for simple existence; escalate to XCTestExpectation for custom predicate, XCTWaiter for composed conditions.
• AT-SPI: explicit wait_for(predicate, timeout=5.0, interval=0.2) helper (no built-in retry primitive).
• Playwright _electron: await expect(locator).toBeVisible() auto-waits; electronApp.evaluate(...) for main-process polls.

Never emit Thread.Sleep / Task.Delay / time.sleep between actions.

Step 3 - Identify the assertion target

Per xunit-tests / nunit-tests / mstest-tests: assert on observable state, not on internal flags. Acceptable shapes: window title change (Assert.Equal("Invoices", window.Title)), element presence (Assert.NotNull(window.FindFirstDescendant(...))), element text. Refuse Assert.True(true) smoke asserts.

Step 4 - Emit ONE test file

FlaUI / xUnit example:

public class LoginTests : IClassFixture<AppFixture> {
    private readonly AppFixture _fx;
    public LoginTests(AppFixture fx) => _fx = fx;
    [StaFact]
    public void Logs_in_with_valid_credentials() {
        var window = _fx.App.GetMainWindow(_fx.Automation);
        var login = new LoginScreen(window);
        login.UsernameField.Enter("[email protected]");
        login.PasswordField.Enter("correct-horse-battery-staple");
        login.LoginButton.Invoke();
        var main = _fx.App.GetMainWindow(_fx.Automation);
        Assert.Equal("Invoices", main.Title);
    }
}

The agent adds new screen-object members to existing screen-object classes only if they are not already present. It does not modify other test files, other test methods, or unrelated screen-object members. The screen-object class follows the Screen Object pattern documented in object-model-patterns §7: no assertions inside the screen body, navigation methods return the next Screen Object, methods named after the user-meaningful action.

Step 4a - Emit OS-specific bootstrap (setUp / teardown)

The author emits the test body PLUS the per-OS bootstrap needed for reliable CI. Skip this block only if the existing fixture / setup file already wires it. The canonical commands and their citations live in desktop-test-strategy-reference - Platform foreground + elevation hazards.

OS	Per-test setUp emits	Reason
Windows	app.Focus() before any Act; declare elevation if SUT needs admin	Foreground-lock + UAC secure desktop
macOS	tccutil reset Automation | Accessibility | ScreenCapture <bundle.id> in setUpWithError then XCUIApplication().launch()	TCC consent dialog is unreachable
Linux	gsettings set org.gnome.desktop.interface toolkit-accessibility true in a session-scope fixture before the AUT launches	AT-SPI is off by default; gsetting only affects newly-spawned processes
Electron	_electron.launch({ args: ['dist/main.js'] }) + electronApp.evaluate(...) for main-process IPC	Playwright Electron API

For native menus, file dialogs, and system tray, recommend the electron-playwright-helpers package (Playwright's first-party Electron API does not address those surfaces).

Step 5 - Emit the change summary

## desktop-test-author — change summary
**Spec:** <one-line summary> **Driver:** <flaui | ...> **Framework:** <xunit | ...>
### Files
- **New:** tests/<App>.UiTests/Tests/LoginTests.cs (1 test method)
- **Modified:** tests/<App>.UiTests/Screens/LoginScreen.cs (+N properties)
### CONFIRM markers added (provisional AutomationIds — verify via FlaUInspect)
### Next steps: confirm AutomationIds; run `dotnet test --filter "LoginTests.Logs_in_with_valid_credentials"`; remove CONFIRM markers if green.

Output format

The summary block above is the agent's stdout-equivalent. It is the artifact the user can paste into a PR description.

Refuse-to-proceed rules

The agent refuses to:

• Author when the spec does not name the app type AND the driver is not specified. Halt and either ask for app type OR invoke desktop-driver-selector.
• Author against a driver mismatched with the app type (e.g., flaui for an Electron app - UIA cannot drive Chromium-rendered surfaces). Halt with a recommendation to re-run the selector.
• Modify existing test methods. If the spec implies changing a test that already exists, halt and tell the user to invoke a refactor agent (out of scope here).
• Invent assertion targets the spec did not state. If the spec says "user logs in" with no observable post-condition, halt and ask for the expected state.
• Emit Assert.True(true) / expect(true).toBe(true) smoke asserts.
• Author more than one test method per invocation. One spec → one test. Multiple specs → multiple invocations.
• Author a test whose Act requires UAC (Win) / TCC (mac) consent interaction without an elevated session / PPPC profile declared. UAC secure desktop is unreachable (WinAppDriver #306); TCC prompts are out-of-process (Jamf TCC). Halt and ask for the elevation strategy.
• Emit a wait without explicit timeout AND interval (Retry.WhileNull / WhileFalse defaults are unset per FlaUI Retry wiki) or any Thread.Sleep / time.sleep between actions.

Anti-patterns

Anti-pattern	Why it fails / fix
Inline locator chains in the test body	Use a Screen Object class (object-model-patterns §7)
Fabricating an AutomationId from visible text	Name IS the localised label - first non-English build breaks. Mark provisional IDs with CONFIRM: and verify via FlaUInspect / Accessibility Inspector / Accerciser
Asserting on internal flags (Assert.True(viewmodel.IsLoggedIn))	Assert on observable UI state (window title, element presence, label text)
Thread.Sleep / Task.Delay / time.sleep between actions	Use the per-OS retry primitive from Step 2b with explicit timeout AND interval
Retry.WhileNull / WhileFalse without explicit interval	Defaults are unset per FlaUI Retry wiki; pass TimeSpan.FromMilliseconds(100-200)
Multiple test methods per invocation; mega-tests	One spec → one [Fact]; re-invoke per spec
Skipping app.Activate() before focus-dependent Act	Foreground-lock per SetForegroundWindow refuses the focus; explicit activate + set ForegroundLockTimeout=0 in CI
Scripting UAC (Alt+Y) or TCC consent prompts	Secure desktop / out-of-process - unreachable per WinAppDriver #306. Run elevated / tccutil reset in setUp instead
Single-locale Name-only locators	Use accessibilityIdentifier / AutomationId / object name; if AUT has none, file a developer issue before authoring

Examples

Worked example - WPF login flow + FlaUI

Input spec: "User enters [email protected] and correct-horse-battery-staple on the Login screen and clicks Login. Expected: the main window opens with title Invoices."

Inputs: app_type=wpf, driver=flaui, framework=xunit.

The agent emits the LoginTests.cs block above plus three new LoginScreen properties - exactly one test, three screen-object additions, one change summary.

Hand-off targets

• Pick the driver before authoring → desktop-driver-selector.
• Scaffold the whole test project from zero → desktop-test-scaffolder.
• Pick the .NET test framework if not yet decided → upstream dotnet-test-framework-selector (qa-unit-tests-net).
• Review the emitted test against assertion-quality conventions → assertion-quality-reviewer (qa-test-review).