Uno Testing
The Uno App MCP lets you drive the real running app: launch it, read its visual tree, act on elements through automation peers, and check what actually rendered. Use it to prove a change works instead of inferring from source. The failure modes here are mostly timing and stale references, so the rules below are about when to refresh and when to wait.
Prerequisite
Confirm the app tools exist before starting. Some clients list the uno_app_* tools directly; others list only uno_health, uno_discover_tools, and uno_execute_tool. In that case call uno_discover_tools to see the app tools and run each one as uno_execute_tool(toolName: "uno_app_start", arguments: {...}). If uno_health reports toolCount: 0 or issues, or a tool a step names is not offered, read references/availability.md before concluding anything. When the tools stay unavailable, and for Release builds, verify through the platform accessibility tree on Windows or Android (references/without-app-mcp.md); only where that is not possible either, fall back to static review of the XAML and Model code, labelled as unverified. Do not describe test results you did not obtain.
Workflow
Verify behaviour on a Debug build with the App MCP. Use a Release build only when the task requires one (a spec that asks for it, or a Release-only defect such as trimming or AOT), and then drive it through the accessibility tree (references/without-app-mcp.md) instead of repeating every check with screenshots.
- Find the app, or build once and start once. Call
uno_app_get_runtime_infofirst: an instance that is already connected is the app under test, with no build and no start; go to step 2. Otherwise make sure Hot Design will not open over the app (see the first critical rule), build once withdotnet build -f net10.0-desktop(or the app's own TFM, read from<TargetFrameworks>) so compile errors surface as build output, thenuno_app_start(projectPath, targetFramework, connectionTimeoutSeconds: 120)with the full.csprojpath, andwindowSizewhen a check or a deliverable needs a window size (see the window-size rule). This is the only build and the only start of a verification pass on a platform: every fix after it goes through step 8, not through another build. - Wait for the connection, then for Hot Reload; do not restart. If the start times out, the app is usually still launching. Poll
uno_app_get_runtime_infoevery few seconds and calluno_devserver_diagnosticsif it keeps reporting no instance. Callinguno_app_startagain does not stop it: it builds and launches a second instance. An edit made before Hot Reload is ready is dropped and not replayed. When discovery listsuno_app_hot_reload_status, the start already waits for it and its result has aHot Reload:line; if that line says it is still initializing, calluno_app_hot_reload_status(waitForReady: true)before the first edit. Without that tool, make the first edit at least 15 s after the start returns. - Baseline.
uno_app_visualtree_snapshot(detail: "normal")plusuno_app_get_screenshot(path: …)before touching anything, so failures have a before/after. This is the one routine snapshot; from here on, locate and assert withuno_app_find_elements. - Locate by selector; snapshot only to discover or assert. Every element tool takes
automationId(the XAML'sAutomationProperties.AutomationId) orname(x:NameorAutomationProperties.Name) in place ofelementRef, resolved against the live tree at call time: no snapshot first, nothing goes stale, and it survives navigation and hot reload. You know the ids from the XAML you wrote or read, so act straight away. Matching is exact and case-sensitive; 0 matches is an error naming the value, N matches is an error listing the candidates as snapshot lines with fresh handles (act on one byelementRef, or addscopeRefto search under one container). When no id or name exists, read the snapshot: each line isType ^handle #Name :line [patterns] "text"; the handle is the bare token after^(elementRef: "5k"forButton ^5k, not"^5k"), and it dies with the next UI change. - Act.
uno_app_element_peer_default_action(automationId | name | elementRef)always runsinvoke, so use it only on[i]elements (Button,HyperlinkButton); on anything else it fails. For the other letters useuno_app_element_peer_action(automationId | name | elementRef, action):ttoggle,xexpand/collapse,sselect,vsetValue (fills aTextBoxwithout keyboard focus),rsetRangeValue.uno_app_type_text(text, automationId | name | elementRef)focuses that control and types into it in one call.ListViewItemshows noson Uno (and[i]only when the list hasIsItemClickEnabled="True", where the default action raisesItemClick), so select it by pointer or keyboard and read{selected}fromuno_app_find_elements. An item that is off screen or not loaded yet is reached withuno_app_scroll_into_view(automationId | name | elementRef, index | itemText): it scrolls the list, loading further pages the way a user's scroll does, and returns the list's{items=N}and the item's line with a fresh handle and@@x,y,w,hbounds to click. Withoutuno_app_element_peer_action(Community), seereferences/availability.md. - Wait, then check, in one call.
uno_app_find_elements(automationId | name | text | type, waitForMs: 2000)re-checks the live tree every 100 ms until something matches (max 10 s) and returns only the matches: a count line, then one snapshot line per match with its{state}:disabled,checked|unchecked|indeterminate,selected,expanded|collapsed,value=…,items=N,selectedIndex=N, and!hiddenwhen collapsed. That is the check after an action: the next page's title byautomationId, the submit button no longer{disabled}, the list at{items=12}, the toggle{checked}, the error text bytextwithtextContains: true. Zero matches is a result, not an error, so absence is asserted the same way. No screenshot and no re-snapshot are needed to know whether the action worked; take a screenshot afterwards only when the question is visual (layout, colours, a comparison against a reference). Several selectors combine with AND,scopeRefbounds the search to one container, andincludeHidden: falseexcludes collapsed elements. To wait for a state rather than for a match, adduntil:"items>=40"after a scroll that loads a page,"absent"for a loading view to go,"visible","enabled","selected","checked","value>=50","text contains Saved".waitForMsthen defaults to 10000, and the count line endsuntil …: metorNOT met after Nsover the last state seen: NOT met is the answer, so read the state it shows instead of asking again. Handles from an earlier snapshot are invalid after UI changes; selectors are not. - Assert. Presence, absence, text and the
{state}tokens come fromuno_app_find_elements; the tree shows bindings (Text={Title}), not current property values, so for a value the state group does not carry read the DataContext withuno_app_get_element_datacontextby selector. A screenshot is not how a state is read. Without that tool (Community), report DataContext assertions as not run. Save a screenshot of the final state. - Fix in the running app, then confirm. When a check fails and you edit a
.xamlor.csfile, do not build, close or start: save, then calluno_app_hot_reload_status(file: "<edited file>", waitForMs: 10000).appliedmeans the app now runs your change (a C# edit recreates the current page, so navigate back to the state under test), and you go back to step 6 on that state.NOT appliedcomes with the compiler's diagnostics for that edit: fix the file and save again; that result is your build output.RudeEdit, anInternalError(the DevServer failed, not your file: do not save it again), orno Hot Reload operation coveredthe file after a second save, is the one signal that a restart is needed, and until it no later edit applies: finish the edits that belong with it, thenuno_app_restartonce (oruno_app_close, then step 1, when the App MCP does not offer it). ARudeEditthat citesUNOHR0001is a compiler emit failure: undo that change and save to keep going, or restart. Decide from that result, never from a guess about what Hot Reload can carry: new members, new classes, lambdas and generated code all apply in most sessions. - Report and clean up. State each assertion with expected vs actual, attach screenshots, and
uno_app_closeon desktop unless the user wants the app left open. On failure, also capture adetail: "full"tree and the DataContext.
Topic map
| Task | Read |
|---|---|
| Tool catalogue, parameters, lifecycle, and the four base test patterns (click, form, navigation, visual regression) | references/ui.md |
| Assertion patterns: page loaded, button state, text, list counts, dialogs, validation errors, navigation, wait/retry loops, failure diagnostics | references/assertions.md |
| Interaction recipes: text entry and clearing, keyboard navigation, lists and multi-select, ComboBox, sliders, dialogs, scrolling, context menus | references/INTERACTION-PATTERNS.md |
Reading the snapshot text format, detail/includeHidden/elementRef, element-finding strategies, recycled list handles |
references/VISUAL-TREE-GUIDE.md |
uno_health problems, missing app tools, licensing tiers and the Community fallbacks |
references/availability.md |
Release builds, CI, or no App MCP: what Windows UI Automation and Android uiautomator expose, finding, acting and asserting through them |
references/without-app-mcp.md |
Critical rules
- Accessibility first, on every path. Find controls in the element tree (
uno_app_find_elementsthrough the App MCP, or Windows UI Automation and Androiduiautomatorwithout it), act on them through their name, and assert on what the tree reports. A screenshot is a visual assertion or evidence, never the way to find a control or confirm its state while the tree can. - Act, then find; screenshot only for the eye. The check that follows an action is
uno_app_find_elementswithwaitForMson the element whose state should have changed, about a hundred characters back. A screenshot after every click is the expensive habit this replaces: it costs an image in context each time and answers less. Screenshots remain for visual checks against a reference, for the before and after evidence of step 3 and step 8, and for the deliverables a task asks for. - Keep Studio's own UI out of the app. Before the first
uno_app_start,App.xaml.csshould callMainWindow.UseStudio(showHotReloadIndicator: false, launchHotDesignOnStart: false);under#if DEBUG. With no arguments the Hot Reload indicator and the Hot Design button sit over the app in every screenshot and under pointer clicks, and Hot Design can open over the app on launch: screenshots then show the designer, clicks land on it, and the visual tree does not show it. Hot Reload and the App MCP keep working with the arguments. In an app you created in this session, make the change and mention it in your report. In an existing app, ask the developer first; if they decline, check the first screenshot for the designer, ask them to exit Hot Design if it is there, and report any check it blocked as not run. If Hot Design still opens, theUNO_HOTDESIGN_LAUNCHenvironment variable or theUnoHotDesignLaunchMSBuild property is set, and takes precedence. - Edit the running app; the status result, not your guess, decides when to start again. After the start, edits to existing
.xamland.csfiles reach the app through Hot Reload in 2 to 4 s, on desktop and Android alike (workflow step 8). A start is right only for: launch arguments, platform or app data; a Release build; the.csprojor packages; code that already ran at startup (OnLaunched, host configuration, DI registrations); and aRudeEdit,InternalErroror uncovered edit the status reported. Everything else, including a new class, member, file, event handler or generated code, goes through Hot Reload first. A dropped edit is not carried by a later edit of another file: if the status says no operation covered the file, check it saved and edit that file again; only if it still reports nothing, start the app. - One app instance, and close it before you build. Build only before a start the previous rule allows; a passing Hot Reload status is the build. A running app locks its
binfolder, sodotnet buildor anotheruno_app_startfails withMSB3026/MSB3027copy errors.uno_app_closefirst, and do not launch the app yourself withdotnet runor a script while the App MCP drives it. - Save screenshots to files; read one back only for a visual assertion. Without
paththe image comes back in the tool result and stays in context for every later call. Save one before and after, on pass and on fail: that evidence makes the report reviewable and regressions diagnosable. To save a file, the path must be inside the App MCP's workspace, which is the selected solution's folder (effectiveWorkspaceDirectoryinuno_health), and if the save fails with "Could not find a part of the path", create the folder and retry. Copy the file elsewhere afterwards if the task needs it there. - Size the window with the App MCP, never with code or scripts.
uno_app_start(windowSize: "1280x800")opens the app at a size anduno_app_resize(width, height)changes it while it runs: both set the client area in logical pixels, which is what layout and screenshots see, and return the size applied (and say so when the screen limited it). A narrow and a wide layout are twouno_app_resizecalls, not two starts.windowSizeis applied once the app connects, so it needsconnectionTimeoutSeconds, anduno_app_restartkeeps it. Desktop only. Do not resize fromOnLaunchedor with a UI Automation or Win32 script. - Selectors do not expire; handles do. Act by
automationIdornameand nothing needs refreshing. When you must use a handle, any action that changes UI invalidates it: re-snapshot before the next interaction, and remember recycledListViewitems change handles on scroll. - Never assert during a transient state. A
ProgressRing,ProgressBar, loading text, or disabled submit button means the async work is still running: wait for it to clear in one call,uno_app_find_elements(automationId: "<indicator>", until: "absent"), then assert. To capture the state itself (a loading screenshot), wait for it withuntil: "visible", take the screenshot, then wait for"absent". Asserting early produces false failures and false passes. - Selectors, then handles, then coordinates. A selector is one call and survives everything; a handle survives until the next UI change; a coordinate click survives neither layout changes nor DPI differences. When coordinates are unavoidable, take a
detail: "full"snapshot withoutelementRefand click the centre of the element's@@x,y,w,hbounds: the bounds are relative to the snapshot root, and clicks are relative to the window. - Give every control an automation id.
AutomationProperties.AutomationId, unique on its page, is theautomationIdselector here and UI Automation'sAutomationIdin Release verification;x:NameorAutomationProperties.Nameis thenameselector, shown as#Namein the tree, and the only thing Android's accessibility tree exposes (content-desc), so a control a test touches gets both when its text may vary. An element with neither is found only by text or position. In an app you created, add them as you write the XAML; in an existing app, suggest them. - Keep the default
detail: "compact"or"normal"."full"adds framework nodes, bounds, and offscreen flags and is large; use it for coordinates and failure diagnosis. A hidden element (!hidden) only proves something is collapsed; never interact with it. - Be specific. Assert exact text, counts, and enabled states rather than "element exists":
{items=12},{checked}, not{disabled}. Absence is0 matchedwithincludeHidden: false. - Older App MCP.
until,uno_app_scroll_into_view,uno_app_resizeandwindowSizeneed an App MCP that lists them (uno_discover_tools, or the parameters ofuno_app_find_elementsanduno_app_start); without them, seereferences/availability.md. - Feed states are three assertions, not one. For a
FeedView, check the progress template appears, then the value or error template replaces it, then the bound data matches via DataContext.
Related skills
uno-mvuxfor what the loading, error, and value states of aFeedViewshould contain and how the ViewModel exposes them.uno-navigationfor the routes and regions a navigation test should land on.uno-toolkitfor the control types (TabBar,NavigationBar,CardContentControl) you will see in the visual tree.