# Uno Testing

> Automated UI testing and verification of a running Uno Platform app through the Uno App MCP (the uno_app_* tools): start the app, take a visual-tree snapshot, find elements by automation id, x:Name, text or type, click, type, press keys, scroll, drive navigation flows, read an element's state or DataContext, capture screenshots, and assert on text, visibility, enabled state, list counts, dialogs, layout, and FeedView loading/error/value states. Use whenever the user says check that, verify, test the UI, does it render, click through, make sure the button works, take a screenshot, why is X not visible, or asks for end-to-end or visual regression testing of an Uno app. Also use after any UI change you made when the uno_app_* tools are available, so the result is confirmed in the real app rather than assumed from the code. Before verifying a Release build, where the App MCP is not available, load this skill: it gives the steps for that path.

- Skill: `unoplatform/uno-testing` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx get-skill add unoplatform/uno-testing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/unoplatform/uno-testing/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: unoplatform (https://skillmd.com/u/unoplatform)
- Updated: 2026-11-11
- Page: https://skillmd.com/skills/unoplatform/uno-testing

---


# 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.

1. **Find the app, or build once and start once.** Call `uno_app_get_runtime_info` first: 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 with `dotnet build -f net10.0-desktop` (or the app's own TFM, read from `<TargetFrameworks>`) so compile errors surface as build output, then `uno_app_start(projectPath, targetFramework, connectionTimeoutSeconds: 120)` with the full `.csproj` path, and `windowSize` when 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.
2. **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_info` every few seconds and call `uno_devserver_diagnostics` if it keeps reporting no instance. Calling `uno_app_start` again 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 lists `uno_app_hot_reload_status`, the start already waits for it and its result has a `Hot Reload:` line; if that line says it is still initializing, call `uno_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.
3. **Baseline.** `uno_app_visualtree_snapshot(detail: "normal")` plus `uno_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 with `uno_app_find_elements`.
4. **Locate by selector; snapshot only to discover or assert.** Every element tool takes `automationId` (the XAML's `AutomationProperties.AutomationId`) or `name` (`x:Name` or `AutomationProperties.Name`) in place of `elementRef`, 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 by `elementRef`, or add `scopeRef` to search under one container). When no id or name exists, read the snapshot: each line is `Type ^handle #Name :line [patterns] "text"`; the handle is the bare token after `^` (`elementRef: "5k"` for `Button ^5k`, not `"^5k"`), and it dies with the next UI change.
5. **Act.** `uno_app_element_peer_default_action(automationId | name | elementRef)` always runs `invoke`, so use it only on `[i]` elements (`Button`, `HyperlinkButton`); on anything else it fails. For the other letters use `uno_app_element_peer_action(automationId | name | elementRef, action)`: `t` toggle, `x` expand/collapse, `s` select, `v` setValue (fills a `TextBox` without keyboard focus), `r` setRangeValue. `uno_app_type_text(text, automationId | name | elementRef)` focuses that control and types into it in one call. `ListViewItem` shows no `s` on Uno (and `[i]` only when the list has `IsItemClickEnabled="True"`, where the default action raises `ItemClick`), so select it by pointer or keyboard and read `{selected}` from `uno_app_find_elements`. An item that is off screen or not loaded yet is reached with `uno_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,h` bounds to click. Without `uno_app_element_peer_action` (Community), see `references/availability.md`.
6. **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 `!hidden` when collapsed. That is the check after an action: the next page's title by `automationId`, the submit button no longer `{disabled}`, the list at `{items=12}`, the toggle `{checked}`, the error text by `text` with `textContains: 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, `scopeRef` bounds the search to one container, and `includeHidden: false` excludes collapsed elements. To wait for a state rather than for a match, add `until`: `"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"`. `waitForMs` then defaults to 10000, and the count line ends `until …: met` or `NOT met after Ns` over 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.
7. **Assert.** Presence, absence, text and the `{state}` tokens come from `uno_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 with `uno_app_get_element_datacontext` by 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.
8. **Fix in the running app, then confirm.** When a check fails and you edit a `.xaml` or `.cs` file, do not build, close or start: save, then call `uno_app_hot_reload_status(file: "<edited file>", waitForMs: 10000)`. `applied` means 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 applied` comes with the compiler's diagnostics for that edit: fix the file and save again; that result is your build output. `RudeEdit`, an `InternalError` (the DevServer failed, not your file: do not save it again), or `no Hot Reload operation covered` the 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, then `uno_app_restart` once (or `uno_app_close`, then step 1, when the App MCP does not offer it). A `RudeEdit` that cites `UNOHR0001` is 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.
9. **Report and clean up.** State each assertion with expected vs actual, attach screenshots, and `uno_app_close` on desktop unless the user wants the app left open. On failure, also capture a `detail: "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_elements` through the App MCP, or Windows UI Automation and Android `uiautomator` without 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_elements` with `waitForMs` on 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.cs` should call `MainWindow.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, the `UNO_HOTDESIGN_LAUNCH` environment variable or the `UnoHotDesignLaunch` MSBuild 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 `.xaml` and `.cs` files 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 `.csproj` or packages; code that already ran at startup (`OnLaunched`, host configuration, DI registrations); and a `RudeEdit`, `InternalError` or 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 `bin` folder, so `dotnet build` or another `uno_app_start` fails with `MSB3026`/`MSB3027` copy errors. `uno_app_close` first, and do not launch the app yourself with `dotnet run` or a script while the App MCP drives it.
- **Save screenshots to files; read one back only for a visual assertion.** Without `path` the 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 (`effectiveWorkspaceDirectory` in `uno_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 and `uno_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 two `uno_app_resize` calls, not two starts. `windowSize` is applied once the app connects, so it needs `connectionTimeoutSeconds`, and `uno_app_restart` keeps it. Desktop only. Do not resize from `OnLaunched` or with a UI Automation or Win32 script.
- **Selectors do not expire; handles do.** Act by `automationId` or `name` and nothing needs refreshing. When you must use a handle, any action that changes UI invalidates it: re-snapshot before the next interaction, and remember recycled `ListView` items 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 with `until: "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 without `elementRef` and click the centre of the element's `@@x,y,w,h` bounds: 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 the `automationId` selector here and UI Automation's `AutomationId` in Release verification; `x:Name` or `AutomationProperties.Name` is the `name` selector, shown as `#Name` in 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 is `0 matched` with `includeHidden: false`.
- **Older App MCP.** `until`, `uno_app_scroll_into_view`, `uno_app_resize` and `windowSize` need an App MCP that lists them (`uno_discover_tools`, or the parameters of `uno_app_find_elements` and `uno_app_start`); without them, see `references/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-mvux` for what the loading, error, and value states of a `FeedView` should contain and how the ViewModel exposes them.
- `uno-navigation` for the routes and regions a navigation test should land on.
- `uno-toolkit` for the control types (`TabBar`, `NavigationBar`, `CardContentControl`) you will see in the visual tree.

