MSTest UI Testing for WinUI 3: Testing Packaged and Unpackaged Apps

Why WinUI 3 UI Testing Needs a Different Approach

A WinUI 3 application can compile successfully, pass its business-logic tests, and still fail when the actual interface runs. A control may be created on the wrong thread, an asynchronous operation may update the UI incorrectly, or the application may behave differently when launched through its MSIX package.

These problems are difficult to catch with ordinary unit tests because WinUI relies on a real application UI dispatcher, not simply a thread configured as single-threaded apartment (STA).

Microsoft addressed this testing challenge with improvements in MSTest 4.5 and Microsoft.Testing.Platform 2.5. Announced on October 5, 2026, the updated approach supports UI-thread testing across several Windows application models, including packaged and unpackaged WinUI 3 applications.

For .NET developers, the important change is that tests can run with access to the application's actual UI-thread infrastructure while the test platform handles the appropriate launch mechanism.

What Makes WinUI 3 UI Testing Different?

WinUI 3 is built on the Windows App SDK and uses XAML to construct its interface. Most types in the Microsoft.UI.Xaml namespace must be accessed from the application's UI thread.

A conventional unit test might create a new thread or mark a test method with an STA attribute. That establishes a threading apartment, but it does not automatically create the WinUI application environment and dispatcher required by many UI objects.

For example, this test is not a reliable way to validate WinUI behavior:

[TestMethod]
public void CreateGrid()
{
    var grid = new Grid();

    Assert.IsNotNull(grid);
}

The test may execute without the required WinUI application context. Creating an STA thread alone does not solve the problem.

MSTest's UITestMethod provides a UI-thread-aware testing model. It allows setup, asynchronous test execution, and cleanup to run with access to the application's UI dispatcher.

This makes it possible to test UI objects and thread affinity without manually implementing a custom dispatcher for every test.

Understanding the Supported Application Models

Packaged and unpackaged WinUI 3 applications have different deployment and startup behavior. The test runner must account for those differences.

Application model	Package identity	How the test application starts	When to use it
Unpackaged WinUI 3	No MSIX identity	Starts the executable directly	Most UI tests that do not require package identity
Packaged full-trust WinUI 3	MSIX identity	Registers and activates the packaged application	Tests involving package identity or packaged activation
WinUI 3 AppContainer	MSIX identity and restricted process access	Uses the supported packaged test-host infrastructure	Tests that need the AppContainer security model
UWP	Packaged application model	Uses the appropriate UWP test-host and activation path	Existing UWP applications

The distinction is important because a packaged desktop application cannot always be launched in the same way as a normal executable. Windows may need to register the package and activate its Application User Model ID (AUMID).

Microsoft.Testing.Platform provides the infrastructure for selecting the appropriate launch path. The MSTest.Sdk project SDK helps configure the runner and the required testing components.

For new WinUI 3 tests, start with the unpackaged model unless the feature being tested requires package identity or packaged activation behavior.

Create a WinUI 3 MSTest Project

Start with a Windows development environment that has a compatible .NET SDK, Visual Studio tooling, and Windows App SDK support.

The test project must target a Windows-specific framework because WinUI 3 is a Windows-only UI framework.

For example, a project targeting .NET 10 can use a target framework such as:

<PropertyGroup>
  <TargetFramework>net10.0-windows10.0.19041.0</TargetFramework>
  <RuntimeIdentifiers>win-x64;win-arm64</RuntimeIdentifiers>
</PropertyGroup>

The example targets Windows 10, version 2004, or later through its platform version and declares x64 and ARM64 runtime identifiers. Adjust the runtime identifiers to match the architectures your team supports.

For the modern MSTest approach, use the MSTest.Sdk project SDK and a compatible version of MSTest and Microsoft.Testing.Platform.

A minimal project can start with the following structure:

<Project Sdk="MSTest.Sdk/4.5.0">

  <PropertyGroup>
    <TargetFramework>net10.0-windows10.0.19041.0</TargetFramework>
    <RuntimeIdentifiers>win-x64;win-arm64</RuntimeIdentifiers>
  </PropertyGroup>

</Project>

The version shown is an example of the MSTest SDK version used for this testing model. Confirm the available package version and align it with the supported Microsoft.Testing.Platform version in your environment.

The project must also include the appropriate Windows App SDK and WinUI configuration for the application model being tested.

Write Your First UI-Thread Test

Once the project is configured, the test itself can be relatively simple.

The following example verifies that a WinUI Grid is created on a thread with access to the UI dispatcher.

using Microsoft.UI.Xaml;
using Microsoft.VisualStudio.TestTools.UnitTesting;

[TestClass]
public class WinUITests
{
    [UITestMethod]
    public async Task GridCanBeCreatedOnTheUIThread()
    {
        await Task.Yield();

        var grid = new Grid();

        Assert.IsTrue(
            grid.DispatcherQueue.HasThreadAccess);
    }
}

Here is what happens:

[TestClass] identifies the class containing MSTest tests.
[UITestMethod] runs the test using the WinUI-aware UI-thread testing model.
await Task.Yield() introduces an asynchronous continuation, allowing the test to exercise an asynchronous path.
new Grid() creates a WinUI control.
DispatcherQueue.HasThreadAccess verifies that the current thread has access to the grid's dispatcher.

The assertion checks thread access rather than visual rendering. It is a useful starting point for verifying that the test host is configured correctly.

In a real application, the same pattern can be extended to create windows, manipulate controls, test UI-bound state, and verify that asynchronous operations update the interface correctly.

Test Asynchronous UI Operations

Asynchronous operations introduce additional risks in desktop applications.

A service may fetch data from an API, load records from a database, or perform a long-running calculation. Once the operation finishes, the application must update its UI-bound state through the correct dispatcher.

A useful test checks that the asynchronous operation completes and that the UI update occurs on the expected thread.

For example, consider a view model that loads a product name and exposes it through a property:

public sealed class ProductViewModel
{
    public string? ProductName { get; private set; }

    public async Task LoadAsync()
    {
        await Task.Delay(10);

        ProductName = "Mechanical Keyboard";
    }
}

A test can verify the resulting state:

[TestClass]
public class ProductViewModelTests
{
    [TestMethod]
    public async Task LoadAsyncSetsProductName()
    {
        var viewModel = new ProductViewModel();

        await viewModel.LoadAsync();

        Assert.AreEqual(
            "Mechanical Keyboard",
            viewModel.ProductName);
    }
}

This second test is a conventional unit test because the view model does not create or manipulate WinUI controls. It does not need a UI dispatcher.

The distinction is important: use ordinary tests for business logic and reserve UITestMethod for operations that require WinUI's UI-thread infrastructure.

For an application that updates a bound property from an asynchronous callback, test the dispatcher interaction separately. Avoid introducing artificial UI-thread dependencies into classes that can be tested independently.

Configure an Unpackaged WinUI 3 Test App

An unpackaged WinUI 3 application has no MSIX identity and does not need package registration to launch its executable.

The project configuration includes these properties:

<PropertyGroup>
  <WindowsPackageType>None</WindowsPackageType>
  <EnableMsixTooling>false</EnableMsixTooling>
</PropertyGroup>

The test project should not include MSIX manifest and package-asset items for this unpackaged configuration.

When the project meets the Windows App SDK's bootstrap-initializer conditions, the build tooling normally supplies the initializer automatically. If a separate host loads the test library instead, the bootstrap configuration may need to be set explicitly.

Under Microsoft.Testing.Platform, the unpackaged test application can be started directly. This avoids the additional package-registration and activation steps required by the packaged model.

Run the project from its directory:

dotnet run

You can also specify the project explicitly:

dotnet run --project .\WinUITests.csproj

For this configuration, use Microsoft.Testing.Platform. The unpackaged WinUI test-host path is not supported by VSTest.

Do not substitute dotnet exec for launching the generated application host. WinUI resolves package-independent resource files relative to the process path, and launching through dotnet.exe can interfere with resource loading.

Configure a Packaged WinUI 3 Test App

Some tests need to verify behavior that depends on MSIX identity, package registration, or packaged activation contracts.

In that case, retain the normal packaged WinUI configuration and the Package.appxmanifest file. Do not set WindowsPackageType to None.

The test infrastructure must register the package layout and activate the application through its AUMID. A packaged test host cannot be treated as an ordinary executable launched with Process.Start.

The packaged testing extension supplies the required launch integration when used with a compatible MSTest and Microsoft.Testing.Platform configuration.

Before running packaged tests, verify the following:

The project targets a Windows-specific framework with platform version 10.0.19041.0 or later.
Developer Mode or an appropriate sideloading policy permits registration of the build output.
The package manifest identifies the correct application executable.
The packaged application uses a supported trust model.
The testing extension and runner versions support the packaged activation workflow.

Packaged activation support has evolved through preview releases. Check the current package release and documentation before relying on it in a production CI pipeline.

Run UI Tests in Continuous Integration

UI tests introduce requirements that ordinary unit tests do not have. The runner needs a supported Windows environment, the correct Windows App SDK components, and a working application launch configuration.

For unpackaged tests, a CI job can execute the test project directly:

dotnet run --project .\WinUITests.csproj -c Release

For packaged projects, follow the documented Microsoft.Testing.Platform and MSBuild invocation for the selected application model. The machine may need Developer Mode or an approved sideloading configuration, and the test host must be activated through the package.

Before making the tests a required build gate, verify:

The CI agent uses a supported Windows version.
The correct SDK and Windows App SDK dependencies are installed.
The test process exits with a nonzero code when an assertion fails.
The test window closes and the process terminates after execution.
Test results and diagnostic artifacts are captured by the pipeline.
Packaged registration and activation work on a clean agent.

UI tests can be sensitive to desktop availability, process startup, and timing. Keep the first test suite small, avoid arbitrary delays where possible, and use deterministic application state to reduce flaky results.

Common Problems and How to Troubleshoot Them

Symptom	Likely cause	What to check
WinUI controls fail during initialization	Missing or incorrect UI-thread context	Use `UITestMethod` for tests that require the WinUI dispatcher
Unpackaged test fails looking for `AppxManifest.xml`	Incorrect runner or project configuration	Confirm `WindowsPackageType` is `None` and use Microsoft.Testing.Platform
Packaged test cannot activate	Package registration or AUMID configuration is incorrect	Check the manifest, Windows target framework, and sideloading policy
Test passes but the process remains open	Window or application lifecycle is not shutting down	Ensure cleanup closes the test window and exits the application
Failed assertions still produce a successful process exit	Test-runner exit code is not propagated correctly	Verify the test host returns the result of the platform run
Tests behave differently on CI	Missing Windows dependencies or unsupported session configuration	Reproduce the environment and validate the launch path

The right troubleshooting approach is to identify whether the failure comes from the test itself, the UI dispatcher, the package model, or the CI environment.

Best Practices for Reliable WinUI 3 Tests

Separate business logic from UI code. Move data processing, validation, and application rules into independently testable classes. This keeps most tests fast and reduces the number that require a real UI host.

Use the correct test attribute. Use [TestMethod] for ordinary application logic and [UITestMethod] for code that requires WinUI's UI-thread context.

Choose the packaging model intentionally. Prefer unpackaged testing unless package identity or activation behavior is part of the requirement.

Keep framework versions aligned. Verify that MSTest, Microsoft.Testing.Platform, Windows App SDK, and the target framework work together.

Test the real deployment behavior. If the application ships as an MSIX package, maintain a smaller suite of tests that exercises the packaged activation path.

Validate CI before enforcing the gate. A test that passes only on a developer's workstation is not yet a reliable regression test.

Conclusion

MSTest's updated UI-thread testing support makes it easier to test WinUI 3 applications using the dispatcher and application infrastructure they actually depend on. The improvements in MSTest 4.5 and Microsoft.Testing.Platform 2.5 cover the distinct startup paths used by packaged and unpackaged Windows applications.

For most new WinUI 3 test projects, the unpackaged model is the simplest starting point. Add packaged tests when package identity, activation, or deployment behavior needs explicit validation.

The most reliable strategy is to keep business logic in conventional unit tests, use UI-thread-aware tests for WinUI-specific behavior, and verify the complete launch and cleanup lifecycle on the same Windows environment used by your CI pipeline.