dotnet test
Este artigo se aplica a: ✔️ SDK do .NET Core 3.1 e versões posteriores
dotnet test
- driver de teste do .NET usado para executar testes de unidade.
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
O comando dotnet test
é 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 . O host de teste executa testes no projeto determinado usando uma estrutura de teste, por exemplo: MSTest, NUnit ou xUnit e relata o êxito ou a falha de cada teste. Se todos os testes forem bem-sucedidos, o executor de testes retornará 0 como um código de saída; caso contrário, se algum teste falhar, retornará 1.
Observação
dotnet test
foi originalmente projetado para suportar apenas VSTest
projetos de teste baseados em . Versões recentes das estruturas de teste estão adicionando suporte para Microsoft.Testing.Platform. Essa plataforma de teste alternativa é mais leve e rápida e VSTest
oferece suporte a dotnet test
diferentes opções de linha de comando. Para obter mais informações, consulte Microsoft.Testing.Platform.
Para projetos com vários destinos, os testes são executados para cada estrutura de destino. 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 do projeto. A partir do SDK do .NET 9, esses testes são executados em paralelo por padrão. Para desabilitar 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>
, conforme mostrado no exemplo de arquivo de projeto a seguir:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net8.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>
Em que Microsoft.NET.Test.Sdk
é o host de teste e 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.
Não é necessário executar dotnet restore
, pois ele é executado implicitamente por todos os comandos que exigem uma restauração, como dotnet new
, dotnet build
, dotnet run
, dotnet test
, dotnet publish
e dotnet pack
. Para desabilitar a restauração implícita, use a opção --no-restore
.
O comando dotnet restore
ainda é útil em determinados cenários em que realizar uma restauração explícita faz sentido, como compilações de integração contínua no Azure DevOps Services ou em sistemas de compilação que precisam controlar explicitamente quando a restauração ocorrerá.
Para obter informações sobre como gerenciar feeds do NuGet, confira a documentação do dotnet restore
.
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 esse comando for concluído, o download será interrompido. Para saber mais, confira Manifestos de publicidade.
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 arquivo .dll de projeto de teste.
- Caminho para um arquivo .exe de projeto de teste.
Se não for especificado, o efeito será o mesmo que usar o argumento
DIRECTORY
para especificar o diretório atual.
Aviso
Alterações interruptivas nas opções:
- A partir do .NET 7: alternar
-a
para alias--arch
em vez de--test-adapter-path
- A partir do .NET 7: alternar
-r
para alias--runtime
em vez de--results-directory
Aviso
Ao usar Microsoft.Testing.Platform
o , consulte dotnet test integration para obter as opções com suporte. 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 para adaptadores de teste adicionais. Somente arquivos .dll com sufixo
.TestAdapter.dll
são inspecionados. Se não for especificado, o diretório do .dll de teste será pesquisado.Formulário curto
-a
disponível em versões do SDK do .NET anteriores a 7.
--arch <ARCHITECTURE>
Especifica a arquitetura de destino. Essa é uma sintaxe abreviada para definir o RID (Identificador de Runtime), em que o valor fornecido é combinado com o RID padrão. Por exemplo, em um computador
win-x64
, a especificação de--arch x86
define o RID comowin-x86
. Se você usar essa opção, não use a opção-r|--runtime
. Disponível desde a versão prévia 7 do .NET 6.
--artifacts-path <ARTIFACTS_DIR>
Todos os arquivos de saída de compilação do comando executado irão para subpastas no 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 blame. Essa opção é útil para isolar testes problemáticos que causam falha no host de teste. Quando uma falha é detectada, ela cria um arquivo de sequência em
TestResults/<Guid>/<Guid>_Sequence.xml
que 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á travando.
--blame-crash
(Disponível desde o SDK do .NET 5.0)Executa os testes no modo de responsabilidade e coleta um despejo de memória quando o host de teste é executado 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 em versões posteriores. Ele vai gerar um despejo para testhost ou qualquer processo filho que também tenha sido testado no .NET 5.0 e falhado. Falhas no código nativo não geram um despejo. Essa opção funciona no Windows, no macOS e no Linux.
Despejos de memória no código nativo ou ao usar o .NET Core 3.1 ou versões anteriores só podem ser coletados no Windows, usando Procdump. Um diretório que contém procdump.exe e procdump64.exe precisa estar na variável de ambiente PATH ou PROCDUMP_PATH. Baixe as 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 de Procdump pode ser forçado definindo a variável de ambiente
VSTEST_DUMP_FORCEPROCDUMP
como1
.--blame-crash-dump-type <DUMP_TYPE>
(Disponível desde o SDK do .NET 5.0)O tipo de despejo de memória a ser coletado. Os tipos de despejo com suporte são
full
(padrão) emini
. Implica--blame-crash
.--blame-crash-collect-always
(Disponível desde o SDK do .NET 5.0)Coleta um despejo de memória esperado, bem como uma saída inesperada do host de teste.
--blame-hang
(Disponível desde o SDK do .NET 5.0)Executar os testes no modo de responsabilidade e coletar um despejo de memória quando um teste exceder o tempo limite determinado.
--blame-hang-dump-type <DUMP_TYPE>
(Disponível desde o SDK do .NET 5.0)O tipo de despejo de memória a ser coletado. Deveria ser
full
,mini
ounone
. Quandonone
é especificado, o host de teste é encerrado no tempo limite, mas nenhum despejo é coletado. Implica--blame-hang
.--blame-hang-timeout <TIMESPAN>
(Disponível desde o SDK do .NET 5.0)Tempo limite por teste, após o qual um despejo de travamento é disparado e o processo do host de teste e todos os 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, 90minute, 90minutes
- 5400s, 5400sec, 5400second, 5400seconds
- 5400000ms, 5400000mil, 5400000millisecond, 5400000milliseconds
Quando nenhuma unidade é usada (por exemplo, 5400000), supõe-se que o valor esteja em milissegundos. Quando usado junto com testes controlados por dados, o comportamento do 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. No MSTest antes da versão 2.2.4, o tempo limite é usado para todos os casos de teste. Essa opção é compativel com o Windows com
netcoreapp2.1
e posteriores, no Linux comnetcoreapp3.1
e posterior e no macOS comnet5.0
ou posterior. Implica--blame
e--blame-hang
.
-c|--configuration <CONFIGURATION>
Define a configuração da compilação. O padrão da maioria dos projetos é
Debug
, mas você pode substituir as definições de configuração de build no projeto.
--collect <DATA_COLLECTOR_NAME>
Habilita o coletor de dados para a execução de teste. Para obter mais informações, consulte Monitor and analyze test run (Monitorar e analisar a execução de teste).
Por exemplo, você pode coletar cobertura de código usando a opção
--collect "Code Coverage"
. Para obter mais informações, confira Usar a cobertura de código, Personalizar a análise de cobertura de código e o problema do GitHub dotnet/docs#34479.Para coletar a cobertura de código, você também pode usar Coverlet usando a opção
--collect "XPlat Code Coverage"
.-d|--diag <LOG_FILE>
Habilita o modo de diagnóstico da plataforma de teste e grava mensagens de diagnóstico no arquivo especificado e nos arquivos ao lado dele. O processo que registra as mensagens em log determina quais arquivos são criados, como
*.host_<date>.txt
para o log do 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 TFM (Moniker da Estrutura de Destino) da estrutura de destino cujos testes serão executados. A estrutura de destino também precisa ser especificada no arquivo de projeto.
--filter <EXPRESSION>
Filtra os testes no projeto atual usando a expressão fornecida. Somente os testes que correspondem à expressão de filtro são executados. Para saber mais, confira a seção Filtrar detalhes da opção. Para obter mais informações e exemplos sobre como usar a filtragem de teste de unidade seletivo, confira Executando testes de unidade seletivos.
-?|-h|--help
Imprime uma descrição de como usar o comando.
--interactive
Permite que o comando pare e aguarde 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 agente para resultados de teste e, opcionalmente, alterna para o agente. Especifique esse parâmetro várias vezes para ativar vários registradores. Para obter mais informações, confira Resultados do teste de relatório, Opções para agentes e exemplos mais adiante neste artigo.
Para passar as opções de linha de comando para o agente:
- Use o nome completo da opção, não o formulário abreviado (por exemplo,
verbosity
em vez dev
). - Omita todos os traços à esquerda.
- Substitua o espaço que separa cada comutador por um ponto e vírgula
;
. - Se a opção tiver um valor, substitua o separador de dois-pontos entre essa opção e seu valor pelo sinal de igual
=
.
Por exemplo,
-v:detailed --consoleLoggerParameters:ErrorsOnly
se tornariaverbosity=detailed;consoleLoggerParameters=ErrorsOnly
.- Use o nome completo da opção, não o formulário abreviado (por exemplo,
--no-build
Não compila o projeto de teste antes de sua execução. Também define o sinalizador
--no-restore
implicitamente.--nologo
Executar testes, sem exibir a faixa do 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 encontram-se os binários para execução. Se não for especificado, o caminho padrão será
./bin/<configuration>/<framework>/
. Para projetos com várias estruturas de destino (por meio da propriedadeTargetFrameworks
), você também precisa definir--framework
quando especifica essa opção.dotnet test
sempre executa testes 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 opção
--output
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 opção--output
não é permitida, porque todas as saídas de todos os projetos criados serão copiadas para o diretório especificado, o que não é compatível com projetos multiplataforma, bem como projetos que têm diferentes versões de dependências diretas e transitivas. Para obter mais informações, confira A opção--output
no nível da solução não é mais válida para comandos relacionados à compilação.
--os <OS>
Especifica o sistema operacional (SO) de destino. Essa é uma sintaxe abreviada para definir o RID (Identificador de Runtime), em que o valor fornecido é combinado com o RID padrão. Por exemplo, em um computador
win-x64
, a especificação de--os linux
define o RID comolinux-x64
. Se você usar essa opção, não use a opção-r|--runtime
. Disponível desde o .NET 6.
--results-directory <RESULTS_DIR>
O diretório em que os resultados de teste serão colocados. Se o diretório especificado não existir, ele será criado. O padrão é
TestResults
no diretório que contém o arquivo de projeto.Formulário curto
-r
disponível em versões do SDK do .NET anteriores a 7.-r|--runtime <RUNTIME_IDENTIFIER>
O runtime de destino dos testes.
Formulário curto
-r
disponível a partir do SDK do .NET 7.-s|--settings <SETTINGS_FILE>
O arquivo
.runsettings
a ser usado para executar os testes. O elementoTargetPlatform
(x86|x64) não tem nenhum efeito paradotnet test
. Para executar testes direcionados ao x86, instale a versão x86 do .NET Core. O número de bit do dotnet.exe que está no caminho é o que será usado para executar testes. Para saber mais, consulte os recursos a seguir:-t|--list-tests
Listar os testes detectados em vez de executar os testes.
-v|--verbosity <LEVEL>
Define o nível de detalhes do comando. Os valores permitidos são
q[uiet]
,m[inimal]
,n[ormal]
,d[etailed]
ediag[nostic]
. O padrão éminimal
. Para obter mais informações, consulte LoggerVerbosity.
args
Especifica argumentos extras para passar ao 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, uma solução ou um diretório ou se você omite esse argumento, a chamada é encaminhada para
msbuild
. Nesse caso, os argumentos disponíveis podem ser encontrados na documentação do 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 do dotnet vstest.
- Quando você especifica um projeto, uma solução ou um diretório ou se você omite esse argumento, a chamada é encaminhada para
Argumentos de
RunSettings
RunSettings
embutidos são passados como os últimos argumentos na linha de comando após "-- " (observe o espaço após --). RunSettings
embutidos são especificados como pares [name]=[value]
. Um espaço é usado para separar vários pares [name]=[value]
.
Exemplo: dotnet test -- MSTest.DeploymentEnabled=false MSTest.MapInconclusiveToFailed=True
Para obter mais informações, confira Como passar argumentos de RunSettings por meio da linha de comando.
Execute os testes no projeto no diretório atual:
CLI do .NETdotnet test
Execute os testes no projeto
test1
:CLI do .NETdotnet test ~/projects/test1/test1.csproj
Executar os testes usando o assembly
test1.dll
:CLI do .NETdotnet test ~/projects/test1/bin/debug/test1.dll
Executar os testes no projeto no diretório atual e gerar um arquivo de resultados de teste no formato trx:
CLI do .NETdotnet test --logger trx
Executar os testes no projeto no diretório atual e gerar um arquivo de cobertura de código (depois de instalar a integração de coletores do Coverlet):
CLI do .NETdotnet test --collect:"XPlat Code Coverage"
Executar os testes no projeto no diretório atual e gerar um arquivo de cobertura de código (somente Windows):
CLI do .NETdotnet test --collect "Code Coverage"
Executar os testes no projeto no diretório atual e fazer logon com nível alto de detalhamento no console:
CLI do .NETdotnet test --logger "console;verbosity=detailed"
Executar os testes no projeto no diretório atual e fazer logon com o agente trx para testResults.trx na pasta TestResults:
CLI do .NETdotnet 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 de cada estrutura de destino substitui a saída das estruturas de destino anteriores. O arquivo é criado na pasta TestResults na pasta do projeto de teste, pois os caminhos relativos são em relação a essa pasta. O exemplo a seguir mostra como produzir um arquivo separado para cada estrutura de destino.
Executar os testes no projeto no diretório atual e fazer logon com o agente trx para arquivos na pasta TestResults, com nomes de arquivo exclusivos para cada estrutura de destino:
CLI do .NETdotnet test --logger:"trx;LogFilePrefix=testResults"
Executar os testes no projeto no diretório atual e fazer logon com o agente html para testResults.html na pasta TestResults:
CLI do .NETdotnet test --logger "html;logfilename=testResults.html"
Executar os testes no projeto no diretório atual e relatar os testes que estavam em andamento quando o host de teste falhou:
CLI do .NETdotnet test --blame
Execute os testes no projeto
test1
, fornecendo o argumento-bl
(log binário) paramsbuild
:CLI do .NETdotnet test ~/projects/test1/test1.csproj -bl
Execute os testes no projeto
test1
, definindo a propriedadeDefineConstants
do MSBuild comoDEV
:CLI do .NETdotnet test ~/projects/test1/test1.csproj -p:DefineConstants="DEV"
Execute os testes no projeto
test1
, definindo a propriedadeTestTfmsInParallel
do MSBuild comofalse
:CLI do .NETdotnet test ~/projects/test1/test1.csproj -p:TestTfmsInParallel=false
--filter <EXPRESSION>
<Expression>
tem o formato <property><operator><value>[|&<Expression>]
.
<property>
é um atributo de Test Case
. A seguir estão as propriedades com suporte nas estruturas populares de teste de unidade:
Estrutura de teste | Propriedades com suporte |
---|---|
MSTest |
|
xUnit |
|
NUnit |
|
O <operator>
descreve a relação entre a propriedade o valor:
Operador | Função |
---|---|
= |
Correspondência exata |
!= |
Sem correspondência exata |
~ |
Contém |
!~ |
Não contém |
<value>
é uma cadeia de caracteres. As pesquisas não diferenciam maiúsculas de minúsculas.
Uma expressão sem um <operator>
é automaticamente considerada como um contains
na propriedade FullyQualifiedName
(por exemplo, dotnet test --filter xyz
é o mesmo que dotnet test --filter FullyQualifiedName~xyz
).
As expressões podem ser associadas a operadores condicionais:
Operador | Função |
---|---|
| |
OU |
& |
AND |
Inclua expressões em 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 seletivo, confira Executando testes de unidade seletivos.
Comentários do .NET
O .NET é um projeto código aberto. Selecione um link para fornecer comentários: