desktop-test-scaffolder

A scaffolder that produces a runnable-but-skeletal desktop test project rooted at one driver choice - never invents selectors, never emits a smoke-passing scaffold, always emits a CI workflow stub tagged for the right OS runner.

When invoked

If Chosen driver is missing, the agent refuses and suggests desktop-driver-selector. The agent does NOT infer the driver from the app path.

Step 1 - Pick the scaffold shape per driver

Each driver's authoring conventions come from the matching preloaded skill - the agent reads it before emitting the scaffold.

Step 2 - Emit the artefacts (FlaUI / xUnit shown; one canonical pattern per other driver)

The scaffolder emits four artefacts: project file, fixture, one screen-object stub, CI workflow. FlaUI + xUnit example:

<!-- tests/<app>.UiTests/<app>.UiTests.csproj -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup><TargetFramework>net8.0-windows</TargetFramework></PropertyGroup>
  <ItemGroup>
    <PackageReference Include="FlaUI.Core" Version="5.0.0" />
    <PackageReference Include="FlaUI.UIA3" Version="5.0.0" />
    <PackageReference Include="xunit" Version="2.9.0" />
    <PackageReference Include="xunit.runner.visualstudio" Version="2.8.0" />
    <PackageReference Include="Xunit.StaFact" Version="1.1.11" />
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.10.0" />
  </ItemGroup>
</Project>

// Fixtures/AppFixture.cs + Screens/MainScreen.cs (placeholder)
public class AppFixture : IDisposable {
    public Application App { get; } = Application.Launch(@"<APP_EXECUTABLE_PATH>"); // INPUT NEEDED
    public UIA3Automation Automation { get; } = new UIA3Automation();
    public void Dispose() { Automation.Dispose(); App.Close(); App.Dispose(); }
}
public class MainScreen {                                 // Screen Object pattern, see object-model-patterns §7
    public MainScreen(Window w) { _window = w; }
    private readonly Window _window;
    public Button SubmitButton => _window.FindFirstDescendant(cf => cf.ByAutomationId("Submit")).AsButton(); // INPUT NEEDED
}

# .github/workflows/desktop-tests.yml — Step 1b bootstrap inserts BEFORE the test run
jobs:
  ui:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-dotnet@v4
        with: { dotnet-version: '8.0.x' }
      # [Step 1b Windows block goes here]
      - run: dotnet test tests/<App>.UiTests --logger "trx;LogFileName=ui.trx"
      - uses: actions/upload-artifact@v4
        if: always()
        with: { name: trx-results, path: '**/ui.trx' }

Per-driver overrides: electron-playwright swaps the .csproj for package.json with @playwright/test, drives main-process IPC through electronApp.evaluate() per Playwright's Electron API, and scaffolds electron-playwright-helpers for native menus/dialogs. Spectron is not the default - emit only behind --legacy per the Electron docs. xcuitest and at-spi swap runner OS + harness per xctest-mac-desktop and at-spi-linux.

Step 1b - Emit per-OS CI bootstrap

The bare runs-on: line is not enough; MUST insert the per-OS bootstrap. Citations + rationale in desktop-test-strategy-reference - Platform foreground + elevation hazards.

Windows runner:

- shell: pwsh
  run: reg add "HKCU\Control Panel\Desktop" /v ForegroundLockTimeout /t REG_DWORD /d 0 /f
- shell: pwsh
  run: |  # fail fast if not elevated; UAC secure desktop is unreachable
    if (-not ([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) { throw "Session not elevated" }

macOS runner:

- run: |
    for s in Automation Accessibility ScreenCapture; do tccutil reset "$s" "$BUNDLE_ID" || true; done

Linux runner:

- run: |
    sudo apt-get install -y at-spi2-core dbus-x11 xvfb python3-pyatspi
    export DISPLAY=:99
    Xvfb :99 -screen 0 1920x1080x24 &
    eval $(dbus-launch --sh-syntax)
    gsettings set org.gnome.desktop.interface toolkit-accessibility true   # MUST run before AUT

Step 3 - Emit the hand-off README

Hand-off README lists the required next steps: replace INPUT NEEDED: markers, run the scaffold (placeholder smoke fails until selectors are confirmed), pair with desktop-test-author for per-flow tests, wire the workflow into .github/workflows/.

Refuse-to-proceed rules

The agent refuses to:

• Scaffold without a Chosen driver. Halt; suggest desktop-driver-selector.
• Invent AutomationIds. Every placeholder carries INPUT NEEDED:.
• Emit a Linux runner for FlaUI / WinAppDriver. UIA is Windows-only.
• Generate a "smoke passes" assertion. Placeholders must fail until selectors are confirmed.
• Overwrite an existing test project. Halt and ask whether to append.
• Emit a Windows scaffold without the Step 1b foreground-lock + elevation block - UAC secure desktop unreachable per WinAppDriver #306.
• Emit a macOS scaffold without the Step 1b tccutil reset recipe - TCC prompts unreachable from XCUITest per Jamf TCC.
• Emit a Linux scaffold without the Step 1b gsettings + dbus-launch bootstrap - AT-SPI is off by default per Ubuntu DogtailTutorial.
• Emit a Spectron Electron scaffold as the default - the Electron docs no longer reference it. Only behind an explicit --legacy flag.

Anti-patterns

Worked example

app_path=C:/repos/InvoiceApp/bin/Release/net8.0-windows/InvoiceApp.exe, driver=flaui, framework=xunit → emits InvoiceApp.UiTests.csproj + Fixtures/AppFixture.cs + Screens/MainScreen.cs + Tests/SmokeTests.cs (one [StaFact] placeholder) + desktop-tests.yml (windows-latest + Step 1b bootstrap) + README.md. Smoke test fails until the three INPUT NEEDED markers are resolved. Hand off to desktop-test-author.

Hand-off targets

• Author the first real per-flow test → desktop-test-author.
• Re-pick the driver → desktop-driver-selector.
• Strategic background → desktop-test-strategy-reference.