Migrar do VSTest para a Microsoft. Testing.Platform (MTP)

Neste artigo, aprende como migrar do VSTest para o MTP.

Este artigo foca-se nos passos de migração e no mapeamento de argumentos.

Se ainda precisares de escolher uma plataforma, começa pela visão geral das plataformas de Teste.

Se precisar de comportamento detalhado dos dotnet test modos, veja Testing with dotnet test.

Se precisar de uma lista única de opções de linha de comandos de plataforma e extensão, consulte a referência de opções de CLI do MTP.

Optar por usar o MTP

O primeiro passo na migração é optar por usar o MTP.

Para todas as estruturas de teste, adicione <OutputType>Exe</OutputType> a todos os projetos de teste na solução. Depois disso, siga as orientações específicas do quadro.

MSTest

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

** Para optar por participar, adicione <EnableMSTestRunner>true</EnableMSTestRunner> num PropertyGroup, localizado num arquivo Directory.Build.props.

Observação

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

NUnit

O MTP é suportado pelo NUnit3TestAdapter a partir da versão 5.0.0.

** Para optar por participar, adicione <EnableNUnitRunner>true</EnableNUnitRunner> num PropertyGroup, localizado num arquivo Directory.Build.props.

xUnit.net

O MTP é suportado a partir do xunit.v3.

** Para optar por participar, adicione <UseMicrosoftTestingPlatformRunner>true</UseMicrosoftTestingPlatformRunner> num PropertyGroup, localizado num arquivo Directory.Build.props.

dotnet test

Adesão ao SDK do .NET 9 e versões anteriores

No SDK .NET 9 e anteriores, não existe suporte nativo para MTP para dotnet test. O suporte é construído sobre a infraestrutura VSTest. Para usar isto, adicione <TestingPlatformDotnetTestSupport>true</TestingPlatformDotnetTestSupport> sob um PropertyGroup num ficheiro Directory.Build.props.

Importante

Ao executar suporte para MTP neste modo, é necessário adicionar -- para separar os dotnet test argumentos dos argumentos da nova plataforma. Por exemplo, dotnet test --no-build -- --list-tests.

Opt-in para o SDK do .NET 10 e posterior

A partir do .NET SDK 10, existe 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

Neste modo, o extra -- deixa de ser utilizado.

Atualizar dotnet test invocações

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

Os argumentos relacionados à compilação 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 o MTP
--blame Não é relevante para o MTP
--blame-crash --crashdump(requer extensão de despejo de memória)
--blame-crash-dump-type <DUMP_TYPE> --crashdump-type(requer extensão de despejo de memória)
--blame-crash-collect-always Não suportado
--blame-hang --hangdump (necessita da extensão "Hang dump")
--blame-hang-dump-type <DUMP_TYPE> --hangdump-type (necessita da extensão "Hang dump")
--blame-hang-timeout <TIMESPAN> --hangdump-timeout (necessita da extensão "Hang dump")
--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 registador
--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 existe tal argumento centralizado a ser usado por todos os coletores de dados. Com o MTP, cada coletor de dados pode adicionar a sua própria opção de linha de comandos. Por exemplo, a execução do Microsoft CodeCoverage através do VSTest pode ser semelhante à seguinte:

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

Com o MTP, isto torna-se:

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

Importante

Como explicado anteriormente, ao usar MTP com o VSTest-based dotnet test, é necessário um extra -- antes dos argumentos que se pretende transmitir à plataforma. Então, isso se torna dotnet test -- --coverage --coverage-output-format cobertura.

--filter

--filter é o filtro baseado em VSTest.

O MSTest e o NUnit suportam o mesmo formato de filtro mesmo quando a correr com MTP.

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

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 de Microsoft.Testing.Platform para xUnit.net e Query Filter Language for xUnit.net.

--logger

O que normalmente era chamado de "logger" no VSTest é referido como "repórter" no MTP. No MTP, o registo é explicitamente apenas para fins de diagnóstico.

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

Um dos registradores VSTest muito usados é o registrador TRX. Este registador é geralmente chamado da seguinte forma:

dotnet test --logger trx

Com o MTP, o comando torna-se:

dotnet test --report-trx

Importante

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

Importante

Como explicado anteriormente, ao usar MTP com o VSTest dotnet test, é necessário um elemento adicional -- antes dos argumentos que se pretende passar à plataforma. Então, isso se torna dotnet test -- --report-trx.

--settings

VSTest's --settings é usado para especificar um arquivo RunSettings para a execução de teste. O RunSettings não é suportado pelo MTP central e foi substituído por um ficheiro de configuração mais moderno testconfig.json . No entanto, o MSTest e o NUnit continuam a suportar as antigas RunSettings ao executar MTP, e --settings é ainda suportado.

vstest.console.exe

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

Explorador de Testes

Ao usar o Visual Studio ou o Visual Studio Code Test Explorer, pode ser necessário ativar o suporte para MTP.

Visual Studio

O Visual Studio Test Explorer suporta MTP a partir da versão 17.14. Se você estiver usando uma versão anterior, talvez seja necessário atualizar seu Visual Studio para a versão mais recente.

Código do Visual Studio

O Visual Studio Code com C# DevKit suporta MTP.

Azure DevOps

Ao usar tarefas do Azure DevOps, pode ser necessário atualizar o seu pipeline para usar MTP, dependendo da tarefa que utiliza.

Tarefa VSTest

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

Tarefa CLI do .NET Core

  • Se tiveste arguments personalizado passado para a tarefa, segue as mesmas orientações para a migração de dotnet test.

  • Se estiveres a usar a tarefa DotNetCoreCLI sem aderir à experiência MTP nativa para .NET SDK 10 e depois via ficheiro global.json, precisas de definir a tarefa arguments para apontar corretamente para o diretório de resultados para onde ela 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

Execução de zero testes

Se um conjunto de testes não executou nenhum teste, o VSTest tolera isso e sai com sucesso. No entanto, o MTP falha com o código de saída 8. Existem várias formas de contornar isto:

  • Passe --ignore-exit-code 8 ao realizar os seus testes.

  • Se quiseres ignorar esse código de saída para um projeto de teste específico, adiciona o seguinte no ficheiro do projeto:

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

  • Usa a TESTINGPLATFORM_EXITCODE_IGNORE variável de ambiente.

Preservação do Console.InputEncoding

Se executares os teus testes numa consola onde a página de códigos foi explicitamente alterada (por exemplo, no Azure DevOps, a página de código está definida como 65001, que corresponde ao UTF8), o comportamento pode ser diferente entre VSTest e MTP.

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

Sugestão

A razão pela qual a codificação não é preservada com o modo de isolamento VSTest é que o processo testhost é iniciado com CreateNoWindow = true. Portanto, não está ligado à consola original.

Se tiver um teste que inicia mais um processo filho e redireciona a sua saída padrão, poderá enfrentar problemas se se aplicarem todas as seguintes opções:

  • A página de códigos da consola está definida para 65001 (UTF8). Isto pode acontecer no CI, mas geralmente não localmente. Para obter um comportamento local semelhante ao do CI, execute chcp 65001 antes de executar os testes.
  • O processo filho é iniciado com codificação não-UTF-8. Isto também pode acontecer caso o seu próprio teste defina CreateNoWindow = true.

Isto é especialmente problemático quando o processo filho não espera ver o byte BOM UTF8 (Byte-Order-Mark), o que poderia acontecer no cenário anterior no .NET Framework.

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

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

Outra solução alternativa para isso é não usar CreateNoWindow = true para processos filhos que redirecionam entradas padrão.

  • Last updated on