teste dotnet

Artigo
04/06/2024

Este artigo aplica-se a: ✔️ SDK do .NET Core 3.1 e versões posteriores

Nome

dotnet test - Driver de teste .NET usado para executar testes de unidade.

Sinopse

dotnet test [<PROJECT> | <SOLUTION> | <DIRECTORY> | <DLL> | <EXE>]
    [--test-adapter-path <ADAPTER_PATH>]
    [-a|--arch <ARCHITECTURE>]
    [--artifacts-path <ARTIFACTS_DIR>]
    [--blame]
    [--blame-crash]
    [--blame-crash-dump-type <DUMP_TYPE>]
    [--blame-crash-collect-always]
    [--blame-hang]
    [--blame-hang-dump-type <DUMP_TYPE>]
    [--blame-hang-timeout <TIMESPAN>]
    [-c|--configuration <CONFIGURATION>]
    [--collect <DATA_COLLECTOR_NAME>]
    [-d|--diag <LOG_FILE>]
    [-f|--framework <FRAMEWORK>]
    [-e|--environment <NAME="VALUE">]
    [--filter <EXPRESSION>]
    [--interactive]
    [-l|--logger <LOGGER>]
    [--no-build]
    [--nologo]
    [--no-restore]
    [-o|--output <OUTPUT_DIRECTORY>]
    [--os <OS>]
    [--results-directory <RESULTS_DIR>]
    [-r|--runtime <RUNTIME_IDENTIFIER>]
    [-s|--settings <SETTINGS_FILE>]
    [-t|--list-tests]
    [-v|--verbosity <LEVEL>]
    [<args>...]
    [[--] <RunSettings arguments>]

dotnet test -h|--help

Description

O dotnet test comando é usado para executar testes de unidade em uma determinada solução. O dotnet test comando cria a solução e executa um aplicativo host de teste para cada projeto de teste na solução usando VSTest. O host de teste executa testes em um determinado projeto usando uma estrutura de teste, por exemplo: MSTest, NUnit ou xUnit, e relata o sucesso ou falha de cada teste. Se todos os testes forem bem-sucedidos, o executor de teste retornará 0 como um código de saída; caso contrário, se algum teste falhar, ele retornará 1.

Nota

dotnet test foi originalmente concebido para suportar apenas VSTestprojetos de teste baseados em projetos. Versões recentes das estruturas de teste estão adicionando suporte para Microsoft.Testing.Platform. Esta plataforma de teste alternativa é mais leve e mais rápida do que VSTest e suporta dotnet test diferentes opções de linha de comando. Para obter mais informações, consulte Microsoft.Testing.Platform.

Para projetos com várias orientações, são realizados testes para cada quadro visado. O host de teste e a estrutura de teste de unidade são empacotados como pacotes NuGet e são restaurados como dependências comuns para o projeto. A partir do SDK do .NET 9, esses testes são executados em paralelo por padrão. Para desativar a execução paralela, defina a TestTfmsInParallel propriedade MSBuild como false. Para obter mais informações, consulte Executar testes em paralelo e a linha de comando de exemplo mais adiante neste artigo.

Os projetos de teste especificam o executor de teste usando um elemento comum <PackageReference> , como visto no seguinte arquivo de projeto de exemplo:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.10.0" />
    <PackageReference Include="xunit" Version="2.8.1" />
    <PackageReference Include="xunit.runner.visualstudio" Version="2.8.1" />
  </ItemGroup>

</Project>

Onde Microsoft.NET.Test.Sdk está o host de teste, xunit é a estrutura de teste. E xunit.runner.visualstudio é um adaptador de teste, que permite que a estrutura xUnit funcione com o host de teste.

Restauração implícita

Você não precisa executar dotnet restore porque ele é executado implicitamente por todos os comandos que exigem uma restauração para ocorrer, como dotnet new, dotnet build, dotnet run, dotnet test, dotnet publishe dotnet pack. Para desativar a restauração implícita, use a --no-restore opção.

O dotnet restore comando ainda é útil em determinados cenários em que a restauração explícita faz sentido, como compilações de integração contínua nos Serviços de DevOps do Azure ou em sistemas de compilação que precisam controlar explicitamente quando a restauração ocorre.

Para obter informações sobre como gerenciar feeds NuGet, consulte a dotnet restore documentação.

Downloads de manifesto de carga de trabalho

Quando você executa esse comando, ele inicia um download assíncrono em segundo plano de manifestos de publicidade para cargas de trabalho. Se o download ainda estiver em execução quando este comando terminar, o download será interrompido. Para obter mais informações, consulte Manifestos de publicidade.

Argumentos

PROJECT | SOLUTION | DIRECTORY | DLL | EXE
- Caminho para o projeto de teste.
- Caminho para a solução.
- Caminho para um diretório que contém um projeto ou uma solução.
- Caminho para um projeto de teste .dll arquivo.
- Caminho para um projeto de teste .exe arquivo.
Se não for especificado, o efeito é o mesmo que usar o DIRECTORY argumento para especificar o diretório atual.

Opções

Aviso

Alterações significativas nas opções:

A partir do .NET 7: alterne -a para alias --arch em vez de --test-adapter-path
A partir do .NET 7: alterne -r para alias --runtime em vez de --results-directory

Aviso

Ao usar Microsoft.Testing.Platformo , consulte a integração do teste dotnet para obter as opções suportadas. Como regra geral, todas as opções não relacionadas ao teste são suportadas, enquanto todas as opções relacionadas ao teste não são suportadas no estado em que se encontram.

--test-adapter-path <ADAPTER_PATH>

Caminho para um diretório a ser pesquisado por adaptadores de teste adicionais. Somente .dll arquivos com sufixo .TestAdapter.dll são inspecionados. Se não for especificado, o diretório do .dll de teste será pesquisado.

Formulário -a curto disponível em versões do SDK do .NET anteriores a 7.

--arch <ARCHITECTURE>

Especifica a arquitetura de destino. Esta é uma sintaxe abreviada para definir o Runtime Identifier (RID), onde o valor fornecido é combinado com o RID padrão. Por exemplo, em uma win-x64 máquina, especificar --arch x86 define o RID como win-x86. Se você usar essa opção, não use a -r|--runtime opção. Disponível desde o .NET 6 Preview 7.

--artifacts-path <ARTIFACTS_DIR>

Todos os arquivos de saída de compilação do comando executado irão em subpastas sob o caminho especificado, separados por projeto. Para obter mais informações, consulte Layout de saída de artefatos. Disponível desde o SDK do .NET 8.

--blame

Executa os testes no modo de culpa. Essa opção é útil para isolar testes problemáticos que causam falhas no host de teste. Quando uma falha é detetada, ele cria um arquivo de sequência que TestResults/<Guid>/<Guid>_Sequence.xml captura a ordem dos testes que foram executados antes da falha.

Essa opção não cria um despejo de memória e não é útil quando o teste está suspenso.
--blame-crash (Disponível desde .NET 5.0 SDK)

Executa os testes no modo de culpa e coleta um despejo de memória quando o host de teste é encerrado inesperadamente. Essa opção depende da versão do .NET usada, do tipo de erro e do sistema operacional.

Para exceções no código gerenciado, um despejo será coletado automaticamente no .NET 5.0 e versões posteriores. Ele gerará um despejo para testhost ou qualquer processo filho que também foi executado no .NET 5.0 e falhou. Falhas no código nativo não gerarão um dump. Esta opção funciona no Windows, macOS e Linux.

Despejos de memória em código nativo, ou ao usar o .NET Core 3.1 ou versões anteriores, só podem ser coletados no Windows, usando o Procdump. Um diretório que contém procdump.exe e procdump64.exe deve estar na variável de ambiente PATH ou PROCDUMP_PATH. Faça o download das ferramentas. Implica --blame.

Para coletar um despejo de memória de um aplicativo nativo em execução no .NET 5.0 ou posterior, o uso do Procdump pode ser forçado definindo a VSTEST_DUMP_FORCEPROCDUMP variável de ambiente como 1.
--blame-crash-dump-type <DUMP_TYPE> (Disponível desde .NET 5.0 SDK)

O tipo de despejo de memória a ser coletado. Os tipos de despejo suportados são full (padrão) e mini. Implica --blame-crash.
--blame-crash-collect-always (Disponível desde .NET 5.0 SDK)

Coleta um despejo de memória na saída esperada e inesperada do host de teste.
--blame-hang (Disponível desde .NET 5.0 SDK)

Execute os testes no modo de culpa e coleta um despejo de bloqueio quando um teste excede o tempo limite determinado.
--blame-hang-dump-type <DUMP_TYPE> (Disponível desde .NET 5.0 SDK)

O tipo de despejo de memória a ser coletado. Deve ser full, miniou none. Quando none é especificado, o host de teste é encerrado no tempo limite, mas nenhum despejo é coletado. Implica --blame-hang.
--blame-hang-timeout <TIMESPAN> (Disponível desde .NET 5.0 SDK)

Tempo limite por teste, após o qual um despejo suspenso é acionado e o processo do host de teste e todos os seus processos filho são despejados e encerrados. O valor de tempo limite é especificado em um dos seguintes formatos:
- 1.5h, 1.5hour, 1.5hours
- 90m, 90min, 90minuto, 90minutos
- 5400s, 5400seg, 5400segundo, 5400segundos
- 5400000ms, 5400000mil, 5400000milissegundo, 5400000milissegundos
Quando nenhuma unidade é usada (por exemplo, 5400000), o valor é assumido como sendo em milissegundos. Quando usado em conjunto com testes controlados por dados, o comportamento de tempo limite depende do adaptador de teste usado. Para xUnit, NUnit. e MSTest 2.2.4+, o tempo limite é renovado após cada caso de teste. Para MSTest antes da versão 2.2.4, o tempo limite é usado para todos os casos de teste. Esta opção é suportada no Windows com netcoreapp2.1 e posterior, no Linux com netcoreapp3.1 e posterior, e no macOS com net5.0 ou posterior. Implica --blame e --blame-hang.

-c|--configuration <CONFIGURATION>

Define a configuração de compilação. O padrão para a maioria dos projetos é Debug, mas você pode substituir as definições de configuração de compilação em seu projeto.

--collect <DATA_COLLECTOR_NAME>

Habilita o coletor de dados para a execução de teste. Para obter mais informações, consulte Monitorar e analisar a execução do teste.

Por exemplo, você pode coletar cobertura de código usando a --collect "Code Coverage" opção. Para obter mais informações, consulte Usar cobertura de código, Personalizar análise de cobertura de código e Emitir dotnet/docs#34479 do GitHub.

Para coletar a cobertura do código, você também pode usar o Coverlet usando a --collect "XPlat Code Coverage" opção.
-d|--diag <LOG_FILE>

Habilita o modo de diagnóstico para a plataforma de teste e grava mensagens de diagnóstico no arquivo especificado e em arquivos próximos a ele. O processo que está registrando as mensagens determina quais arquivos são criados, como *.host_<date>.txt para o log de host de teste e *.datacollector_<date>.txt para o log do coletor de dados.
-e|--environment <NAME="VALUE">

Define o valor de uma variável de ambiente. Cria a variável se ela não existir, substitui se ela existir. O uso dessa opção forçará os testes a serem executados em um processo isolado. A opção pode ser especificada várias vezes para fornecer várias variáveis.
-f|--framework <FRAMEWORK>

O moniker da estrutura de destino (TFM) da estrutura de destino para a qual executar testes. A estrutura de destino também deve ser especificada no arquivo de projeto.
--filter <EXPRESSION>

Filtra testes no projeto atual usando a expressão dada. Somente testes que correspondem à expressão de filtro são executados. Para obter mais informações, consulte a seção Detalhes da opção Filtro. Para obter mais informações e exemplos sobre como usar a filtragem de teste de unidade seletiva, consulte Executando testes de unidade seletiva.

-?|-h|--help

Imprime uma descrição de como usar o comando.

--interactive

Permite que o comando pare e aguarde a entrada ou ação do usuário. Por exemplo, para concluir a autenticação. Disponível desde o SDK do .NET Core 3.0.

-l|--logger <LOGGER>

Especifica um registrador para resultados de teste e, opcionalmente, alterna para o registrador. Especifique esse parâmetro várias vezes para habilitar vários registradores. Para obter mais informações, consulte Relatórios de resultados de testes, Opções para registradores e os exemplos mais adiante neste artigo.

Para passar opções de linha de comando para o registrador:
- Use o nome completo do switch, não a forma abreviada (por exemplo, verbosity em vez de v).
- Omita quaisquer traços à esquerda.
- Substitua o espaço que separa cada interruptor por um ponto-e-vírgula ;.
- Se o switch tiver um valor, substitua o separador de dois pontos entre esse switch e seu valor pelo sinal =de igual .
Por exemplo, -v:detailed --consoleLoggerParameters:ErrorsOnly tornar-se-ia verbosity=detailed;consoleLoggerParameters=ErrorsOnly.
--no-build

Não cria o projeto de teste antes de executá-lo. Também coloca implicitamente a --no-restore bandeira.
--nologo

Execute testes sem exibir o banner Microsoft TestPlatform. Disponível desde o SDK do .NET Core 3.0.
--no-restore

Não executa uma restauração implícita ao executar o comando.
-o|--output <OUTPUT_DIRECTORY>

Diretório no qual encontrar os binários a serem executados. Se não for especificado, o caminho padrão será ./bin/<configuration>/<framework>/. Para projetos com várias estruturas de destino (por meio da TargetFrameworks propriedade), você também precisa definir --framework quando especificar essa opção. dotnet test sempre executa testes a partir do diretório de saída. Você pode usar AppDomain.BaseDirectory para consumir ativos de teste no diretório de saída.
- SDK do .NET 7.0.200 e posterior
  
  Se você especificar a --output opção ao executar esse comando em uma solução, a CLI emitirá um aviso (um erro em 7.0.200) devido à semântica pouco clara do caminho de saída. A --output opção não é permitida porque todas as saídas de todos os projetos construídos seriam copiadas para o diretório especificado, que não é compatível com projetos com vários destinos, bem como projetos que têm diferentes versões de dependências diretas e transitivas. Para obter mais informações, consulte A opção de nível --output de solução não é mais válida para comandos relacionados à compilação.

--os <OS>

Especifica o sistema operacional (SO) de destino. Esta é uma sintaxe abreviada para definir o Runtime Identifier (RID), onde o valor fornecido é combinado com o RID padrão. Por exemplo, em uma win-x64 máquina, especificar --os linux define o RID como linux-x64. Se você usar essa opção, não use a -r|--runtime opção. Disponível desde .NET 6.

--results-directory <RESULTS_DIR>

O diretório onde os resultados do teste serão colocados. Se o diretório especificado não existir, ele será criado. O padrão está TestResults no diretório que contém o arquivo de projeto.

Formulário -r curto disponível em versões do SDK do .NET anteriores a 7.
-r|--runtime <RUNTIME_IDENTIFIER>

O tempo de execução de destino para testar.

Formulário -r curto disponível a partir do .NET SDK 7.
-s|--settings <SETTINGS_FILE>

O .runsettings arquivo a ser usado para executar os testes. O TargetPlatform elemento (x86|x64) não tem efeito para dotnet test. Para executar testes destinados a x86, instale a versão x86 do .NET Core. A mordida do dotnet.exe que está no caminho é o que será usado para executar testes. Para obter mais informações, consulte os seguintes recursos:
- Configure testes de unidade usando um .runsettings arquivo.
- Configurar uma execução de teste
-t|--list-tests

Liste os testes descobertos em vez de executar os testes.

-v|--verbosity <LEVEL>

Define o nível de detalhamento do comando. Os valores permitidos são q[uiet], m[inimal], n[ormal], d[etailed], e diag[nostic]. A predefinição é minimal. Para obter mais informações, veja LoggerVerbosity.

args

Especifica argumentos extras a serem passados para o adaptador. Use um espaço para separar vários argumentos.

A lista de argumentos possíveis depende do comportamento especificado:
- Quando você especifica um projeto, solução ou um diretório, ou se omite esse argumento, a chamada é encaminhada para msbuild. Nesse caso, os argumentos disponíveis podem ser encontrados na documentação dotnet msbuild.
- Quando você especifica um .dll ou um .exe, a chamada é encaminhada para vstest. Nesse caso, os argumentos disponíveis podem ser encontrados na documentação dotnet vstest.
RunSettings Argumentos

Inline RunSettings são passados como os últimos argumentos na linha de comando após "-- " (observe o espaço após --). Inline RunSettings são especificados como [name]=[value] pares. Um espaço é usado para separar vários [name]=[value] pares.

Exemplo: dotnet test -- MSTest.DeploymentEnabled=false MSTest.MapInconclusiveToFailed=True

Para obter mais informações, consulte Passando argumentos RunSettings pela linha de comando.

Exemplos

Execute os testes no projeto no diretório atual:
```
dotnet test
```

Execute os testes no test1 projeto:

dotnet test ~/projects/test1/test1.csproj

Execute os testes usando test1.dll assembly:

dotnet test ~/projects/test1/bin/debug/test1.dll

Execute os testes no projeto no diretório atual e gere um arquivo de resultados de teste no formato trx:
```
dotnet test --logger trx
```
Execute os testes no projeto no diretório atual e gere um arquivo de cobertura de código (depois de instalar a integração de coletores Coverlet ):
```
dotnet test --collect:"XPlat Code Coverage"
```
Execute os testes no projeto no diretório atual e gere um arquivo de cobertura de código (somente Windows):
```
dotnet test --collect "Code Coverage"
```
Execute os testes no projeto no diretório atual e registre com verbosidade detalhada no console:
```
dotnet test --logger "console;verbosity=detailed"
```
Execute os testes no projeto no diretório atual e faça log com o registrador trx para testResults.trx na pasta TestResults :
```
dotnet test --logger "trx;logfilename=testResults.trx"
```
Como o nome do arquivo de log é especificado, o mesmo nome é usado para cada estrutura de destino no caso de um projeto com vários destinos. A saída para cada estrutura de destino substitui a saída para as estruturas de destino anteriores. O arquivo é criado na pasta TestResults na pasta do projeto de teste, porque os caminhos relativos são relativos a essa pasta. O exemplo a seguir mostra como produzir um arquivo separado para cada estrutura de destino.
Execute os testes no projeto no diretório atual e faça log com o registrador trx em arquivos na pasta TestResults , com nomes de arquivo exclusivos para cada estrutura de destino:
```
dotnet test --logger:"trx;LogFilePrefix=testResults"
```
Execute os testes no projeto no diretório atual e faça log com o registrador html para testResults.html na pasta TestResults :
```
dotnet test --logger "html;logfilename=testResults.html"
```
Execute os testes no projeto no diretório atual e relate os testes que estavam em andamento quando o host de teste falhou:
```
dotnet test --blame
```
Execute os testes no test1 projeto, fornecendo o -bl argumento (log binário) para msbuild:
```
dotnet test ~/projects/test1/test1.csproj -bl
```
Execute os testes no test1 projeto, definindo a propriedade MSBuild DefineConstants como DEV:
```
dotnet test ~/projects/test1/test1.csproj -p:DefineConstants="DEV"
```
Execute os testes no test1 projeto, definindo a propriedade MSBuild TestTfmsInParallel como false:
```
dotnet test ~/projects/test1/test1.csproj -p:TestTfmsInParallel=false
```

--filter <EXPRESSION>

<Expression> tem o formato <property><operator><value>[|&<Expression>].

<property> é um atributo do Test Case. A seguir estão as propriedades suportadas por estruturas de teste de unidade populares:

Estrutura de teste	Propriedades suportadas
MSTest	FullyQualifiedName Nome ClassName Prioridade TestCategory
xUnidade	FullyQualifiedName DisplayName Categoria
NUnit	FullyQualifiedName Nome Categoria Prioridade

O <operator> descreve a relação entre a propriedade e o valor:

Operador	Function
`=`	Correspondência exata
`!=`	Correspondência não exata
`~`	Contains
`!~`	Não contém

<value> é uma cadeia de caracteres. Todas as pesquisas não diferenciam maiúsculas de minúsculas.

Uma expressão sem um <operator> é automaticamente considerada como uma propriedade on FullyQualifiedName (por exemplo, dotnet test --filter xyz é igual contains a dotnet test --filter FullyQualifiedName~xyz).

As expressões podem ser unidas com operadores condicionais:

Operador	Function
`\|`	OU
`&`	AND

Você pode colocar expressões entre parênteses ao usar operadores condicionais (por exemplo, (Name~TestMethod1) | (Name~TestMethod2)).

Para obter mais informações e exemplos sobre como usar a filtragem de teste de unidade seletiva, consulte Executando testes de unidade seletiva.

Partilhar via