dotnet test

  • Artigo

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

Nome

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

Sinopse

dotnet test [<PROJECT> | <SOLUTION> | <DIRECTORY> | <DLL> | <EXE>]
    [--test-adapter-path <ADAPTER_PATH>]
    [-a|--arch <ARCHITECTURE>]
    [--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

Descrição

O comando dotnet test é usado para executar testes de unidade em uma determinada solução. O comando dotnet test cria a solução e executa um aplicativo host de teste para cada projeto de teste na soluçã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.

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>net6.0</TargetFramework>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.9.0" />
    <PackageReference Include="xunit" Version="2.7.1" />
    <PackageReference Include="xunit.runner.visualstudio" Version="2.5.8" />
  </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.

Restauração implícita

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.

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 esse comando for concluído, o download será interrompido. Para saber mais, confira 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 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.

Opções

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

  • --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 como win-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.

  • --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 como 1.

  • --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) e mini. 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 ou 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 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 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 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 de v).
    • 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 tornaria verbosity=detailed;consoleLoggerParameters=ErrorsOnly.

  • --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 propriedade TargetFrameworks), 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 como linux-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 elemento TargetPlatform (x86|x64) não tem nenhum efeito para dotnet 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] e diag[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.

  • 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.

Exemplos

  • Execute os testes no projeto no diretório atual:

    dotnet test

  • Execute os testes no projeto test1:

    dotnet test ~/projects/test1/test1.csproj

  • Executar os testes usando o assembly test1.dll:

    dotnet 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:

    dotnet 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):

    dotnet 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):

    dotnet test --collect "Code Coverage"

  • Executar os testes no projeto no diretório atual e fazer logon com nível alto de detalhamento no console:

    dotnet 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:

    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 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:

    dotnet 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:

    dotnet 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:

    dotnet test --blame

  • Execute os testes no projeto test1, fornecendo o argumento -bl (log binário) para msbuild:

    dotnet test ~/projects/test1/test1.csproj -bl

  • Execute os testes no projeto test1, definindo a propriedade DefineConstants do MSBuild como DEV:

    dotnet test ~/projects/test1/test1.csproj -p:DefineConstants="DEV"

  • Execute os testes no projeto test1, definindo a propriedade TestTfmsInParallel do MSBuild como false:

    dotnet test ~/projects/test1/test1.csproj -p:TestTfmsInParallel=false

Filtrar detalhes da opção

--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
  • FullyQualifiedName
  • Nome
  • ClassName
  • Prioridade
  • TestCategory
xUnit
  • FullyQualifiedName
  • DisplayName
  • Categoria
NUnit
  • FullyQualifiedName
  • Nome
  • Categoria
  • Prioridade

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.

Confira também