A UI test can fail before it even reaches the code you intended to test.
This is especially common with UWP and WinUI 3 applications because many UI objects are tied to the application's real UI thread and dispatcher. A test that creates a Button, Grid, Window, or another XAML object from an ordinary test thread may compile successfully and still fail at runtime.
That is the problem behind the latest MSTest improvements for UWP and WinUI 3 testing. With MSTest 4.5 and Microsoft.Testing.Platform 2.5, MSTest can run UI-focused tests using the application's real UI dispatcher instead of treating UI testing as simply another test method running on an arbitrary test thread.
The change is important because UI testing is not just about asserting visual properties. The test must run within the same threading and application-lifetime model the UI framework expects.
Why UI Tests Need the Real UI Thread
Consider a simple WinUI 3 test:
[TestClass]
public class MainWindowTests
{
[UITestMethod]
public void CanCreateGrid()
{
var grid = new Grid();
Assert.IsNotNull(grid);
}
}
At first glance, this looks like an ordinary unit test.
It is not.
WinUI types are associated with the UI thread and dispatcher. The test needs to execute in the correct application context for UI operations to behave reliably. Microsoft specifically describes the need for the application's real UI dispatcher rather than merely putting the test on an arbitrary single-threaded apartment thread.
That distinction matters because these are not equivalent:
STA thread
≠
Application UI thread
An STA thread satisfies a threading model requirement, but it does not automatically provide the dispatcher, application lifetime, and UI context expected by a WinUI application.
What UITestMethod Provides
MSTest provides the UITestMethod attribute for UI-oriented tests.
A basic test looks like this:
[TestClass]
public class MainWindowTests
{
[UITestMethod]
public void GridCanBeCreatedOnTheUIThread()
{
var grid = new Grid();
Assert.IsTrue(grid.DispatcherQueue.HasThreadAccess);
}
}
The important part is not the assertion itself. It verifies that the test is actually executing with access to the UI dispatcher.
For asynchronous tests, the same model can be used:
[TestClass]
public class MainWindowTests
{
[UITestMethod]
public async Task GridCanBeCreatedOnTheUIThread()
{
await Task.Yield();
var grid = new Grid();
Assert.IsTrue(grid.DispatcherQueue.HasThreadAccess);
}
}
The asynchronous case is important because UI code frequently performs asynchronous operations. A test that begins on the correct thread but loses the required context after an await can still produce confusing failures.
The MSTest UI test model is intended to preserve the application's UI-thread context throughout the test.
MSTest and Microsoft.Testing.Platform
The new support is closely tied to Microsoft.Testing.Platform, commonly abbreviated as MTP.
MTP is Microsoft's newer test platform and is designed as a more extensible test execution system than the older VSTest architecture. Current MSTest guidance recommends MTP with MSTest.Sdk for new projects.
For UWP and WinUI 3, this matters because the test host itself has to participate in the application's lifecycle.
The architecture is roughly:
MSTest
|
v
Microsoft.Testing.Platform
|
v
Application Test Host
|
v
UI Dispatcher
|
v
UWP / WinUI 3 UI
The test is therefore not simply an external process poking at an application. The application can act as the test host, giving the test framework access to the UI thread and application lifetime.
That architectural difference is one of the most important parts of the feature.
UWP and WinUI 3 Are Not the Same Deployment Model
A common mistake is to treat every Windows XAML application as if it uses the same hosting model.
UWP and WinUI 3 have different application models.
Classic UWP and modern .NET UWP applications run inside an AppContainer. WinUI 3 desktop applications can be packaged or unpackaged, and their trust and activation models can differ. Microsoft therefore provides different execution paths depending on the application model.
A useful mental model is:
UWP
└── AppContainer
WinUI 3
├── Unpackaged
├── Packaged full-trust
└── AppContainer scenarios
The test runner has to know which model it is dealing with.
That is why simply adding a test project and referencing the application is not always enough.
Testing Unpackaged WinUI 3 Applications
An unpackaged WinUI 3 application is relatively straightforward because it behaves more like a regular Windows executable.
With the newer Microsoft.Testing.Platform integration, the test host can start the application executable directly for supported unpackaged scenarios.
Conceptually:
MTP
|
+-- Start WinUI executable
|
+-- Application creates UI dispatcher
|
+-- MSTest runs UI test
This avoids some of the package-registration complexity associated with packaged applications.
If the application does not require package identity, an unpackaged test model can therefore be simpler.
That does not mean every application should be converted to unpackaged simply for testing. Package identity can be required for application features, deployment behavior, or APIs that depend on MSIX packaging.
The deployment model should follow application requirements, not testing convenience alone.
Testing Packaged WinUI 3 Applications
Packaged applications introduce another layer.
A packaged application may require:
The testing infrastructure therefore has to activate the correct application rather than simply launching an executable.
MSTest and Microsoft.Testing.Platform provide support for the relevant WinUI application models, with package activation handled through the testing infrastructure for supported configurations.
This is also an area where developers need to pay attention to the exact MSTest and MTP versions they are using. Some packaged-app functionality has had preview or evolving support, so blindly copying a configuration from an older sample can lead to confusing failures.
The application model and test platform versions should be treated as a matched configuration.
UWP Requires Different Handling
UWP is especially important because it runs inside AppContainer.
Microsoft's current MSTest guidance distinguishes UWP from packaged full-trust WinUI 3 applications. UWP tests require an appropriate UWP execution path, and the MTP packaged-app launcher should not be treated as a generic solution for AppContainer applications.
For classic UWP and modern .NET UWP, the test project and application must be configured according to the UWP project model.
For example, modern .NET UWP projects use the appropriate UWP project configuration and target framework rather than behaving like a normal desktop .NET application.
This distinction becomes particularly important in CI. A test that works on a developer workstation can fail on a build agent if the agent does not provide the required Windows application model, package policy, or development settings.
Why Async UI Tests Need Extra Attention
UI applications are asynchronous by nature.
A typical test might look like:
[UITestMethod]
public async Task LoadsCustomerDetails()
{
await viewModel.LoadAsync();
Assert.IsTrue(viewModel.IsLoaded);
}
The important question is what happens after await.
If the continuation executes without the required UI context, the test may eventually attempt to interact with a UI object from the wrong thread.
This is one reason MSTest's UI-specific execution model is more appropriate for UWP and WinUI than trying to reproduce the same behavior with a generic test attribute.
For Windows UI technologies more broadly, MSTest also provides mechanisms for preserving STA synchronization context in appropriate scenarios. However, UITestMethod is specifically designed for UWP and WinUI applications that require UI-thread access.
What a Real UI Test Should Validate
It is easy to write UI tests that simply prove an object can be instantiated.
That has limited value.
A more useful test checks behavior:
[TestClass]
public class CustomerViewTests
{
[UITestMethod]
public async Task LoadingCustomerUpdatesStatus()
{
var viewModel = new CustomerViewModel();
await viewModel.LoadAsync();
Assert.IsTrue(viewModel.IsLoaded);
Assert.IsNotNull(viewModel.Customer);
}
}
If the test needs actual UI controls, then those controls should be created and manipulated through the correct UI context.
The key is to test behavior that is difficult to validate through ordinary unit tests.
For example:
Unit test
↓
Does CustomerViewModel.LoadAsync return correct state?
UI test
↓
Does the WinUI view correctly interact with that state?
Keeping those responsibilities separate prevents the UI test suite from becoming unnecessarily large.
Do Not Turn Every Test Into a UI Test
This is one of the most important practical considerations.
Suppose you have:
CustomerService
CustomerRepository
CustomerViewModel
CustomerPage
You should not test every method through the UI.
A better split is:
CustomerService
→ Unit tests
CustomerRepository
→ Integration tests
CustomerViewModel
→ Unit tests
CustomerPage
→ UI tests
UI tests are generally more expensive because they require the application host, UI thread, dispatcher, and Windows environment.
If a business rule can be tested without launching the UI, test it without the UI.
The UI test suite should focus on behavior that actually depends on the UI framework.
Common Mistakes
Using a Normal TestMethod for UI Objects
A developer may write:
[TestMethod]
public void CreatesButton()
{
var button = new Button();
}
The code may compile, but the test does not express the correct UI-thread requirement.
For UWP and WinUI UI testing, use UITestMethod where the test requires UI-thread access.
Assuming STA Is Enough
This is a subtle but important mistake.
Putting a test on an STA thread does not automatically reproduce the application's UI dispatcher environment.
The test needs the application-level UI context expected by the framework.
Ignoring the Deployment Model
A packaged WinUI application and an unpackaged WinUI application should not be configured as if they were identical.
Before troubleshooting the test runner, determine whether the application is:
UWP
WinUI 3 unpackaged
WinUI 3 packaged
WinUI AppContainer
That decision affects how the test host must be started.
Testing Business Logic Through the UI
If a test can be expressed as:
Assert.AreEqual(expected, actual);
without involving the UI, it probably does not belong in the UI test suite.
Reserve UI tests for UI-specific behavior.
Troubleshooting
When a WinUI or UWP UI test fails before executing the assertion, check the environment before changing the test code.
Check the Target Framework
A WinUI test project needs a Windows-specific target framework compatible with the application. Microsoft notes that test projects referencing WinUI 3 applications may need their target framework adjusted to match the application's Windows target.
For example:
<PropertyGroup>
<TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
</PropertyGroup>
The exact target should match the application rather than being copied blindly.
Check Runtime Identifiers
WinUI applications may need Windows runtime identifiers such as:
<PropertyGroup>
<RuntimeIdentifiers>
win-x86;win-x64;win-arm64
</RuntimeIdentifiers>
</PropertyGroup>
The required configuration depends on the target framework and application model.
Check Windows App SDK Availability
For framework-dependent WinUI applications, the required Windows App SDK runtime must be available on the machine running the tests.
A test that works on a developer machine with the runtime installed can fail on a clean CI agent.
Check CI Permissions and Machine Policy
Packaged and AppContainer scenarios can depend on machine configuration, Developer Mode, sideloading policy, and how the test agent is running.
A CI agent running under a different account or privilege level can therefore behave differently from an interactive developer session.
Microsoft specifically calls out machine policy and non-elevated execution considerations for the supported Windows application test models.
Advantages and Disadvantages
Advantages
Tests run with real UI-thread access: The MSTest UI test model is designed around the threading requirements of UWP and WinUI applications instead of treating UI objects like ordinary .NET objects.
Common testing model: Developers can use MSTest lifecycle concepts and UITestMethod across supported UWP and WinUI scenarios rather than maintaining completely different testing patterns.
Better integration with modern test infrastructure: Microsoft.Testing.Platform provides a modern execution architecture and supports application-hosted testing scenarios that are difficult to model with a conventional external test runner.
Useful for framework-specific behavior: UI tests can verify interactions that ordinary unit tests cannot reliably cover, such as dispatcher-dependent control creation and UI state transitions.
Disadvantages
More complicated setup: UWP, packaged WinUI, unpackaged WinUI, and AppContainer applications have different hosting requirements.
Windows-specific execution: These tests depend on Windows application infrastructure and are not equivalent to ordinary cross-platform .NET unit tests.
Slower than unit tests: Starting the application host and creating UI state introduces overhead, so UI tests should not replace normal unit tests.
CI can be more difficult: Package registration, runtime availability, machine policies, and test-agent configuration can all affect reliability.
When Should You Use MSTest UI Tests?
Use MSTest UI tests when the behavior genuinely depends on the Windows UI framework.
Good candidates include:
Creating WinUI controls
Testing dispatcher-dependent behavior
Testing UI state transitions
Testing application-level UI initialization
Testing async operations that update UI state
Testing behavior that cannot be isolated from the UI framework
Avoid using them for business logic that can be tested independently.
A healthy test architecture might look like:
Application
|
+----------+----------+
| |
Business Logic UI Layer
| |
Unit Tests UI Tests
|
Integration Tests
This keeps the expensive UI layer relatively small while giving developers fast feedback from ordinary tests.
Summary
MSTest's expanded UWP and WinUI 3 support addresses a problem that has always made Windows UI testing different from ordinary .NET testing: UI components depend on the application's real UI thread and dispatcher.
With modern MSTest and Microsoft.Testing.Platform support, developers can use UITestMethod to execute tests in the appropriate UI context and build tests around UWP and WinUI application hosts.
The biggest practical lesson is that UI testing is not simply unit testing with a Button added to the test. The application model, dispatcher, process lifetime, packaging model, Windows App SDK runtime, and CI environment all matter.
For new test projects, Microsoft recommends the modern MSTest and Microsoft.Testing.Platform direction, while the exact runner and hosting approach should be selected according to whether the application is UWP, unpackaged WinUI 3, packaged WinUI 3, or an AppContainer application.
The result is a more consistent way to test Windows UI behavior, but the same engineering rule still applies: keep business logic in fast tests and use UI tests where the UI itself is what needs to be verified.
Join the conversation! Your thoughts help the community grow.