desktop-test-author

When invoked

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

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:

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("alice@example.com");
        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.

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

Examples

Worked example - WPF login flow + FlaUI

Input spec: "User enters alice@example.com 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).