Configuração do SDK do MSTest

Este artigo aborda as opções de configuração avançadas para MSTest.Sdk. Para obter as configurações básicas e começar, consulte Introdução ao MSTest.

Importante

Por padrão, o MSTest.Sdk usa o executor do MSTest com MTP, inclusive com o comando dotnet test. Isso requer a modificação de suas chamadas de CI e da CLI local e também afeta as entradas disponíveis dos .runsettings. Você pode manter as integrações e ferramentas antigas alternando para o VSTest.

MSTest.Sdk define EnableMSTestRunner e TestingPlatformDotnetTestSupport como verdadeiro por padrão. Para obter mais informações sobre o teste dotnet e seus diferentes modos, consulte Teste com teste dotnet.

Testar bibliotecas de utilitários auxiliares

Se o project que usa MSTest.Sdk se destina a ser uma biblioteca auxiliar do utilitário de teste e, por si só, não contém nenhum teste executável, o project deve ter <IsTestApplication>false</IsTestApplication>.

Selecionar o corredor

Por padrão, o SDK do MSTest depende do MTP, mas você pode alternar para o VSTest adicionando a propriedade <UseVSTest>true</UseVSTest>.

Estender MTP

Você pode personalizar a experiência MTP por meio de um conjunto de extensões de pacote NuGet. Para simplificar e melhorar essa experiência, o SDK do MSTest apresenta dois recursos:

Microsoft.Testing.Platform Perfil

O conceito de profiles permite selecionar o conjunto padrão de configurações e extensões que serão aplicadas ao projeto de teste.

Você pode definir o perfil usando a propriedade TestingExtensionsProfile com um dos três perfis a seguir:

  • None - Nenhuma extensão está habilitada.

  • Default – Habilita as extensões recomendadas para esta versão do MSTest.SDK. Esse é o padrão quando a propriedade não é definida explicitamente.

    Habilita as seguintes extensões:

  • AllMicrosoft - Habilita as extensões da Microsoft selecionadas para uso imediato e amplo, incluindo extensões com uma licença restritiva. Extensões experimentais e somente de API ainda podem exigir aceitação explícita.

    Habilita todas as extensões do Default perfil, além das seguintes extensões:

    Nas versões 3.11.0 a 4.2.x do MSTest.Sdk, a extensão de relatório do Azure DevOps é incluída apenas em AllMicrosoft.

Observação

Os perfis fazem referência aos pacotes Azure DevOps Report e GitHub Actions Report, mas a geração de relatórios continua desabilitada em tempo de execução. Passe --report-azdo para habilitar Azure DevOps relatórios. Para habilitar os relatórios do GitHub Actions, execute os testes no GitHub Actions e forneça --report-gh.

Aqui está um exemplo completo, usando o perfil None:

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

    <PropertyGroup>
        <TargetFramework>net10.0</TargetFramework>
        <TestingExtensionsProfile>None</TestingExtensionsProfile>
    </PropertyGroup>

</Project>
Extensão/Perfil Nenhum Padrão AllMicrosoft
Cobertura de código ✔️ ✔️
Despejo de Memória ✔️
Falsos ✔️¹
Despejo de travamento ✔️
Recarga Rápida ✔️
Relatório HTML ✔️
Relatório GitHub Actions ✔️³ ✔️³
Tentar novamente ✔️
Trx ✔️ ✔️
Relatório Azure DevOps ✔️³ ✔️²

¹ MSTest.Sdk 3.7.0+ ² MSTest.Sdk 3.11.0+ XIV MSTest.Sdk 4.3.0+

Habilitar ou desabilitar extensões

As extensões podem ser habilitadas e desabilitadas pelas propriedades do MSBuild com o padrão Enable[NugetPackageNameWithoutDots].

Por exemplo, para habilitar a extensão de despejo de falha (pacote NuGet Microsoft.Testing.Extensions.CrashDump), você pode usar a seguinte propriedade EnableMicrosoftTestingExtensionsCrashDump definida como true:

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

<PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <EnableMicrosoftTestingExtensionsCrashDump>true</EnableMicrosoftTestingExtensionsCrashDump>
</PropertyGroup>

</Project>

Para obter uma lista de todas as extensões disponíveis, consulte os recursos do MTP.

Algumas extensões MTP permanecem opcionais e não estão incluídas nos perfis AllMicrosoft ou Default:

  • Começando com MSTest.Sdk 4.3, defina <EnableMicrosoftTestingExtensionsJUnitReport>true</EnableMicrosoftTestingExtensionsJUnitReport>e passe --report-junit.
  • Começando com a versão prévia do MSTest.Sdk 4.4, defina <EnableMicrosoftTestingExtensionsCtrfReport>true</EnableMicrosoftTestingExtensionsCtrfReport>e passe --report-ctrf.
  • Para fazer referência à extensão OpenTelemetry, defina <EnableMicrosoftTestingExtensionsOpenTelemetry>true</EnableMicrosoftTestingExtensionsOpenTelemetry>. Como a extensão requer configuração de API, registre-a no ponto de entrada personalizado, conforme descrito no OpenTelemetry.

Essas extensões só estão disponíveis com MTP.

Aviso

É importante revisar os termos de licenciamento de cada extensão, pois eles podem variar.

As extensões habilitadas e desabilitadas são combinadas com as extensões fornecidas pelo perfil de extensão selecionado.

Esse padrão de propriedade pode ser usado para habilitar uma extensão adicional, além do perfil implícito Default (como visto no exemplo anterior de CrashDumpExtension).

Você também pode desabilitar uma extensão proveniente do perfil selecionado. Por exemplo, desabilite a MS Code Coverage extensão definindo <EnableMicrosoftTestingExtensionsCodeCoverage>false</EnableMicrosoftTestingExtensionsCodeCoverage>:

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

    <PropertyGroup>
        <TargetFramework>net10.0</TargetFramework>
        <EnableMicrosoftTestingExtensionsCodeCoverage>false</EnableMicrosoftTestingExtensionsCodeCoverage>
    </PropertyGroup>

</Project>

No MSTest.Sdk 4.3.0 e posteriores, o perfil Default faz referência aos pacotes de relatório do Azure DevOps e do GitHub Actions. Para remover a referência do pacote, definir <EnableMicrosoftTestingExtensionsAzureDevOpsReport>false</EnableMicrosoftTestingExtensionsAzureDevOpsReport> ou <EnableMicrosoftTestingExtensionsGitHubActionsReport>false</EnableMicrosoftTestingExtensionsGitHubActionsReport>. Se você mantiver as referências do pacote, a geração de relatórios do Azure DevOps só começa quando você passa --report-azdo. A geração de relatórios do GitHub Actions só começa quando você executa os testes no GitHub Actions e informa --report-gh.

Recursos

Além da seleção do executor e das extensões específicas do executor, MSTest.Sdk também fornece recursos adicionais para simplificar e aprimorar sua experiência de teste.

Teste com Aspire

Aspire é uma pilha opinativa, pronta para a nuvem, para construir aplicações distribuídas, observáveis ​​e prontas para produção. Aspire é entregue por meio de uma coleção de pacotes NuGet que lidam com preocupações específicas nativas da nuvem. Para obter mais informações, consulte os Aspire documentos.

Observação

Esse recurso está disponível no MSTest.Sdk 3.4.0.

Ao definir a propriedade EnableAspireTesting como true, você pode trazer todas as dependências e diretivas padrão using necessárias para testes com Aspire e MSTest.

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

    <PropertyGroup>
        <TargetFramework>net10.0</TargetFramework>
        <EnableAspireTesting>true</EnableAspireTesting>
    </PropertyGroup>

</Project>

Teste com o Playwright

O Playwright permite testes confiáveis de ponta a ponta para aplicativos web modernos. Para obter mais informações, consulte os documentos oficiais do Playwright.

Observação

Esse recurso está disponível no MSTest.Sdk 3.4.0.

Ao definir a propriedade EnablePlaywright como true, você pode trazer todas as dependências e diretivas padrão using necessárias para testes com Playwright e MSTest.

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

    <PropertyGroup>
        <TargetFramework>net10.0</TargetFramework>
        <EnablePlaywright>true</EnablePlaywright>
    </PropertyGroup>

</Project>

Migrar para o SDK do MSTest

Considere as etapas a seguir necessárias para migrar para o SDK do MSTest.

Atualizar o projeto

Ao migrar um projeto de teste mstest existente para o SDK do MSTest, comece substituindo a entrada Sdk="Microsoft.NET.Sdk" na parte superior do projeto de teste por Sdk="MSTest.Sdk"

- Sdk="Microsoft.NET.Sdk"
+ Sdk="MSTest.Sdk"

Adicione a versão à sua global.json:

{
    "msbuild-sdks": {
        "MSTest.Sdk": "4.1.0"
    }
}

Em seguida, você pode começar a simplificar o seu projeto.

Remover as propriedades padrão:

- <EnableMSTestRunner>true</EnableMSTestRunner>
- <OutputType>Exe</OutputType>
- <IsPackable>false</IsPackable>
- <IsTestProject>true</IsTestProject>

Remover as referências de pacote padrão:

- <PackageReference Include="MSTest"
- <PackageReference Include="MSTest.TestFramework"
- <PackageReference Include="MSTest.TestAdapter"
- <PackageReference Include="MSTest.Analyzers"
- <PackageReference Include="Microsoft.NET.Test.Sdk"

Por fim, com base no perfil de extensões que você está usando, você também pode remover alguns dos pacotes Microsoft.Testing.Extensions.*.

Atualizar sua CI

Depois de atualizar seus projetos, se você estiver usando MTP (padrão) e se depender de dotnet test para executar seus testes, deverá atualizar sua configuração de CI. Para obter mais informações e orientar sua compreensão de todas as alterações necessárias, consulte integração de teste dotnet.

Se você estiver usando o modo VSTest de dotnet test, veja um exemplo de atualização ao usar a tarefa DotNetCoreCLI no Azure DevOps:

\- task: DotNetCoreCLI@2
  inputs:
    command: 'test'
    projects: '**/**.sln'
-    arguments: '--configuration Release'
+    arguments: '--configuration Release -- --report-trx --results-directory $(Agent.TempDirectory) --coverage'

Recursos experimentais

Os seguintes recursos do MSTest 4.3 são experimentais. Suas APIs públicas estão sujeitas a alterações e são disponibilizadas por meio de diagnósticos experimentais; portanto, para optar por usá-las, é necessário reconhecer o ID de diagnóstico correspondente. Use-os com essa ressalva em mente.

Gerador de origem de reflexão

Observação

Introduzido no MSTest 4.3.0 (experimental).

O gerador de origem de reflexão do MSTest descobre testes em tempo de compilação, em vez de depender de reflexão em runtime, o que torna os projetos de teste compatíveis com redução e AOT nativo. Habilite-o adicionando o pacote MSTest.SourceGeneration . Quando o gerador de origem está ativo, as classes de teste devem declarar [TestClass] diretamente, em vez de herdá-lo; o analisador MSTEST0069 sinaliza as classes que dependem de um [TestClass] herdado.

A partir do MSTest 4.3.2, MSTestSourceGenMode usa ReflectionFree por padrão para projetos com trimming e Native AOT.

A partir do MSTest 4.4, a geração sem reflexão materializa metadados de atributo herdados completos, incluindo AttributeUsage e AllowMultiple. Quando o gerador não consegue materializar metadados estaticamente, o MSTest recorre à reflexão quando há suporte do runtime.

Filtragem programática de testes com ITestFilter

Observação

Introduzido no MSTest 4.3.0 (experimental).

O ponto de extensão experimental ITestFilter , registrado por meio [TestFilterProviderAttribute], permite que você decida programaticamente se cada teste é executado antes de qualquer classe de teste ser carregada. Isso é útil para a lógica de seleção personalizada que não pode ser expressa com filtros de linha de comando.

Implemente ITestFilter.Filter(TestFilterContext) para inspecionar metadados sem carregar a classe de teste:

public sealed class MyFilter : ITestFilter
{
    public TestFilterResult Filter(TestFilterContext context) =>
        context.DisplayName.Contains("Nightly", StringComparison.Ordinal)
            ? TestFilterResult.Run : TestFilterResult.Drop;
}

Use TestFilterResult.Run para executar o teste, Drop para omiti-lo sem registrar um resultado, ou Skip(reason) para registrar um resultado como ignorado. O MSTest pode chamar uma instância de filtro simultaneamente, portanto, as implementações devem ser thread-safe. Os filtros da linha de comando e do Explorador de Testes são aplicados antes de ITestFilter, enquanto [Ignore] é avaliado depois.

A partir da versão 4.4 do MSTest, projetos .NET podem usar a forma genérica, com segurança de tipos, de registro [assembly: TestFilterProvider<MyFilter>]. Em seguida, o compilador garante que MyFilter implemente ITestFilter e tenha um construtor público sem parâmetros. O atributo genérico não está disponível para .NET Framework. Para um projeto direcionado a vários frameworks, selecione a forma genérica ou não genérica com um símbolo de pré-processador do framework de destino.

#if NET
[assembly: TestFilterProvider<MyFilter>]
#else
[assembly: TestFilterProvider(typeof(MyFilter))]
#endif

A partir do MSTest 4.4, o analisador MSTEST0081 valida totalmente o formulário de registro não genérico. Na forma genérica, ele ainda informa tipos de filtro genéricos e assemblies que registram mais de um provedor.

TestRun.Current e testes planejados

Observação

Introduzido no MSTest 4.3.0 (experimental).

A API experimental TestRun.Current (da RFC 014) expõe informações sobre a execução atual, incluindo o conjunto de testes planejados, para que extensões e fixtures possam inspecionar o que está agendado para execução.

Limitações conhecidas

Os SDKs do MSBuild fornecidos pelo NuGet (incluindo MSTest.Sdk) têm suporte limitado a ferramentas quando se trata de atualizar sua versão, o que significa que a atualização normal do NuGet e a interface do usuário do Visual Studio para gerenciar pacotes NuGet não funciona conforme o esperado. Você precisará atualizar manualmente a versão no arquivo global.json e no arquivo project. (Isso se aplica mesmo se você usar Dependabot devido a problemas dependabot-core#12824 e dependabot-core#8615.)

Confira também

  • Last updated on