Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Esso artigo se aplica a: ✔️ .NET 10 SDK e versões posteriores
Nome
dotnet test – .NET driver de teste usado para executar testes de unidade com MTP.
Sinopse
dotnet test
[<PROJECT_OR_TRAVERSAL_PATH>]
[--project <PROJECT_PATH>]
[--solution <SOLUTION_PATH>]
[--test-modules <EXPRESSION>]
[--root-directory <ROOT_PATH>]
[--max-parallel-test-modules <NUMBER>]
[--config-file <CONFIG_FILE>]
[--results-directory <RESULTS_DIRECTORY>]
[--results-directory-layout <flat|per-module>]
[--diagnostic-output-directory <DIAGNOSTIC_OUTPUT_DIRECTORY>]
[--minimum-expected-tests <NUMBER>]
[--maximum-failed-tests <NUMBER>]
[--timeout <DURATION>]
[-e|--environment <NAME="VALUE">]
[-a|--arch <ARCHITECTURE>]
[--artifacts-path <ARTIFACTS_DIR>]
[-c|--configuration <CONFIGURATION>]
[-f|--framework <FRAMEWORK>]
[--os <OS>]
[-r|--runtime <RUNTIME_IDENTIFIER>]
[--use-current-runtime|--ucr]
[-v|--verbosity <LEVEL>]
[--no-build]
[--no-dependencies]
[--no-restore]
[--nologo|--no-logo|--no-banner]
[--no-ansi]
[--no-progress]
[--no-artifact-post-processing]
[--output <VERBOSITY_LEVEL>]
[--show-test-results <OUTCOME>]
[--list-tests [text|json]]
[--no-launch-profile]
[--no-launch-profile-arguments]
[--device <DEVICE_ID>]
[--list-devices]
[--collect-test-map]
[--affected-tests]
[<args>...]
dotnet test -h|--help
Description
Com o MTP, dotnet test opera mais rápido do que com o VSTest. Os argumentos relacionados ao teste não são mais corrigidos, pois estão vinculados às extensões registradas nos project(s) de teste). Além disso, o MTP dá suporte a um filtro de globbing ao executar testes. Para obter mais informações, consulte MTP.
Importante
As opções específicas de extensão não são incorporadas ao MTP. Cada aplicativo de teste direcionado deve registrar a extensão que fornece uma opção. Adicione o pacote NuGet da extensão diretamente ou use uma configuração ou perfil do SDK de teste que inclua o pacote. Caso contrário, a execução de teste falhará com o código de saída 5 porque a opção não é reconhecida. Execute dotnet test --help para ver as opções disponíveis para os aplicativos de teste selecionados e veja as opções de extensão por cenário para localizar o pacote para uma opção.
Aviso
Quando o MTP é optado por via global.json, dotnet test espera que todos os projetos de teste usem MTP. Será um erro se algum dos projetos de teste usar o VSTest.
Requisitos de versão
O modo MTP de dotnet test requer o .NET 10 SDK e MTP 1.7 ou posterior. As opções adicionadas após .NET 10 têm requisitos individuais de versão do SDK nas seções a seguir. Algumas opções também exigem um pacote MTP mais recente porque o SDK coordena a execução completa enquanto cada aplicativo de teste implementa a funcionalidade correspondente.
Restauração implícita
Você não precisa executar dotnet restore porque ela é executada implicitamente por todos os comandos que exigem que uma restauração ocorra, como dotnet new, dotnet build, dotnet run, dotnet test, dotnet publishe 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 a restauração explícita faz sentido, como compilações de integração continuosas no Azure DevOps Services ou em sistemas de build que precisam controlar explicitamente quando a restauração ocorre.
Para obter informações sobre como gerenciar feeds do NuGet, consulte a documentação dotnet restore.
Opções
Observação
Você pode usar apenas uma das seguintes opções por vez: --project, --solution ou --test-modules. Essas opções não podem ser combinadas.
Além disso, quando você usa --test-modules, não é possível especificar --arch, , --configuration, --device, --framework, , --list-devices, --os, --runtimeou --use-current-runtime. Essas opções exigem avaliação de projeto ou não são relevantes para um módulo já criado.
PROJECT_OR_TRAVERSAL_PATHEspecifica um projeto ou projeto de passagem a ser executado. A partir do .NET 11 Versão Prévia 7,
dotnet testdá suporteMicrosoft.Build.Traversala projetos, comodirs.proj, e executa recursivamente seus projetos de teste referenciados.Começando com .NET 12 Versão Prévia 1, o argumento também pode identificar um aplicativo de teste MTP baseado em arquivo C#. Aplicativos de teste baseados em arquivo não dão suporte
--devicea .--project <PROJECT_PATH>Especifica o caminho do arquivo project a ser executado (nome da pasta ou caminho completo). Se não é especificado, ele usa como padrão o diretório atual.
--solution <SOLUTION_PATH>Especifica o caminho do arquivo de solução a ser executado (nome da pasta ou caminho completo). Se não é especificado, ele usa como padrão o diretório atual.
--test-modules <EXPRESSION>Filtra os módulos de teste usando o globbing de arquivo. Somente testes pertencentes a esses módulos de teste são executados. Começando com .NET 11 Versão Prévia 6, prefixe um padrão para
!excluir módulos correspondentes. Separar vários padrões com ponto-e-vírgula; o espaço em branco em torno de cada padrão é ignorado.--root-directory <ROOT_PATH>Especifica o diretório raiz da opção
--test-modules. Ele só pode ser usado com a opção--test-modules.--max-parallel-test-modules <NUMBER>Especifica o número máximo de módulos de teste que podem ser executados em paralelo. O padrão é Environment.ProcessorCount.
--config-file <CONFIG_FILE>Especifica o arquivo de configuração a ser usado para execução de teste. Se um caminho relativo for fornecido, ele será convertido em um caminho absoluto com base no diretório atual. Para obter mais informações sobre as configurações do arquivo de configuração, consulte testconfig.json.
--results-directory <RESULTS_DIRECTORY>Especifica o diretório em que os resultados do teste são armazenados. Se o diretório não existir, ele será criado. Se um caminho relativo for fornecido, ele será convertido em um caminho absoluto com base no diretório atual.
--results-directory-layout <flat|per-module>Especifica como uma execução de vários módulos organiza arquivos no diretório de resultados. O padrão grava
flattodos os resultados no mesmo diretório.per-modulegrava os resultados<project>/<target-framework>_<runtime-or-architecture>de cada módulo, o que impede que relatórios com o mesmo nome de arquivo substituam uns aos outros.Disponível a partir do .NET 11 RC 1.
--diagnostic-output-directory <DIAGNOSTIC_OUTPUT_DIRECTORY>Especifica o diretório em que a saída de diagnóstico é armazenada. Se o diretório não existir, ele será criado. Se um caminho relativo for fornecido, ele será convertido em um caminho absoluto com base no diretório atual.
--minimum-expected-tests <NUMBER>Especifica um número mínimo positivo de testes para toda a execução. Se a contagem de testes agregados for menor que o mínimo especificado, a execução do teste falhará com o código de saída 9. A contagem global inclui testes ignorados. Para obter mais informações sobre códigos de saída, consulte códigos de saída mtp.
Como essa opção é exibida antes
--, é uma opção global (inteira). Para exigir um mínimo para cada módulo de teste, passe a opção depois--para que ele seja encaminhado para cada módulo de teste. Para obter mais informações, consulte os mínimos de execução inteira e por módulo.Observação
O mínimo global requer o .NET 10 SDK (10.0.100) ou uma versão posterior.
--maximum-failed-tests <NUMBER>Interrompe a execução completa depois de atingir o número especificado de testes com falha, erro, tempo limite ou cancelados. A execução é encerrada com o código 13.
Disponível a partir do .NET 11 Versão Prévia 7 e requer MTP 2.4 ou posterior.
--timeout <DURATION>Interrompe a execução completa após a duração especificada enquanto pelo menos um aplicativo de teste está em execução. Especifique um número positivo seguido por uma unidade, como
500ms, ,90s,10m,2hou1d. Uma execução com tempo limite é encerrada com o código 3.Disponível a partir do .NET 11 Versão Prévia 7 e requer MTP 2.4 ou posterior.
-e|--environment <NAME="VALUE">Define uma variável de ambiente para o processo de teste. Especifique a opção várias vezes para definir várias variáveis. Valores de linha de comando substituem valores de um perfil de inicialização.
Use .NET SDK 10.0.110 ou posterior quando nenhum perfil de inicialização existir ou quando você especificar
--no-launch-profile; versões anteriores do SDK .NET 10 podem ignorar as variáveis nesses casos. A partir do .NET 11 Versão Prévia 7, as variáveis também fluem para destinos de build, seleção de dispositivo, implantação e run-argument com reconhecimento de capacidade.-
-a|--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 x86define o RID comowin-x86. Se você usar essa opção, não use a opção-r|--runtime. Disponível desde .NET 6 Versão Prévia 7. -
--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. Essa opção e o valor fornecido devem ser explicitamente em cascata em qualquer
dotnetcomando que dependa da saída de outrodotnetcomando, por exemplo, ao usardotnet build --no-restoreedotnet publish --no-build. Disponível desde .NET 8 SDK.Disponível para o modo MTP começando com .NET 11.
-
-c|--configuration <CONFIGURATION>Define a configuração de build. O padrão para a maioria dos projetos é
Debug, mas você pode substituir as configurações de build em seu project. -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 deve ser especificada no arquivo project.
-
--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 linuxdefine o RID comolinux-x64. Se você usar essa opção, não use a opção-r|--runtime. Disponível desde .NET 6. -r|--runtime <RUNTIME_IDENTIFIER>O runtime de destino dos testes.
Formulário curto
-rdisponível a partir .NET SDK 7.Observação
Não há suporte para a execução de testes para uma solução com uma propriedade global
RuntimeIdentifier(explicitamente ou via--arch,--runtimeou--os) . DefinaRuntimeIdentifierem um nível de project individual.--use-current-runtime|--ucrUsa o runtime atual como o runtime de destino durante a restauração e o build.
Disponível a partir do .NET 11 Versão Prévia 6. Você não pode combinar essa opção com
--test-modules.-
-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]. Para obter mais informações, consulte LoggerVerbosity. --no-buildEspecifica que o project de teste não foi criado antes de ser executado. Ele também define implicitamente o sinalizador
--no-restore.--no-dependenciesIgnora a criação de referências projeto a projeto.
Disponível a partir do .NET 11 Versão Prévia 6.
--no-restoreEspecifica que uma restauração implícita não é executada ao executar o comando.
--nologo|--no-logo|--no-bannerSuprime as faixas de inicialização .NET e MTP. Os
-nologoformulários e/nologoa variável deDOTNET_NOLOGOambiente também têm suporte.Disponível no modo MTP começando com .NET 11 Versão Prévia 7.
--no-ansiDesabilita a saída de caracteres de escape ANSI para a tela.
--no-progressDesabilita o progresso do relatório na tela.
--no-artifact-post-processingDesabilita o pós-processamento de artefatos compatíveis após uma execução de vários módulos. Começando com .NET 11 RC 1 e MTP 2.4, os pós-processadores de artefatos registrados podem combinar relatórios compatíveis, como resultados TRX. Se o pós-processamento falhar, o SDK preservará os artefatos originais e o código de saída do teste.
--output <VERBOSITY_LEVEL>Especifica a verbosidade de saída para os resultados do teste. Os valores válidos são
Minimal,NormaleDetailed. O padrão éNormal.Minimalrequer a versão prévia do MTP 2.4.--show-test-results <OUTCOME>Seleciona blocos de resultados por resultado. Na versão prévia do MTP 2.4, use
passed,failed,skipped, ouallnone. Ofailedvalor também inclui erros, tempos limite e cancelamentos.Combine
passed,failedeskippedcom vírgulas, espaços ou opções repetidas--show-test-results. Não combineallounonecom outro valor. Essa opção explícita substitui a--outputpredefinição independentemente da ordem de opção.--list-tests [text|json]Lista os testes descobertos sem executá-los. Omita o valor ou especifique
texta saída legível por humanos. A partir do .NET 11 Versão Prévia 7, especifiquejsonum documento JSON com versão que agrupa testes por assembly, estrutura de destino e arquitetura e inclui identificadores disponíveis, locais de origem, métodos, parâmetros e características.--no-launch-profileNão tente usar launchSettings.json para configurar o aplicativo. Por padrão,
launchSettings.jsoné usado, o que pode aplicar variáveis de ambiente e argumentos de linha de comando ao executável de teste.--no-launch-profile-argumentsNão use argumentos especificados pelo
commandLineArgsperfil de inicialização para executar o aplicativo.--device <DEVICE_ID>Seleciona um dispositivo, emulador ou simulador para cada estrutura de destino em um projeto de teste do Android ou iOS. O caminho mtp também dá suporte a projetos de teste macOS e Mac Catalyst. Se a entrada for interativa e mais de um dispositivo estiver disponível,
dotnet testpoderá solicitar que você selecione um.Disponível a partir do .NET 11 Versão Prévia 6. Para projetos com vários destinos, use .NET 11 RC 2 ou posterior para que a descoberta de dispositivos avalie cada estrutura de destino corretamente. Não há suporte para projetos de teste do WebAssembly do navegador por essa opção.
--list-devicesLista os dispositivos disponíveis para um projeto sem executar testes. Especifique um projeto em vez de uma solução.
Disponível a partir do .NET 11 Versão Prévia 7.
--collect-test-mape--affected-testsColete um mapa de teste do repositório ou execute testes afetados por uma alteração. Essas opções experimentais exigem uma extensão distribuída separadamente e a variável de
DOTNET_CLI_ENABLE_AFFECTED_TESTS=1ambiente. Você não pode combinar as duas opções. Os fluxos de trabalho de teste afetados também não dão suporte a testes de dispositivos, módulos de teste paralelos ou políticas de teste mínimo.Disponível a partir do .NET 11 RC 1.
--property:<NAME>=<VALUE>Define uma ou mais propriedades do MSBuild. Especifique várias propriedades repetindo a opção:
--property:<NAME1>=<VALUE1> --property:<NAME2>=<VALUE2>O formulário curto
-ppode ser usado para--property. O mesmo se aplica a/property:property=valuee sua forma curta é/p. Mais informações sobre os argumentos disponíveis podem ser encontradas na documentação do dotnet msbuild.-
-?|-h|--helpImprime uma descrição de como usar o comando.
argsEspecifica argumentos extras a serem passados para os aplicativos de teste. Use um espaço para separar vários argumentos. Para obter mais informações e exemplos sobre o que passar, consulte a visão geral do MTP e os recursos de MTP.
Dica
Para especificar argumentos extras para projetos específicos, use a propriedade
TestingPlatformCommandLineArgumentsMSBuild. Essa propriedade é especialmente útil quando sua solução combina estruturas de teste (por exemplo, MSTest e xUnit.net) ou quando apenas alguns projetos fazem referência a uma extensão específica. Para obter mais informações, consulte Soluções com estruturas de teste mistas ou extensões.
Observação
Para habilitar o registro em log de rastreamento em um arquivo, use a variável de ambiente DOTNET_CLI_TEST_TRACEFILE para fornecer o caminho para o arquivo de rastreamento.
Começando com .NET 11 RC 1, dotnet test -bl usa uma sessão do MSBuild para execuções de vários projetos, multilocatários e dispositivos para que o log binário contenha o build completo.
Comportamento de saída e cancelamento
Começando com .NET 11 Versão Prévia 6, a saída interativa de ANSI mostra testes que estão em execução no momento e relata contagens de teste por assembly. A exibição de progresso permanece desabilitada quando a saída é redirecionada, ANSI ou saída de progresso está desabilitada ou o ambiente não é interativo.
A partir do .NET 11 Versão Prévia 6, o primeiro Ctrl+C para de agendar novos aplicativos de teste e solicita cancelamento cooperativo. Pressione Ctrl+C novamente para encerrar os processos filho imediatamente. Uma execução anulada é encerrada com o código 3.
A saída do host de teste ao vivo requer um host MTP compatível com o protocolo 1.1 ou posterior. Hosts mais antigos mantêm a saída capturada e reproduz-a para um módulo com falha. Começando com .NET 11 Versão Prévia 7, os resumos de falha truncam a saída padrão capturada com mais de 40 linhas para as primeiras 30 e as últimas 10 linhas; os logs de diagnóstico mantêm a saída completa.
Para execuções de vários módulos, dotnet test avalia o resultado de teste zero na execução completa, começando com .NET 11 Versão Prévia 7. Um módulo sem testes não falhará na execução se outro módulo executar testes com êxito, a menos que uma política de teste mínimo explícita exija mais testes.
Resultados e artefatos
Quando o layout de saída de artefatos do SDK estiver habilitado, .NET 11 versões RC 1 e posteriores colocarão relatórios MTP, arquivos de cobertura e diagnósticos sob <ArtifactsPath>/test/<project>/<pivot> o padrão. Um explícito --results-directory ou --results-directory-layout tem precedência.
Começando com .NET 11 RC 1 e MTP 2.4, extensões compatíveis podem pós-processar artefatos de uma execução de vários módulos. Por exemplo, a extensão TRX pode criar um relatório mesclado preservando os relatórios por módulo. Para obter os requisitos de extensão e relatório, consulte os relatórios de teste do MTP.
Encaminhar argumentos para o aplicativo de teste
dotnet test encaminha qualquer token que ele não reconhece para o aplicativo de teste. Quando uma opção reconhecida aparece entre um nome de opção não reconhecido e seu valor, remover a opção reconhecida pode alterar a forma como os tokens de sobra se associam às opções no aplicativo de teste. Para evitar essa ambiguidade, coloque argumentos de aplicativo de teste após um literal --:
dotnet test --results-directory TestResults -- --report-trx --report-trx-filename A.trx
O exemplo anterior requer o Microsoft.Testing.Extensions.TrxReport pacote, seja como uma referência de pacote direto ou por meio de uma configuração de SDK de teste que o inclua.
O mesmo comportamento do analisador se aplica a dotnet run e dotnet build. Para obter um exemplo detalhado, consulte Encaminhar argumentos para o aplicativo na dotnet run referência.
Mínimos de execução inteira e por módulo
Para --minimum-expected-tests, o -- separador determina o escopo da opção:
- Os argumentos anteriores
--são globais. Odotnet testorquestrador os interpreta durante toda a execução. - Os argumentos depois
--são locais.dotnet testencaminha-os para cada módulo de teste, de modo que cada módulo os aplique de forma independente.
Como --minimum-expected-tests está disponível em ambos os escopos, você pode exigir um mínimo para toda a execução, para cada módulo ou ambos:
dotnet test --minimum-expected-tests 5 -- --minimum-expected-tests 2
O comando anterior requer pelo menos 5 testes em toda a execução e pelo menos 2 testes em cada módulo de teste.
Os dois escopos contam testes ignorados de forma diferente:
| Scope | Os testes ignorados contam no mínimo? |
|---|---|
| Global | Sim. O dotnet test total agregado inclui testes ignorados. |
| Por módulo | No. O MTP exclui os testes ignorados do número de testes executados. |
Começando com o SDK do .NET 11, o veredicto de teste zero para toda a execução é decidido uma vez a partir dos resultados agregados. Um módulo que não corresponde a nenhum teste, por exemplo, devido --test-modules ou a um global --filter, sai com o código 8 (ZeroTests), mas esse código é normalizado para êxito antes que os resultados sejam agregados. Como resultado, um único módulo vazio não falha em toda a execução, embora o módulo mantenha seu Exit code: 8 diagnóstico na saída para visibilidade.
O MTP 4.3.0 e versões posteriores fornecem --zero-tests-policy <allow-skipped|strict>. O valor padrão permite allow-skippedque um módulo totalmente ignorado seja bem-sucedido. O strict valor trata os testes ignorados como não executados, de modo que um módulo totalmente ignorado sai com o código 8. Passe a opção depois -- para encaminhá-la para cada módulo de teste:
dotnet test -- --zero-tests-policy strict
Quando você não define um mínimo global, o SDK do .NET 11 determina o veredicto de teste zero de execução inteira separadamente. Uma execução inteira totalmente ignorada sai com o código 8, independentemente do valor por módulo --zero-tests-policy .
Quando você especifica --minimum-expected-tests e o mínimo não é atendido, a execução falha com o código de saída 9 (MinimumExpectedTestsPolicyViolation). Esse código é diferente de 8 para que um mínimo global ou por módulo mais estrito não seja confundido com um módulo vazio. Para um mínimo por módulo retornar o código 9 quando o módulo executar zero testes, o módulo de teste deve usar o MTP 4.4.0 ou uma versão posterior.
Observação
--minimum-expected-tests 0 é inválido. Para suprimir o código de saída de testes zero, use --ignore-exit-code 8.
A partir do .NET 11 Versão Prévia 6 --tl--terminalloggere --tlp são encaminhados para o MSBuild em vez do aplicativo de teste. A partir do .NET 12 Versão Prévia 1, os formulários e -multiThreaded reconhecidos -mt também são encaminhados para o MSBuild. Para passar uma opção de aplicativo com um desses nomes, coloque-a depois --.
Passar opções de modo de execução, como --help e --list-tests diretamente para dotnet test. A partir do .NET 11 Versão Prévia 6, o SDK valida o modo de execução negociado com o aplicativo de teste. Se um perfil de inicialização ou TestingPlatformCommandLineArguments injetar uma dessas opções, a operação do SDK solicitada e a operação do aplicativo não corresponderão e a execução falhará com um diagnóstico.
Exemplos
Execute os testes no project ou solução no diretório atual:
dotnet testExecute os testes no
TestProjectproject:dotnet test --project ./TestProject/TestProject.csprojExecute os testes na solução
TestProjects:dotnet test --solution ./TestProjects/TestProjects.slnExecutar os testes usando o assembly
TestProject.dll:dotnet test --test-modules "**/bin/**/Debug/net10.0/TestProject.dll"Execute os testes usando
TestProject.dllassembly com o diretório raiz:dotnet test --test-modules "**/bin/**/Debug/net10.0/TestProject.dll" --root-directory "c:\code"Execute todos os projetos de teste referenciados por um projeto de passagem com .NET 11 Versão Prévia 7 ou posterior:
dotnet test dirs.projListar testes como JSON com .NET 11 Versão Prévia 7 ou posterior:
dotnet test --list-tests jsonExecute um aplicativo de teste MTP baseado em arquivo C# com .NET 12 Versão Prévia 1 ou posterior:
dotnet test App.Tests.csExecute os testes no diretório atual com a extensão cobertura de código Microsoft. O aplicativo de teste deve fazer referência
Microsoft.Testing.Extensions.CodeCoveragediretamente ou por meio de uma configuração do SDK de teste que o inclua:dotnet test --coverageExecute os testes e armazene os resultados em um diretório específico:
dotnet test --results-directory ./TestResultsExecute os testes com a saída de diagnóstico em um diretório específico:
dotnet test --diagnostic-output-directory ./DiagnosticsExecute os testes garantindo que pelo menos 10 testes sejam executados:
dotnet test --minimum-expected-tests 10Exigir pelo menos 5 testes em toda a execução e pelo menos 2 testes em cada módulo de teste:
dotnet test --minimum-expected-tests 5 -- --minimum-expected-tests 2Execute os testes no
TestProjectproject, fornecendo o argumento-bl(log binário) paramsbuild:dotnet test --project ./TestProject/TestProject.csproj -blExecute os testes no
TestProjectproject, definindo a propriedadeDefineConstantsdo MSBuild comoDEV:dotnet test --project ./TestProject/TestProject.csproj -p:DefineConstants="DEV"