Teste aplicativos WinUI 3 com MSTest e Microsoft. Testing.Platform

Use Microsoft. Test.Platform (MTP) para executar testes MSTest dentro de um aplicativo WinUI 3. O aplicativo WinUI atua como o host de teste. Ele possui o ponto de entrada do aplicativo, o thread da interface do usuário e o tempo de vida do processo.

Escolha entre dois modelos de implantação do WinUI 3:

  • Um aplicativo não empacotado é executado como um executável Windows regular.
  • Um aplicativo de confiança total empacotado mantém a identidade do pacote MSIX e usa a extensão experimental Microsoft.Testing.Extensions.PackagedApp para registrar e ativar o host de teste.

Importante

A extensão de aplicativo empacotado dá suporte a aplicativos de área de trabalho empacotados de confiança total. Ele não dá suporte a UWP nem a outros hosts de teste do AppContainer.

A ativação AUMID de confiança total empacotada é implementada no microsoft/testfx repositório, mas não está disponível em um pacote NuGet público a partir de 6 de agosto de 2026. Os pacotes atuais 1.0.0-alpha não contêm a implementação de ativação específica Windows. Use a configuração empacotada somente depois que uma versão do pacote identificar o suporte para registro MSIX de confiança total e ativação do AUMID.

Escolher um modelo de implantação

Escolha o modelo de implantação antes de configurar o projeto de teste.

Requirement Escolher Inicialização do host de teste
Seus testes não precisam de identidade de pacote ou APIs que exijam a identidade do pacote. Desempacotado O MTP inicia o executável do aplicativo diretamente.
Seus testes exigem a identidade do pacote MSIX ou o comportamento de aplicativo empacotado. Confiança total empacotada após a versão prévia do MTP ficar disponível publicamente A extensão de aplicativo empacotado registra a saída de build e ativa o aplicativo pela AUMID (ID do Modelo de Usuário do Aplicativo).
Seus testes devem ser executados em UWP ou em outro AppContainer. VSTest A extensão de aplicativo empacotado MTP não dá suporte ao isolamento appContainer.

A menos que seus testes exijam a identidade do pacote, use um aplicativo não empacotado. O modelo não empacotado não requer registro de pacote, Modo de Desenvolvedor ou a extensão experimental de aplicativo empacotado.

Até que uma versão prévia pública do MTP inclua o registro MSIX de confiança total e a ativação do AUMID, use o VSTest para testes do WinUI 3 de confiança total empacotados.

Entender o limite UWP

Não trate a UWP como outro modelo do WinUI 3 empacotado. Ambos os projetos UWP clássicos destinados ao UAP 10 e aos projetos UWP de .NET modernos que devem UseUwp ser true executados em um AppContainer. Empacotar um aplicativo da área de trabalho WinUI 3 não o coloca nesse modelo de aplicativo.

Use o VSTest para testes UWP clássicos e modernos .NET UWP. O inicializador de aplicativos empacotados mtp tem como destino hosts de área de trabalho empacotados de confiança total. Ele não pode fornecer seus argumentos de ativação ou conexão de controlador a um host AppContainer.

Para obter uma configuração UWP .NET moderna, consulte o exemplo de UWP do MSTest .NET 9.

Configurar o host de teste do WinUI

Ambos os modelos de implantação usam a mesma configuração de MTP auto-hospedada.

Definir as propriedades comuns do projeto

Defina essas propriedades no projeto de teste do WinUI:

<OutputType>Exe</OutputType>
<TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
<UseWinUI>true</UseWinUI>
<EnableMSTestRunner>true</EnableMSTestRunner>
<GenerateTestingPlatformEntryPoint>false</GenerateTestingPlatformEntryPoint>

Use .NET 8 ou uma versão de .NET com suporte posterior. O exemplo é direcionado Windows versão 10.0.19041.0da plataforma. A extensão de aplicativo empacotado requer esta versão ou posterior.

Mantenha o item WinUI ApplicationDefinition que aponta para o arquivo XAML do aplicativo de teste. O WinUI gera um ponto de entrada desse item. Para impedir que o MTP gere um segundo ponto de entrada, defina GenerateTestingPlatformEntryPoint como false.

Adicione referências de pacote às versões compatíveis atuais do MSTest e do Microsoft. WindowsAppSDK.

Hospedar MTP do aplicativo

Substitua OnLaunched na classe WinUI Application . Crie e ative a janela de teste e, em seguida, publique sua fila de dispatcher:

_window = new UnitTestAppWindow();
_window.Activate();
UITestMethodAttribute.DispatcherQueue = _window.DispatcherQueue;

Adicionar using Microsoft.VisualStudio.TestTools.UnitTesting.AppContainer; para UITestMethodAttribute.

Crie o aplicativo MTP com base nos argumentos de linha de comando. Em seguida, registre as extensões que o MSBuild contribui:

string[] cliArgs = Environment.GetCommandLineArgs().Skip(1)
    .Where(arg => !arg.Contains("EnableMSTestRunner")).ToArray();
ITestApplicationBuilder builder = await TestApplication.CreateBuilderAsync(cliArgs);
builder.AddSelfRegisteredExtensions(cliArgs);
using ITestApplication app = await builder.BuildAsync();

Adicione using Microsoft.Testing.Platform.Builder; para os tipos de construtor mtp. O build do WinUI adiciona EnableMSTestRunner aos argumentos do processo. Como não é uma opção de linha de comando MTP, remova-a antes de criar o aplicativo de teste.

O projeto desabilita o ponto de entrada MTP gerado, portanto, chame AddSelfRegisteredExtensions. Para um aplicativo empacotado, o método também registra o Microsoft.Testing.Extensions.PackagedApp inicializador.

In OnLaunched, put test application creation and execution in a try block. Atribuir o resultado de await app.RunAsync()Environment.ExitCode. Em um finally bloco, feche a janela e chame o método do Exit aplicativo.

As etapas do ciclo de vida fornecem duas garantias:

  • O processo retorna o código de saída mtp, de modo que um teste com falha produz um código de saída de processo diferente de zero.
  • O loop de mensagem WinUI é interrompido após a execução em vez de deixar o processo de teste ativo.

Warning

Não adicione [assembly: WinUITestTarget(...)] a um aplicativo de teste do WinUI auto-hospedado. O atributo inicia um aplicativo WinUI para um host de teste separado. Um aplicativo auto-hospedado chama Application.Start primeiro. Em seguida, o atributo tenta iniciar um segundo aplicativo no mesmo processo.

Para obter uma implementação completa, consulte o exemplo de WinUI não empacotado e o exemplo de WinUI empacotado.

Executar testes no thread da interface do usuário

Use UITestMethod para um teste que cria ou acessa objetos WinUI. O MSTest agenda o teste na fila do dispatcher que você atribuiu durante OnLaunched.

[UITestMethod]
public void CreatesControlOnUiThread()
{
    var grid = new Grid();
    Assert.IsTrue(grid.DispatcherQueue.HasThreadAccess);
}

Um regular TestMethod não é executado na fila do dispatcher do WinUI. Use-o para testes que não exigem o thread da interface do usuário.

Configurar um aplicativo de teste não empacotado

Para um aplicativo não empacotado, adicione estas propriedades:

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

Não faça referência Microsoft.Testing.Extensions.PackagedApp. O aplicativo não empacotado não tem nenhuma identidade MSIX ou AppxManifest.xml em sua saída, portanto, o MTP pode iniciar seu executável diretamente.

Por padrão, o SDK do Aplicativo Windows injeta seu inicializador de inicialização quando o projeto atende a estas condições:

  • WindowsPackageType é None.
  • OutputType é Exe ou WinExe.
  • WindowsAppSDKSelfContained não é true.

Se um host que não é um SDK do Aplicativo Windows aplicativo carregar sua biblioteca de teste, definido WindowsAppSdkBootstrapInitializetrue como na biblioteca.

Note

O VSTest não dá suporte a essa configuração winui não empacotada. Execute o projeto com MTP.

Configurar um aplicativo de teste de confiança total empacotado

Mantenha a configuração padrão do WinUI empacotada:

  • Não defina WindowsPackageType como None.
  • Mantenha Package.appxmanifest e os ativos do pacote no projeto.
  • Defina EnableMsixTooling como true se seu projeto usa as ferramentas de empacotamento MSIX de projeto único.

Após uma visualização que inclui o registro MSIX de confiança total e a ativação do AUMID ficarem disponíveis, adicione essa versão específica do Microsoft. Pacote Testing.Extensions.PackagedApp. Não use um pacote anterior 1.0.0-alpha para essa configuração.

Os adereços do MSBuild do pacote registram o inicializador por meio AddSelfRegisteredExtensionsde . Não ligue AddPackagedAppDeploymenttambém. Uma execução mtp pode registrar apenas um inicializador de host de teste.

O inicializador executa estas ações:

  1. Ele verifica um AppxManifest.xml que descreve o executável de teste.
  2. Ele registra o layout de saída de build com Windows.
  3. Ele resolve o AUMID do aplicativo do pacote registrado e da ID do aplicativo de manifesto.
  4. Ele ativa o aplicativo pela AUMID e conecta o processo ativado ao controlador MTP.

O inicializador ignora um manifesto não relacionado em um diretório ancestral, a menos que uma Application entrada aponte para o executável de teste. Um aplicativo não empacotado que faz referência ao pacote permanece indiretamente no caminho de início direto.

Atenda a esses requisitos antes de executar um aplicativo de teste empacotado:

  • Use uma estrutura de destino específica Windows com a versão 10.0.19041.0 da plataforma ou posterior.
  • Para registrar o layout de saída de build sem sinal, habilite o Modo de Desenvolvedor ou configure o sideload.
  • Use um aplicativo de área de trabalho empacotado de confiança total. A extensão não dá suporte a UWP ou a outros hosts AppContainer.

Caution

Microsoft.Testing.Extensions.PackagedApp e o ITestHostLauncher ponto de extensão são experimentais. Uma versão futura pode alterar ou remover suas APIs e comportamento. Avalie os riscos antes de usar o modelo empacotado na infraestrutura de teste de produção.

Executar os testes

No diretório que contém o projeto de teste do WinUI, execute:

dotnet run

Para especificar o projeto, use dotnet run --project .\WinUITests.csproj.

Para um aplicativo não empacotado, o MTP inicia o executável diretamente. Para um aplicativo empacotado, o inicializador de aplicativo empacotado registra o layout e ativa o aplicativo pela AUMID.

Em ambos os modelos, a janela de teste é aberta, o MTP executa os testes e a janela fecha. Em seguida, o terminal relata o resumo do teste. Uma execução bem-sucedida é encerrada com código 0. Quando um teste falha, OnLaunched atribui o resultado diferente de zero RunAsync a Environment.ExitCode.

Use dotnet run para qualquer um dos modelos. Para executar um aplicativo não empacotado diretamente, use o executável do aplicativo gerado. Não use dotnet exec porque o WinUI resolve os recursos do PRI em relação ao caminho do processo.

Solucionar problemas de configuração

Use estas verificações para as falhas de instalação mais comuns:

Sintoma Verificação
O aplicativo relata várias chamadas para Application.Start. Remova o WinUITestTarget atributo do aplicativo de teste auto-hospedado.
A execução do teste é concluída, mas o processo permanece aberto. Feche a janela de teste e chame Exit em um finally bloco após RunAsync.
Testes com falha ainda retornam o código 0de saída do processo. Atribuir o resultado de RunAsyncEnvironment.ExitCode.
Uma execução não empacotada falha porque AppxManifest.xml está ausente. Confirme se o projeto habilita o MTP e se a execução não usa o VSTest.
Uma execução empacotada não pode registrar ou ativar o aplicativo. Confirme a estrutura de destino específica Windows, o Modo de Desenvolvedor ou a configuração de sideload, o modelo de aplicativo de confiança total e a entrada executável do manifesto.

Consulte também

  • Last updated on