Repository avatar
Developer Tools
v0.2.0
active

wpf-locator-doctor

io.github.swechhap/wpf-locator-doctor

Scores how testable a WPF app is and suggests the AutomationId fixes UI tests need.

Documentation

WPF Locator Doctor

M8ven Score

Diagnose, heal and fix the locators in your WPF UI automation tests.

Finding good locators in a WPF app usually means hours in inspect tools (Inspect.exe, FlaUInspect, Accessibility Insights), and tests still break when IDs are missing, duplicated or renamed. WPF Locator Doctor checks your app for you.

Today: the testability scorecard. It checks whether the controls a tester needs (buttons, text boxes, lists, menus, tabs…) have good AutomationIds: are they there, set on purpose, unique, still the same as last time, and actually visible to test tools. It gives each screen and the whole app a score from 0 to 100 and a grade from A to F. Every problem comes with the file, the line, and the line of XAML to add.

New: an MCP server so AI assistants (Claude Code, Copilot, Cursor…) can score your project and add the missing IDs for you, and, on Windows, explore the running app: see the screen as test tools do, get ranked locators that are checked to find exactly one element, click, type, wait and take screenshots. See Use it from an AI assistant.

Coming next: self-healing for broken locators in FlaUI / Appium tests, and automatic pull requests that fix the test code or add the missing IDs to the app. See docs/research-analysis.md for the research and plan.

Works with any WPF app (.NET Framework or .NET). Built on Windows UI Automation and FlaUI.

What you get

This is a real scan of the included practice app (shortened):

$ wpf-locator-doctor scan-source samples/PracticeApp

Overall: grade B, score 86.5/100. Good. A few gaps to fix.

  ID coverage                 80.6%   25 of 31 controls have an AutomationId.
  ID quality                  90.4%   19 set on purpose, 5 borrowed from x:Name, 1 look generated.
  Uniqueness and rows         87.1%   1 ID(s) used more than once; 1 of 2 data lists have identifiable rows.
  Visible to test tools       93.8%   2 invisible control(s), 0 opaque area(s).
  Readable names              89.7%   26 of 29 controls have a readable name.

Screens (worst first):
  B     80.5  MainWindow  (21 controls, 14 problems)
  A     92.5  AddressPanel  (3 controls, 3 problems)
  A      100  SettingsWindow  (7 controls, 0 problems)

Problems: 18 (6 high, 4 medium, 8 low)
  HIGH   WT001 Button has no AutomationId.  [MainWindow.xaml:29]
  HIGH   WT004 "ActionButton" is used 2 times on this screen (line 44, line 45).  [MainWindow.xaml:44]
  HIGH   WT006 StarRating derives from Control and doesn't override OnCreateAutomationPeer, so test tools can't see it.  [Controls/StarRating.cs:13]
  MEDIUM WT003 Button "Clear" has the ID "Button_1", which looks machine-generated.  [MainWindow.xaml:27]
  MEDIUM WT005 Rows in ListBox "Recent orders" have no unique ID.  [MainWindow.xaml:57]
  …

The full report (testability-report.md) tells you exactly what to add:

  • High: Control has no AutomationId. Button has no AutomationId. (MainWindow.xaml:29)
    • Fix: Add AutomationProperties.AutomationId="RefreshButton" to this element.
  • Medium: ID looks machine-generated. Button "Clear" has the ID "Button_1", which looks machine-generated. (MainWindow.xaml:27)
    • Fix: Replace it with a meaningful ID, e.g. AutomationProperties.AutomationId="ClearButton".

Two ways to scan

Source scan (scan-source)Live scan (scan-live)
ReadsThe project's XAML and C# filesThe running app, through Windows UI Automation (the same thing test tools use)
Runs onWindows, macOS, LinuxWindows only, with an unlocked desktop
CoversEvery screen in the project, even ones nobody openedOnly windows that are open, and list rows that are on screen
Good forQuick checks on every code change; exact file and line to fixThe true picture of what tests will see, including third-party controls

Quick start

Source scan (Windows, macOS, Linux)

Install from NuGet. You need the .NET SDK, version 10 or newer:

dotnet tool install -g wpf-locator-doctor --prerelease

Then scan a project:

wpf-locator-doctor scan-source path/to/YourWpfProject

Live scan (Windows)

Download wpf-locator-doctor-live-win-x64.zip from the latest release, unzip it, and run:

wpf-locator-doctor.exe scan-live --exe path/to/YourApp.exe --source path/to/YourWpfProject

It needs the .NET 10 Desktop Runtime. The Windows download also includes the source scan.

Run from the source code

Clone this repo and try it on the included practice app, which has one example of every problem:

dotnet run --project src/WpfLocatorDoctor.Cli -f net10.0 -- scan-source samples/PracticeApp

For the live scan from source, use -f net10.0-windows and scan-live instead.

Reports

Both scans write two files into ./testability-report/:

  • testability-report.md: the report for people (grade, what each check found, every problem with its fix).
  • testability-report.json: the same data for tools. Pass it as --baseline next time to check that no IDs disappeared.

Use it from an AI assistant (MCP server)

The MCP server gives your AI assistant tools to work on your app's locators. Then just ask, for example: "Score src/MyApp and add the missing AutomationIds to the worst screen." or "Start the app, open the settings window and give me the best locator for its OK button."

WhereToolsGet it
Any OS (reads source code)score_source, list_problems, suggest_xaml_fixes (exact line edits with unique new IDs), compare_to_baseline, explain_rulesNuGet package wpf-locator-doctor-mcp, run with dnx
Windows (adds the running app)all of the above, plus open_app, snapshot_screen, recommend_locators, check_locator, act, wait_for, take_screenshot, score_live_app, close_appwpf-locator-doctor-mcp-win-x64.zip or .mcpb on the releases page

Add it to Claude Code (VS Code and Cursor are similar; see the guide):

claude mcp add wpf-locator-doctor -- dnx wpf-locator-doctor-mcp --yes

On Windows, point it at the downloaded server instead:

claude mcp add wpf-locator-doctor -- C:\tools\wpf-locator-doctor-mcp\wpf-locator-doctor-mcp.exe

The packages arrive with the first release that includes the MCP server; until then, build it from this repository (the guide shows how). Full guide, with VS Code and Cursor setup, safety settings and example answers: docs/mcp-server.md.

Using it in a build pipeline

wpf-locator-doctor scan-source src/MyApp --min-score 75 --baseline last-report.json --quiet

Exit codes: 0 OK · 1 score below --min-score · 2 wrong usage · 3 the scan failed.

How the score works

Each check gives a percentage. The score is the weighted average of the checks that could be measured.

CheckWeightWhat it asks
ID coverage30Of everything a user can click, type into or select, how much has an AutomationId?
ID quality15Were IDs set on purpose (best), borrowed from x:Name (OK), borrowed from x:Uid, or do they look machine-generated like Button_12 (bad)?
Uniqueness and rows20Is each ID used once per screen? Can the rows in each list be told apart?
Stability15Are the IDs from the previous report still there? (Only measured with --baseline.)
Visible to test tools10Are there custom controls that test tools can't see at all?
Readable names10Does each control have a readable label? (Also matters for screen-reader users.)

Grades: A 90+ · B 75–89 · C 60–74 · D 40–59 · F below 40.

Run wpf-locator-doctor rules to list every problem type (WT001–WT012) with a plain-English explanation.

Why "where the ID came from" matters

When a test asks a WPF control for its AutomationId, WPF returns the first of these that is set:

  1. AutomationProperties.AutomationId: set on purpose for testing. Best.
  2. x:Uid: meant for translation tools, often auto-generated (Button_12), so it changes.
  3. x:Name: the developer's own name for the control, which they may rename without knowing a test uses it.

Why some controls are invisible to test tools

A custom control built directly on Control, ContentControl, ButtonBase, RangeBase, TextBoxBase or HeaderedContentControl doesn't announce itself to UI Automation unless it overrides OnCreateAutomationPeer. Test tools can't see it, and any AutomationId set on it goes nowhere. The source scan reads the C# code to find these.

Project layout

src/WpfLocatorDoctor.Core     The engine: XAML + C# scanning, scoring, reports, and the rules for judging
                              each element of a running app. No Windows dependency, so it runs (and is tested) anywhere.
src/WpfLocatorDoctor.Live     A thin Windows-only layer: starts or attaches to the app, reads its UI and carries out
                              actions through FlaUI, and hands everything to the Core rules.
src/WpfLocatorDoctor.Cli      The wpf-locator-doctor command (CliApp.cs holds the logic; Program.cs only starts it).
src/WpfLocatorDoctor.Mcp      The MCP server for AI assistants. Only describes the tools; the answers come from Core (Assistant/).
                              Built twice: cross-platform (source tools, NuGet) and Windows (adds the live tools).
samples/PracticeApp           A small WPF app with one example of each problem (and good examples).
tests/                        Automated tests (run with: dotnet test WpfLocatorDoctor.slnx).
docs/mcp-server.md            How to set up and use the MCP server.
docs/research-analysis.md     Research behind this project.

The rule of thumb: anything that makes a decision lives in Core and has tests. The Windows-only layer only reads values from the screen, so as little as possible depends on having Windows to test it.

Tests and code quality

dotnet test WpfLocatorDoctor.slnx
WhatHow it is testedWhere
Reading XAML and C# (source scan)Small XAML/C# snippets, temporary project folders, and the practice appXamlSourceScannerTests, CodeBehindAnalyzerTests, EdgeCaseTests, PracticeAppTests
Scores, grades and problem reportsHand-built scans with known answersScorerTests, EdgeCaseTests
Live scan decisions (what counts as a control, rows, opaque areas, limits)A fake UI tree, so no Windows or running app is neededLiveTreeWalkerTests
ID suggestions and reports (Markdown, JSON, terminal)Direct checks of the output textHeuristicsAndReportTests, EdgeCaseTests
The command line: every command, option, error message and exit codeRuns the command in-process against temporary folderstests/WpfLocatorDoctor.Cli.Tests
The MCP tools' answers: scores, filters, suggested IDs, exact XAML edits, baseline comparison, error messagesThe practice app and temporary projects; one test applies every suggested edit and re-scoresProjectDoctorTests, XamlFixPlannerTests
The live MCP tools' decisions: what a snapshot shows, locator ranking and code, matching, how to click or type, waiting, allowed appsA fake app, so no Windows or running app is neededLiveSessionTests
The MCP server as an assistant sees it: tool list, JSON answers, error messagesStarts the real server and talks to it with the official MCP clienttests/WpfLocatorDoctor.Mcp.Tests
The live scan and the live MCP tools against a real running appGitHub Actions starts the practice app on Windows, scans it, then drives it through the MCP server (snapshot, locators, type, menu, wait, screenshot, score).github/workflows/ci.yml (live-scan job), LiveToolsTests

Quality checks run on every build: .NET's recommended code-analysis rules are on, and any warning fails the build. GitHub Actions builds and tests on Linux and Windows for every push and pull request.

Known limits

  • The source scan can't see controls created only in C# code, and it guesses third-party controls (Telerik, DevExpress…) from their class names.
  • The live scan only sees open windows and the list rows on screen. Open other screens and scan again.
  • The live scan runs in CI on every push: it starts the practice app on Windows, scans it, and fails the build if the scan breaks. It has not yet been tried on large real-world apps, so expect rough edges there.

License

MIT. Free to use, change and share, including in commercial projects.

NUGET
wpf-locator-doctor-mcp
Install Command
# nuget: wpf-locator-doctor-mcp
Runtime: dnx
MCPB
https://github.com/swechhap/wpf-locator-doctor/releases/download/v0.2.0/wpf-locator-doctor-mcp-win-x64.mcpb
Install Command
# mcpb: https://github.com/swechhap/wpf-locator-doctor/releases/download/v0.2.0/wpf-locator-doctor-mcp-win-x64.mcpb