Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Este artigo aplica-se a: ✔️ .NET SDK 10 e versões posteriores
Nome
dotnet test - .NET driver de teste usado para executar testes unitários 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 funciona mais rápido do que com o VSTest. Os argumentos relacionados com testes já não são fixos, pois estão ligados às extensões registadas no(s) projecto(s) de teste. Além disso, o MTP suporta um filtro de globbing ao executar testes. Para mais informações, consulte o MTP.
Importante
As opções específicas para extensões não estão integradas no MTP. Cada aplicação de teste direcionada deve registar a extensão que oferece uma opção. Adicione diretamente o pacote NuGet da extensão, ou use uma configuração ou perfil do SDK de teste que inclua o pacote. Caso contrário, o teste falha 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 as aplicações de teste selecionadas e consulte Opções de Extensão por cenário para encontrar o pacote para uma opção.
Advertência
Quando o MTP é optado via global.json, dotnet test espera que todos os projetos de teste usem o MTP. É um erro se qualquer um dos projetos de teste usar VSTest.
Requisitos de versão
O modo MTP requer dotnet test o SDK .NET 10 e o MTP 1.7 ou posterior. As opções adicionadas após o .NET 10 têm requisitos individuais de versão do SDK nas secções seguintes. Algumas opções também requerem um pacote MTP mais recente porque o SDK coordena a execução completa enquanto cada aplicação de teste implementa a funcionalidade correspondente.
Restauração implícita
Não é necessário executá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 opção --no-restore.
O comando dotnet restore continua a ser útil em certos cenários onde a restauração explícita faz sentido, como compilações de integração contínua em Azure DevOps Services ou em sistemas de compilação que precisam de controlar explicitamente quando ocorre a restauração.
Para obter informações sobre como gerenciar feeds NuGet, consulte a documentação dotnet restore.
Opções
Observação
Pode usar apenas uma das seguintes opções de cada vez: --project, --solution ou --test-modules. Essas opções não podem ser combinadas.
Além disso, quando usa --test-modules, não pode especificar --arch, --configuration, --device, --framework, --list-devices--os, --runtime, ou --use-current-runtime. Estas opções exigem avaliação de projeto ou não são relevantes para um módulo já construído.
PROJECT_OR_TRAVERSAL_PATHEspecifica um projeto ou projeto de deslocamento a realizar. A partir do .NET 11 Preview 7,
dotnet testsuportaMicrosoft.Build.Traversalprojetos, comodirs.proj, e executa recursivamente os seus projetos de teste referenciados.A partir do .NET 12 Preview 1, o argumento pode também identificar uma aplicação de teste MTP baseada em ficheiros C#. As aplicações de teste baseadas em ficheiros não suportam
--device.--project <PROJECT_PATH>Especifica o caminho do ficheiro do project a executar (nome da pasta ou caminho completo). Se não for especificado, o padrão será 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 for especificado, o padrão será o diretório atual.
--test-modules <EXPRESSION>Filtra módulos de teste usando globos de ficheiros. Apenas os testes pertencentes a esses módulos de teste são executados. A partir do .NET 11 Preview 6, prefixe um padrão com
!para excluir módulos correspondentes. Separe múltiplos 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. A predefinição é Environment.ProcessorCount.
--config-file <CONFIG_FILE>Especifica o ficheiro de configuração a usar para execução de testes. Se for fornecido um caminho relativo, este é convertido num caminho absoluto baseado no diretório atual. Para mais informações sobre as definições do ficheiro de configuração, vejatestconfig.json.
--results-directory <RESULTS_DIRECTORY>Especifica o diretório onde os resultados dos testes são armazenados. Se o diretório não existir, é criado. Se for fornecido um caminho relativo, este é convertido num caminho absoluto baseado no diretório atual.
--results-directory-layout <flat|per-module>Especifica como uma execução multi-módulo organiza ficheiros no diretório de resultados. O padrão,
flat, escreve todos os resultados no mesmo diretório.per-moduleescreve os resultados de cada módulo em<project>/<target-framework>_<runtime-or-architecture>, o que impede que relatórios com o mesmo nome de ficheiro se sobrescribam uns aos outros.Disponível a partir de .NET 11 RC 1.
--diagnostic-output-directory <DIAGNOSTIC_OUTPUT_DIRECTORY>Especifica o diretório onde a saída de diagnóstico é armazenada. Se o diretório não existir, é criado. Se for fornecido um caminho relativo, este é convertido num caminho absoluto baseado no diretório atual.
--minimum-expected-tests <NUMBER>Especifica um número mínimo positivo de testes para toda a corrida. Se a contagem agregada de testes for inferior ao mínimo especificado, a execução falha com o código de saída 9. A contagem global inclui testes saltados. Para mais informações sobre códigos de saída, consulte códigos de saída MTP.
Como esta opção aparece antes
--de , é uma opção global (para toda a execução). Para exigir um mínimo para cada módulo de teste, passe a opção seguinte--para que seja encaminhada para todos os módulos de teste. Para mais informações, veja Mínimos de execução completa e por módulo.Observação
O mínimo global requer o SDK .NET 10 (10.0.100) ou uma versão posterior.
--maximum-failed-tests <NUMBER>Para a execução completa após atingir o número especificado de testes falhados, com erros, com tempo de expiração ou cancelados. A saída da corrida com o código 13.
Disponível a partir do .NET 11 Preview 7 e requer MTP 2.4 ou posterior.
--timeout <DURATION>Para a execução completa após a duração especificada enquanto pelo menos uma aplicação de teste está a correr. Especifique um número positivo seguido de uma unidade, como
500ms,90s,10m,2h, ou1d. Uma corrida com tempo limitado sai com código 3.Disponível a partir do .NET 11 Preview 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. Os valores da linha de comandos sobrepõem valores a partir de um perfil de lançamento.
Use o .NET SDK 10.0.110 ou posterior quando não existir perfil de lançamento ou quando especificar
--no-launch-profile; versões anteriores do .NET 10 SDK podem ignorar as variáveis nesses casos. A partir do .NET 11 Preview 7, as variáveis também fluem para alvos de build, seleção de dispositivos, implementação e run-argument conscientes da capacidade.-
-a|--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-x64máquina, especificar--arch x86define o RID comowin-x86. Se você usar essa opção, não use a-r|--runtimeopção. Disponível desde .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. Esta opção e o valor fornecido devem ser explicitamente encadeados em qualquer
dotnetcomando que dependa da saída de outrodotnetcomando, por exemplo, ao usardotnet build --no-restoreedotnet publish --no-build. Disponível desde o SDK .NET 8.Disponível para o modo MTP a partir de .NET 11.
-
-c|--configuration <CONFIGURATION>Define a configuração de compilação. O padrão para a maioria dos projetos é
Debug, mas podes sobrescrever as definições de configuração da build no teu project. -f|--framework <FRAMEWORK>O moniker da estrutura de destino (TFM) da estrutura de destino para a qual executar testes. O framework alvo também deve ser especificado no ficheiro do project.
-
--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-x64máquina, especificar--os linuxdefine o RID comolinux-x64. Se você usar essa opção, não use a-r|--runtimeopção. Disponível desde o .NET 6. -r|--runtime <RUNTIME_IDENTIFIER>O tempo de execução de destino para testar.
A forma curta
-rdisponível a partir .NET SDK 7.Observação
Executar testes para uma solução com uma propriedade global
RuntimeIdentifier(explicitamente ou via--arch,--runtime, ou--os) não é suportado. DefinaRuntimeIdentifiernum nível de project individual em vez disso.--use-current-runtime|--ucrUsa o tempo de execução atual como alvo durante a restauração e compilação.
Disponível a partir do .NET 11 Preview 6. Não podes combinar esta opção com
--test-modules.-
-v|--verbosity <LEVEL>Define o nível de verbosidade 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 é construído antes de ser executado. Também estabelece implicitamente a bandeira
--no-restore.--no-dependenciesIgnora a construção de referências de projeto para projeto.
Disponível a partir do .NET 11 Preview 6.
--no-restoreEspecifica que uma restauração implícita não é executada ao executar o comando.
--nologo|--no-logo|--no-bannerSuprime os banners de arranque .NET e MTP. As
-nologoformas e/nologoaDOTNET_NOLOGOvariável ambiente também são suportadas.Disponível em modo MTP a partir do .NET 11 Preview 7.
--no-ansiDesativa a saída de caracteres de escape ANSI para a tela.
--no-progressDesabilita o relatório de progresso para a tela.
--no-artifact-post-processingDesativa o pós-processamento de artefactos compatíveis após uma execução em vários módulos. A partir do .NET 11 RC 1 e MTP 2.4, os pós-processadores de artefactos registados podem combinar relatórios compatíveis, como resultados TRX. Se o pós-processamento falhar, o SDK preserva os artefactos originais e o código de saída do teste.
--output <VERBOSITY_LEVEL>Especifica a verbosidade da saída para os resultados dos testes. Os valores válidos são
Minimal,NormaleDetailed. A predefinição éNormal.Minimalrequer pré-visualização do MTP 2.4.--show-test-results <OUTCOME>Seleciona blocos de resultado por resultado. No MTP 2.4 pré-visualização, use
passed,failed,skipped,all, ounone. Ofailedvalor inclui também erros, tempos de espera e cancelamentos.Combine
passed, , eskippedcom vírgulas, espaços ou opções repetidas--show-test-resultsfailed. Não combinesallnemnonecom outro valor. Esta opção explícita sobrepõe-se ao--outputpreset independentemente da ordem das opções.--list-tests [text|json]Lista testes descobertos sem os executar. Omita o valor ou especifica
textpara saída legível por humanos. A partir do .NET 11 Preview 7, especifiquejsonpara um documento JSON versionado que agrupe os testes por assembly, framework de destino e arquitetura, incluindo identificadores disponíveis, localizações de fonte, métodos, parâmetros e características.--no-launch-profileNão tentes usar launchSettings.json para configurar a aplicação. Por padrão,
launchSettings.jsoné usado, que pode aplicar variáveis de ambiente e argumentos de linha de comando ao executável de teste.--no-launch-profile-argumentsNão uses argumentos especificados por
commandLineArgsno perfil de lançamento para executar a aplicação.--device <DEVICE_ID>Seleciona um dispositivo, emulador ou simulador para cada framework alvo num projeto de teste Android ou iOS. O caminho MTP também suporta projetos de teste para macOS e Mac Catalyst. Se a entrada for interativa e houver mais do que um dispositivo disponível,
dotnet testpode pedir-lhe para selecionar um.Disponível a partir do .NET 11 Preview 6. Para projetos multidirecionados, utilize .NET 11 RC 2 ou posteriores para que a descoberta de dispositivos avalie corretamente cada framework alvo. Os projetos de teste do Browser WebAssembly não são suportados por esta opção.
--list-devicesLista os dispositivos disponíveis para um projeto sem correr testes. Especifique um projeto em vez de uma solução.
Disponível a partir do .NET 11 Preview 7.
--collect-test-mape--affected-testsRecolha um mapa de testes do repositório ou execute testes afetados por uma alteração. Estas opções experimentais requerem uma extensão distribuída separadamente e a
DOTNET_CLI_ENABLE_AFFECTED_TESTS=1variável de ambiente. Não podes combinar as duas opções. Os fluxos de trabalho de teste afetado também não suportam testes de dispositivos, módulos de teste paralelos ou políticas de teste mínimo.Disponível a partir de .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>A forma
-pabreviada pode ser usada para--property. O mesmo se aplica à/property:property=valuee a sua forma abreviada é/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 o(s) aplicativo(s) de teste. Use um espaço para separar vários argumentos. Para mais informações e exemplos sobre o que passar, consulte a visão geral do MTP e as funcionalidades do MTP.
Sugestão
Para especificar argumentos extras para projetos específicos, use a propriedade
TestingPlatformCommandLineArgumentsMSBuild. Esta propriedade é especialmente útil quando a sua solução mistura frameworks de teste (por exemplo, MSTest e xUnit.net) ou quando apenas alguns projetos referenciam uma extensão específica. Para mais informações, consulte Soluções com frameworks de teste mistos ou extensões.
Observação
Para habilitar o log de rastreamento para um arquivo, use a variável de ambiente DOTNET_CLI_TEST_TRACEFILE para fornecer o caminho para o arquivo de rastreamento.
A partir do .NET 11 RC 1, dotnet test -bl utiliza uma sessão MSBuild para execuções multi-projeto, multi-alvo e dispositivos, pelo que o registo binário contém a compilação completa.
Comportamento de saída e cancelamento
A partir do .NET 11 Preview 6, a saída interativa do ANSI mostra os testes atualmente em execução e reporta a contagem de testes por montagem. O ecrã de progresso permanece desativado quando a saída é redirecionada, ANSI ou saída de progresso está desativada, ou o ambiente não é interativo.
A partir do .NET 11 Preview 6, o primeiro Ctrl+C deixa de agendar novas aplicações de teste e solicita cancelamento cooperativo. Pressione Ctrl+C novamente para terminar imediatamente os processos filhos. Uma execução abortada sai com código 3.
A saída do host de teste ao vivo requer um host MTP que suporte o protocolo 1.1 ou posterior. Os hosts mais antigos mantêm a saída capturada e repetem-na para verificar se um módulo avariado. A partir do .NET 11 Preview 7, os resumos de falhas truncam a saída padrão capturada com mais de 40 linhas para as primeiras 30 e as últimas 10 linhas; os registos de diagnóstico mantêm a saída completa.
Para execuções multi-módulo, dotnet test avalia o resultado do teste zero ao longo de toda a execução, começando com .NET 11 Preview 7. Um módulo sem testes não falha a execução se outro módulo executar testes com sucesso, a menos que uma política explícita de testes mínimos exija mais testes.
Resultados e artefactos
Quando o layout de saída dos artefactos do SDK está ativado, as versões .NET 11, RC 1 e posteriores colocam por defeito os relatórios MTP, ficheiros de cobertura e diagnósticos<ArtifactsPath>/test/<project>/<pivot>. Um ou --results-directory-layout explícito --results-directory tem prioridade.
A partir do .NET 11 RC 1 e MTP 2.4, extensões compatíveis podem processar artefactos de uma execução multi-módulo. Por exemplo, a extensão TRX pode criar um relatório fundido enquanto preserva os relatórios por módulo. Para requisitos de extensão e relatório, consulte os relatórios de teste MTP.
Encaminhar argumentos para a aplicação do teste
dotnet test encaminha qualquer token que não reconheça para a aplicação de teste. Quando uma opção reconhecida aparece entre o nome de uma opção não reconhecida e o seu valor, remover a opção reconhecida pode alterar a forma como os tokens remanescentes se ligam às opções na aplicação de teste. Para evitar esta ambiguidade, coloque os argumentos da aplicação 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 referência direta de pacote ou através de uma configuração de SDK de teste que o inclua.
O mesmo comportamento do parser aplica-se a dotnet run e dotnet build. Para um exemplo detalhado, veja Encaminhar argumentos à aplicação na dotnet run referência.
Mínimos de execução inteira e por módulo
Para --minimum-expected-tests, o -- separador determina o âmbito da opção:
- Os argumentos anteriores
--são globais. Odotnet testorquestrador interpreta-as durante toda a temporada. - As discussões que se seguem
--são locais.dotnet testencaminha-as para cada módulo de teste, para que cada módulo as aplique de forma independente.
Como --minimum-expected-tests está disponível em ambos os escopos, pode exigir um mínimo para toda a execução, para cada módulo, ou para ambos:
dotnet test --minimum-expected-tests 5 -- --minimum-expected-tests 2
O comando anterior exige pelo menos 5 testes ao longo de toda a execução e pelo menos 2 testes em cada módulo de teste.
Os dois endoscópios contam os testes saltados de forma diferente:
| Scope | Os testes saltados contam para o mínimo? |
|---|---|
| A nível mundial | Yes. O dotnet test total agregado inclui testes saltados. |
| Por módulo | Não. O MTP exclui os testes saltados do número de testes que foram realizados. |
A partir do SDK .NET 11, o veredicto de testes 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 por causa de --test-modules ou um global --filter, sai com código 8 (ZeroTests), mas esse código é normalizado para sucesso antes de os resultados serem agregados. Como resultado, um único módulo vazio não falha durante toda a execução, embora o módulo mantenha o seu Exit code: 8 diagnóstico na saída para maior vizibilidade.
MTP 4.3.0 e versões posteriores fornecem --zero-tests-policy <allow-skipped|strict>. O valor padrão, allow-skipped, permite que um módulo totalmente ignorado tenha sucesso. O strict valor trata os testes saltados como não executados, pelo que um módulo totalmente saltado sai com o código 8. Passe a opção seguinte -- para encaminhar para cada módulo de teste:
dotnet test -- --zero-tests-policy strict
Quando não defines um mínimo global, o SDK .NET 11 determina separadamente o veredicto dos testes zero em execução inteira. Uma execução inteira totalmente saltada sai com código 8 independentemente do valor por módulo --zero-tests-policy .
Quando especificas --minimum-expected-tests e o mínimo não é atingido, a execução falha com o código de saída 9 (MinimumExpectedTestsPolicyViolation). Este código é distinto do 8 para que um mínimo global ou por módulo mais rigoroso não seja confundido com um módulo vazio. Para que um mínimo por módulo devolva o código 9 quando o módulo executa zero testes, o módulo de teste deve usar 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 zero-testes, use --ignore-exit-code 8.
A partir do .NET 11 Preview 6, --tl, --terminallogger, e --tlp são encaminhados para o MSBuild em vez da aplicação de teste. A partir do .NET 12 Preview 1, os formulários reconhecidos -mt-multiThreaded e reconhecidos também são encaminhados para o MSBuild. Para passar numa opção de candidatura com um destes nomes, coloque-a depois --de .
Passe opções de modo de execução, como --help e --list-tests diretamente, para dotnet test. A partir do .NET 11 Preview 6, o SDK valida o modo de execução negociado com a aplicação de teste. Se um perfil de lançamento ou TestingPlatformCommandLineArguments injetar uma destas opções, a operação SDK solicitada e a operação da aplicação não coincidem, e a execução falha com um diagnóstico.
Examples
Execute os testes no project ou solução no diretório atual:
dotnet testExecuta os testes no
TestProjectproject:dotnet test --project ./TestProject/TestProject.csprojExecute os testes na solução
TestProjects:dotnet test --solution ./TestProjects/TestProjects.slnExecute os testes usando
TestProject.dllassembly: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 percurso com .NET 11 Preview 7 ou posterior:
dotnet test dirs.projListe os testes como JSON com .NET 11 Preview 7 ou posterior:
dotnet test --list-tests jsonExecute uma aplicação de teste MTP baseada em ficheiros C# com .NET 12 Preview 1 ou posterior:
dotnet test App.Tests.csExecuta os testes no diretório atual com a extensão Microsoft Code Coverage. A aplicação de teste deve referenciar
Microsoft.Testing.Extensions.CodeCoverage, diretamente ou através de uma configuração de SDK de teste que a inclua:dotnet test --coverageExecuta os testes e armazena os resultados num diretório específico:
dotnet test --results-directory ./TestResultsExecute os testes com saída de diagnóstico numa diretório específica:
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 ao longo de toda a duraçã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(logarítrum binário) amsbuild:dotnet test --project ./TestProject/TestProject.csproj -blExecute os testes no
TestProjectproject, definindo a propriedade MSBuildDefineConstantsparaDEV:dotnet test --project ./TestProject/TestProject.csproj -p:DefineConstants="DEV"