Migre do VSTest para Microsoft. Testing.Platform (MTP)

Neste artigo, você aprenderá a migrar do VSTest para o MTP.

Este artigo se concentra nas etapas de migração e no mapeamento de argumentos.

Se você ainda precisar escolher uma plataforma, comece com a visão geral das plataformas de teste.

Se você precisar de um comportamento detalhado dos dotnet test modos, consulte Testando com dotnet test.

Se você precisar de uma lista única de opções de linha de comando para a plataforma e extensão, consulte Referência de Opções da CLI MTP.

Optar por usar o MTP

A primeira etapa na migração é aceitar o uso do MTP.

Para todas as estruturas de teste, adicione <OutputType>Exe</OutputType> a todos os projetos de teste na solução. Depois disso, siga as diretrizes específicas da estrutura.

MSTest

O MTP tem suporte do MSTest a partir da versão 3.2.0. No entanto, recomendamos atualizar para a versão mais recente do MSTest disponível.

Para aderir, adicione <EnableMSTestRunner>true</EnableMSTestRunner> sob um PropertyGroup no arquivo Directory.Build.props.

Observação

Ao usar MSTest.Sdk, o MTP é usado por padrão, a menos que <UseVSTest>true</UseVSTest> seja especificado.

NUnit

O MTP tem suporte do NUnit3TestAdapter começando com 5.0.0.

Para aderir, adicione <EnableNUnitRunner>true</EnableNUnitRunner> sob um PropertyGroup no arquivo Directory.Build.props.

xUnit.net

O MTP tem suporte a partir do xunit.v3.

Para aderir, adicione <UseMicrosoftTestingPlatformRunner>true</UseMicrosoftTestingPlatformRunner> sob um PropertyGroup no arquivo Directory.Build.props.

dotnet test

Optar pelo SDK .NET 9 e versões anteriores

No SDK do .NET 9 e anteriores, não há suporte nativo para MTP para dotnet test. O suporte é criado com base na infraestrutura do VSTest. Para usá-lo, adicione <TestingPlatformDotnetTestSupport>true</TestingPlatformDotnetTestSupport> em um PropertyGroup no arquivo Directory.Build.props.

Importante

Ao executar o suporte a MTP nesse modo, você precisa adicionar -- para separar os dotnet test argumentos dos novos argumentos da plataforma. Por exemplo, dotnet test --no-build -- --list-tests.

Aceitar o SDK do .NET 10 e posterior

A partir do SDK do .NET 10, há suporte nativo para MTP. Para usá-lo, você deve especificar o executor de teste como Microsoft.Testing.Platform em global.json:

{
  "test": {
    "runner": "Microsoft.Testing.Platform"
  }
}

Importante

Nesse modo, o extra -- não é mais usado.

Atualizar dotnet test invocações

As opções de linha de comando dotnet test são divididas em duas categorias: argumentos relacionados ao build e argumentos relacionados ao teste.

Os argumentos relacionados ao build são irrelevantes para a plataforma de teste e, como tal, não precisam ser atualizados para a nova plataforma. Os argumentos relacionados ao build estão listados aqui:

  • -a|--arch <ARCHITECTURE>
  • --artifacts-path <ARTIFACTS_DIR>
  • -c|--configuration <CONFIGURATION>
  • -f|--framework <FRAMEWORK>
  • -e|--environment <NAME="VALUE">
  • --interactive
  • --no-build
  • --nologo
  • --no-restore
  • -o|--output <OUTPUT_DIRECTORY>
  • --os <OS>
  • -r|--runtime <RUNTIME_IDENTIFIER>
  • -v|--verbosity <LEVEL>

Os argumentos relacionados ao teste são específicos do VSTest e, portanto, precisam ser transformados para corresponder à nova plataforma. A tabela a seguir mostra o mapeamento entre os argumentos VSTest e a nova plataforma:

Argumento VSTest Novo argumento de plataforma
--test-adapter-path <ADAPTER_PATH> Não relevante para MTP
--blame Não relevante para MTP
--blame-crash --crashdump (requer extensão de crash dump)
--blame-crash-dump-type <DUMP_TYPE> --crashdump-type (requer extensão de crash dump)
--blame-crash-collect-always Sem suporte
--blame-hang --hangdump (requer extensão de despejo de falha)
--blame-hang-dump-type <DUMP_TYPE> --hangdump-type (requer extensão de despejo de falha)
--blame-hang-timeout <TIMESPAN> --hangdump-timeout (requer extensão de despejo de falha)
--collect <DATA_COLLECTOR_NAME> Depende do coletor de dados
-d\|--diag <LOG_FILE> --diagnostic
--filter <EXPRESSION> Depende da estrutura de teste selecionada
-l\|--logger <LOGGER> Depende do logger
--results-directory <RESULTS_DIR> --results-directory <RESULTS_DIR>
-s\|--settings <SETTINGS_FILE> Depende da estrutura de teste selecionada
-t\|--list-tests --list-tests
-- <RunSettings arguments> --test-parameter (fornecido por VSTestBridge)

--collect

--collect é um ponto de extensibilidade geral no VSTest para qualquer coletor de dados. O modelo de extensibilidade do MTP é diferente e não há nenhum argumento centralizado a ser usado por todos os coletores de dados. Com o MTP, cada coletor de dados pode adicionar sua própria opção de linha de comando. Por exemplo, executar o Microsoft CodeCoverage por meio do VSTest pode ser semelhante ao seguinte:

dotnet test --collect "Code Coverage;Format=cobertura"

Com o MTP, isso se torna:

dotnet test --coverage --coverage-output-format cobertura

Importante

Conforme explicado anteriormente, ao usar MTP com base no dotnet testVSTest, um extra -- é necessário antes que os argumentos pretendidos sejam passados para a plataforma. Então, isso se torna dotnet test -- --coverage --coverage-output-format cobertura.

--filter

--filter é o filtro baseado em VSTest.

MSTest e NUnit dão suporte ao mesmo formato de filtro mesmo quando executados com MTP.

xUnit.net, não dá suporte ao mesmo formato de filtro ao ser executado com MTP. Você deve migrar do filtro baseado em VSTest para o novo suporte de filtro em xunit.v3, que é fornecido usando as opções de linha de comando a seguir.

xUnit.net opções específicas:

  • --filter-class
  • --filter-not-class
  • --filter-method
  • --filter-not-method
  • --filter-namespace
  • --filter-not-namespace
  • --filter-trait
  • --filter-not-trait
  • --filter-query

Para obter mais informações, consulte a documentação Microsoft.Testing.Platform para xUnit.net e Linguagem de Filtro de Consulta para xUnit.net.

--logger

O que era geralmente chamado de "logger" no VSTest é referido como "repórter" no MTP. No MTP, o registro em log é explicitamente somente para fins de diagnóstico.

Semelhante a --collect, --logger é um ponto de extensibilidade geral no VSTest para qualquer registrador (ou, no contexto de MTP, qualquer reportador). Cada repórter MTP é livre para adicionar sua própria opção de linha de comando e, portanto, não há uma opção de linha de comando centralizada como a do --loggerVSTest.

Um dos registradores VSTest mais comumente usados é o registrador TRX. Esse logger geralmente é chamado da seguinte maneira:

dotnet test --logger trx

Com o MTP, o comando se torna:

dotnet test --report-trx

Importante

Para usar --report-trx, você deve ter o Microsoft.Testing.Extensions.TrxReport pacote NuGet instalado.

Importante

Conforme explicado anteriormente, ao usar MTP com o VSTest baseado no dotnet test, um extra -- é necessário antes que os argumentos destinados sejam passados para a plataforma. Então, isso se torna dotnet test -- --report-trx.

--settings

VSTest --settings é usado para especificar um arquivo RunSettings para a execução dos testes. RunSettings não é compatível com o MTP principal e foi substituído por um arquivo de configuração mais moderno testconfig.json . No entanto, MSTest e NUnit ainda dão suporte aos RunSettings antigos durante a execução do MTP e --settings ainda é suportado.

vstest.console.exe

Se você estiver usando vstest.console.exe diretamente, recomendamos substituí-lo pelo dotnet test comando.

Gerenciador de Testes

Ao usar Visual Studio ou Visual Studio Code Gerenciador de Testes, talvez seja necessário habilitar o suporte para MTP.

Visual Studio

Visual Studio Gerenciador de Testes dá suporte ao MTP a partir da versão 17.14. Se você estiver usando uma versão anterior, talvez seja necessário atualizar o Visual Studio para a versão mais recente.

Visual Studio Code

Visual Studio Code com o Kit de Desenvolvimento em C# dá suporte a MTP.

Azure DevOps

Ao usar as tarefas do Azure DevOps, pode ser necessário atualizar o pipeline para usar o MTP, a depender da tarefa que utilizar.

Tarefa VSTest

Se você estiver usando a tarefa VSTest no Azure DevOps, poderá substituí-la pela tarefa .NET Core.

Tarefa da CLI do .NET Core

  • Se você tiver um arguments personalizado passado para a tarefa, siga as mesmas diretrizes para migração de dotnet test.

  • Se você estiver usando a tarefa DotNetCoreCLI sem optar pela experiência MTP nativa para o .NET 10 SDK e versões posteriores por meio do arquivo global.json, será necessário configurar a tarefa arguments para apontar corretamente para o diretório de resultados ao qual ela originalmente apontava, bem como para o relatório TRX solicitado. Por exemplo:

    - task: DotNetCoreCLI@2
  displayName: Run unit tests
  inputs:
    command: 'test'
    arguments: '-- --report-trx --results-directory $(Agent.TempDirectory)'

Diferenças comportamentais entre VSTest e MTP

Executando zero testes

Se um assembly de teste não executar nenhum teste, o VSTest aceita isso e finaliza com sucesso. No entanto, o MTP falha com o código de saída 8. Há várias maneiras de contornar isso:

  • Passe --ignore-exit-code 8 ao executar seus testes.

  • Se você quiser ignorar esse código de saída para um projeto de teste específico, adicione o seguinte no arquivo de projeto:

    <PropertyGroup>
  <TestingPlatformCommandLineArguments>$(TestingPlatformCommandLineArguments) --ignore-exit-code 8</TestingPlatformCommandLineArguments>
</PropertyGroup>

  • Use a variável de TESTINGPLATFORM_EXITCODE_IGNORE ambiente.

Preservação do Console.InputEncoding

Se você executar seus testes em um console em que a página de código foi explicitamente alterada (por exemplo, em Azure DevOps, a página de código será definida como 65001 que corresponde a UTF8), o comportamento poderá ser diferente entre VSTest e MTP.

  • Com MTP, essa codificação é sempre preservada.
  • Com o VSTest não sendo executado no modo de isolamento (o comportamento padrão do vstest.console), essa codificação é preservada, semelhante ao MTP.
  • Com o VSTest em execução no modo de isolamento (o comportamento padrão de dotnet test), essa codificação não é preservada no testhost, que é o processo que executa os testes.

Dica

O motivo pelo qual a codificação não é preservada com o modo de isolamento VSTest é que o processo de testhost é iniciado com CreateNoWindow = true. Portanto, ele não está anexado ao console original.

Se você tiver um teste que inicie mais um processo filho e redirecione sua saída padrão, poderá enfrentar problemas se todos os seguintes se aplicarem:

  • A página de código do console é definida como 65001 (UTF8). Esse pode ser o caso na CI, mas geralmente não localmente. Para obter um comportamento local semelhante ao da CI, execute chcp 65001 antes de executar os testes.
  • O processo filho é iniciado com codificação não UTF-8. Isso também pode acontecer se seu próprio teste também definir CreateNoWindow = true.

Isso é especialmente problemático quando o processo filho não espera ver o byte UTF8 BOM (byte-Order-Mark), que pode ser obtido no cenário anterior no .NET Framework.

Como essa diferença de comportamento provavelmente será problemática especificamente para o byte BOM, uma solução alternativa é definir InputEncoding durante a inicialização do assembly como UTF8 sem BOM.

Console.InputEncoding = new UTF8Encoding(encoderShouldEmitUTF8Identifier: false);

Uma solução alternativa diferente para isso é não usar CreateNoWindow = true para processos filho que redirecionam a entrada padrão.

  • Last updated on