Relatórios de teste

Cada opção de relatório requer o pacote de extensão nomeado em sua seção. Adicione o pacote diretamente ou use uma configuração ou perfil do SDK de teste que o inclua. As extensões de relatório não fazem parte do núcleo mtp, portanto, uma opção como --report-trx não é reconhecida quando o aplicativo de teste não registra sua extensão. Execute o aplicativo de teste com --help, ou execute dotnet test --help no modo MTP, para confirmar se uma opção está disponível.

Dica

Ao usar o Microsoft.Testing.Platform.MSBuild (incluído transitivamente por MSTest, NUnit e xUnit runners), essas extensões são registradas automaticamente quando você instala seus pacotes NuGet , sem necessidade de alterações de código. O registro manual especificado neste artigo só será necessário se você desabilitar o ponto de entrada gerado automaticamente definindo <GenerateTestingPlatformEntryPoint>false</GenerateTestingPlatformEntryPoint>.

Nomes dos arquivos de relatório

Cada extensão de relatório grava seu arquivo no diretório de resultados do teste, que você pode definir com a opção --results-directory . Para substituir o nome, use a opção correspondente --report-*-filename . Cada seção de relatório lista o nome padrão desse relatório.

Um nome de arquivo pode incluir um caminho relativo que permanece dentro do diretório de resultados do teste e pode usar os seguintes itens de substituição (espaços reservados):

Espaço reservado	DESCRIÇÃO
{asm}	Nome do assembly de entrada ou unknown quando não estiver disponível.
{tfm}	Monitor da estrutura de destino detectada em tempo de execução, como net9.0.
{arch}	Arquitetura de processo, como x64, x86ou arm64.
{pname}	Nome do processo.
{pid}	ID do processo.
{time}	Carimbo de data e hora de alta precisão.

Por exemplo, --report-trx-filename "{asm}_{tfm}_{arch}.trx" reproduz o nome TRX padrão.

Se um nome de arquivo TRX, HTML ou JUnit padrão ou explícito já existir para uma fonte de teste, a extensão avisará e substituirá o arquivo. A partir da versão prévia do MTP 2.4, o CTRF usa o mesmo comportamento. Para manter o histórico de relatórios, inclua {time}.

Observação

Os nomes de espaço reservado diferenciam maiúsculas de minúsculas e usam letras minúsculas. O suporte a espaços reservados para nomes de arquivos de relatório está disponível no MTP a partir da versão 2.3.0.

Consolidação de relatório

A partir do MTP 2.4.0, o MTP faz automaticamente o pós-processamento dos artefatos do relatório após a execução de uma invocação de dotnet test que executa vários módulos de teste ou depois que o suporte a novas tentativas executa várias tentativas. O recurso é experimental no MTP 2.4.0.

As extensões TRX, JUnit, CTRF e HTML agrupam artefatos compatíveis por tipo de relatório e geram um relatório consolidado no subdiretório merged do diretório de resultados de teste. A consolidação do CTRF combina os resultados dos módulos e consolida as tentativas de nova execução no resultado final do teste, com o histórico dessas tentativas. A consolidação em HTML cria um resumo consolidado e preserva os relatórios originais de cada processo.

Para extensões de relatório personalizadas, a API experimental IArtifactPostProcessor expõe modos separados TestModules e RetryAttempts de processamento. Para obter mais informações, consulte As IArtifactPostProcessor extensões.

Visual Studio relatórios de teste (TRX)

O Visual Studio arquivo de resultado de teste (ou TRX) é o formato padrão para publicar resultados de teste. Essa extensão requer o pacote NuGet Microsoft.Testing.Extensions.TrxReport .

Registro manual

var builder = await TestApplication.CreateBuilderAsync(args);
builder.AddTrxReportProvider();

Observação

Ao usar o registro manual, registre o provedor de relatório TRX por último. A implementação atual depende da ordem de registro, portanto, registrá-la após todas as outras extensões garante que ela capture todos os dados de teste.

Observação

Disponível no MTP a partir da versão 1.9.0, o relatório TRX inclui o campo de teste Description .

Observação

Disponível no MTP a partir da versão 2.3.0, os resultados do TRX são transmitidos para o disco à medida que a execução progride. Se o host de teste falhar, o arquivo TRX manterá os resultados coletados antes da falha.

A partir da versão prévia do MTP 2.4, um TRX gerado pelo MTP preserva os metadados do MSTest [WorkItem] e [GitHubWorkItem].

Opções

Opção	DESCRIÇÃO
--report-trx	Gera o relatório TRX.
--report-trx-filename	O nome do relatório TRX gerado. A partir do MTP 2.3.0, o padrão é a forma determinística {asm}_{tfm}_{arch}.trx ; antes do MTP 2.3.0, o padrão era <UserName>_<MachineName>_<yyyy-MM-dd_HH_mm_ss.fffffff>.trx. Para personalizar o nome, consulte nomes de arquivo de relatório.

O relatório é salvo dentro da pasta TestResults padrão que pode ser especificada por meio do argumento de --results-directory linha de comando.

Relatórios HTML

O relatório HTML cria um arquivo HTML interativo e autocontido para uma sessão de teste. Essa extensão requer o pacote NuGet Microsoft.Testing.Extensions.HtmlReport.

Observação

Disponível no MTP a partir da versão 2.3.0. Essa extensão é experimental e suas opções e formato de saída podem mudar em uma versão futura.

Registro manual

var builder = await TestApplication.CreateBuilderAsync(args);
builder.AddHtmlReportProvider();

Opções

Opção	DESCRIÇÃO
--report-html	Gera o relatório HTML.
--report-html-filename	O nome do relatório HTML gerado. O valor deve terminar com .html. O padrão é {asm}_{tfm}_{arch}.html. Para personalizar o nome, consulte nomes de arquivo de relatório. Requer --report-html.

Relatórios JUnit

O relatório JUnit cria um arquivo XML compatível com JUnit para uma sessão de teste. Esta extensão requer o pacote NuGet Microsoft.Testing.Extensions.JUnitReport.

Observação

Disponível no MTP a partir da versão 2.3.0. Essa extensão é experimental e suas opções e formato de saída podem mudar em uma versão futura.

A partir do MSTest.Sdk 4.3, habilite essa extensão com <EnableMicrosoftTestingExtensionsJUnitReport>true</EnableMicrosoftTestingExtensionsJUnitReport>. A extensão não faz parte dos perfis Default ou AllMicrosoft do MSTest.Sdk.

Registro manual

var builder = await TestApplication.CreateBuilderAsync(args);
builder.AddJUnitReportProvider();

Opções

Opção	DESCRIÇÃO
--report-junit	Gera o relatório XML do JUnit.
--report-junit-filename	O nome do relatório JUnit XML gerado. O valor deve terminar com .xml. O padrão é {asm}_{tfm}_{arch}.xml. Para personalizar o nome, consulte nomes de arquivo de relatório. Requer --report-junit.

Relatórios CTRF

O relatório CTRF cria um arquivo JSON que usa o Formato de Relatório de Teste Comum para uma sessão de teste. Essa extensão requer o pacote NuGet Microsoft.Testing.Extensions.CtrfReport.

Observação

Disponível no MTP a partir da versão 2.3.0. Essa extensão é experimental e suas opções e formato de saída podem mudar em uma versão futura.

Registro manual

var builder = await TestApplication.CreateBuilderAsync(args);
builder.AddCtrfReportProvider();

Opções

Opção	DESCRIÇÃO
--report-ctrf	Gera o relatório JSON CTRF.
--report-ctrf-filename	O nome do relatório JSON CTRF gerado. O valor deve terminar com .json. O padrão é <UserName>_<MachineName>_<assembly>_<tfm>_<timestamp>.ctrf.json. Para personalizar o nome, consulte nomes de arquivo de relatório. Requer --report-ctrf.

A partir da versão prévia do MTP 2.4, o CTRF preserva todos os resultados quando vários testes usam a mesma UID. Ele também inclui anexos de cada teste e de tentativas anteriores e infere os tipos MIME com base nos nomes dos arquivos.

Para testes repetidos, CTRF correlaciona tentativas somente quando a relação é inequívoca. Em seguida, ele registra tentativas anteriores em retryAttempts, define retriese marca um resultado bem-sucedido posterior como flaky: true. Os resultados ambíguos da mesma UID permanecem separados para que o relatório não associe o diagnóstico ao teste errado.

O resumo do terminal identifica testes instáveis e testes executados novamente. Os relatórios TRX e JUnit mantêm um resultado final por teste em vez de gravar todas as tentativas.

relatórios Azure DevOps

A extensão de relatório Azure DevOps integra execuções de teste MTP com Azure Pipelines. Formata erros e avisos nos logs do pipeline, adiciona anotações para testes com falha e ignorados, cria um resumo do trabalho em Markdown e pode agrupar a saída por assembly de testes. A extensão também pode identificar falhas intermitentes ou em quarentena, fazer upload de artefatos de teste e enviar resultados em fluxo contínuo para uma execução de teste do Azure DevOps.

Quando você hospeda seu código no GitHub mas executa testes em Azure Pipelines agentes, as anotações de falha podem aparecer diretamente na solicitação de pull GitHub:

Anotação de erro na visualização de arquivos de PR do GitHub

Essa extensão requer o pacote NuGet Microsoft.Testing.Extensions.AzureDevOpsReport .

Registro manual

var builder = await TestApplication.CreateBuilderAsync(args);
builder.TestHost.AddAzureDevOpsProvider();

Opções

Opção	Versão do MTP	DESCRIÇÃO
--report-azdo	1.9.0	Habilita o gerador de relatório Azure DevOps. Erros e avisos são gravados na saída em um formato que Azure DevOps entende.
--report-azdo-severity	1.9.0	Gravidade a ser usada para eventos relatados. Os valores válidos são error (padrão) e warning.
--report-azdo-groups	2.4.0	Habilita ou desabilita grupos de logs por assembly. Quando habilitada, a saída de cada assembly de teste aparece em uma seção recolhível do log de Azure Pipelines. Os valores válidos são on e off. As compilações de prévia do MTP 2.4.0 usam on por padrão; a versão estável do MTP 2.4.0 usa off por padrão. Requer --report-azdo.
--report-azdo-annotations	2.4.0	Habilita ou desabilita anotações para testes com falha e ignorados. Os valores válidos são on (padrão) e off. Requer --report-azdo.
--report-azdo-flaky-history	2.3.0	Consulta o histórico de resultados de testes do Azure DevOps dos últimos N dias (1 a 90) e anota as falhas relatadas com o contexto de instabilidade. Requer --report-azdo.
--report-azdo-demote-known-flaky	2.3.0	Rebaixa as falhas que são suficientemente instáveis na janela de histórico do Azure DevOps (o limite padrão é 25%) de erros para avisos. Requer --report-azdo e --report-azdo-flaky-history.
--report-azdo-slow-test-history	2.3.0	Consulta o histórico de resultados de teste do Azure DevOps para o número de dias especificado e reduz o limite de teste ainda em execução para testes com tempo de execução curto conhecido. Aceita exatamente um inteiro de 1 a 90. Com exemplos históricos suficientes, o limite é o menor de 60 segundos e a duração p99 histórica multiplicada pelo multiplicador configurado. Requer --report-azdo.
--report-azdo-slow-test-history-min-sample	2.3.0	Define o número mínimo de amostras históricas necessárias antes que a extensão use o histórico de um teste para ajustar seu limite de teste lento ou adicionar detalhes de histórico a linhas de saída de teste lento. Aceita exatamente um inteiro maior ou igual a 1. O padrão é 10. Requer --report-azdo-slow-test-history.
--report-azdo-slow-test-history-multiplier	2.3.0	Define o multiplicador aplicado à duração p99 histórica de um teste para calcular seu limite de teste lento. Aceita exatamente um valor de ponto flutuante de cultura invariante maior que 0 e no máximo 10.000. O padrão é 3. Requer --report-azdo-slow-test-history.
--report-azdo-quarantine-file	2.3.0	Caminho para um arquivo de texto que lista os nomes totalmente qualificados ou padrões glob dos testes em quarentena. As falhas correspondentes são relatadas como avisos. Requer --report-azdo.
--report-azdo-summary	2.3.0	Grava um resumo da tarefa em Markdown no final da execução do teste e faz o upload por meio de ##vso[task.uploadsummary]. Um argumento de caminho de arquivo opcional substitui o local padrão ({testResultsDir}/azdo-summary-{assembly}-{tfm}-{arch}.md). Requer --report-azdo.
--report-azdo-stackframe-filter	2.3.0	Adiciona padrões de expressão regular, comparados com o prefixo de tipo totalmente qualificado de cada quadro de pilha, que são ignorados quando a extensão localiza o ponto de chamada do usuário para anotação. A opção é repetível, até 16 padrões e cada padrão é compilado com um tempo limite de correspondência de 500 ms. Esses padrões somam-se aos prefixos integrados da extensão para implementação de asserções do MSTest. Requer --report-azdo.
--report-azdo-upload-artifacts	2.3.0	Envia arquivos de resultados de teste e/ou adiciona tags de build ao Azure DevOps. Os valores válidos são off (padrão), tags-onlye filesall.
--report-azdo-upload-artifact-include	2.3.0	Inclui arquivos no upload de artefatos do Azure DevOps usando padrões glob relativos ao diretório de resultados de teste. Usa **/* como padrão. Requer --report-azdo-upload-artifacts ser um valor diferente de off.
--report-azdo-upload-artifact-exclude	2.3.0	Exclui arquivos do upload de artefatos do Azure DevOps usando padrões glob relativos ao diretório de resultados de teste. Requer --report-azdo-upload-artifacts ser um valor diferente de off.
--report-azdo-upload-artifact-name	2.3.0	Substitui o nome do contêiner de artefatos do Azure DevOps. Usa TestResults_{assemblyName}_{tfm} como padrão. Requer --report-azdo-upload-artifacts ser um valor diferente de off.
--publish-azdo-test-results	2.3.0	Transmite resultados para uma execução de teste de Azure DevOps à medida que os testes são concluídos. A guia Testes do build lista a execução concluída.
--publish-azdo-run-name	2.3.0	Define um nome de execução de teste de Azure DevOps personalizado para publicação de resultado de teste ao vivo. Requer --publish-azdo-test-results.

Warning

Não habilite grupos quando vários conjuntos de testes são executados em paralelo. Azure DevOps ##[group] e ##[endgroup] comandos de formatação são sequenciais e anônimos. A saída simultânea do assembly pode intercalar, causar aninhamento de grupo incorreto e colocar linhas sob o assembly errado. Se você usar uma versão prévia do MTP 2.4.0, passe --report-azdo-groups off para desabilitar grupos. A versão estável do MTP 2.4.0 desabilita os grupos por padrão. Passe --report-azdo-groups on apenas para uma única montagem ou para a execução serializada de uma montagem.

Observação

A coluna Versão MTP lista a primeira versão do MTP que contém cada opção. A própria extensão do Azure DevOps tornou-se estável no MTP 1.9.0 com --report-azdo e --report-azdo-severity; as opções restantes foram adicionadas no MTP 2.3.0 ou 2.4.0.

A extensão detecta automaticamente que é executada em um ambiente de CI (integração contínua) verificando a variável de TF_BUILD ambiente.

Importante

As consultas de histórico do Azure DevOps exigem SYSTEM_ACCESSTOKEN, BUILD_DEFINITIONID, SYSTEM_TEAMPROJECT, SYSTEM_COLLECTIONURI e TF_BUILD=true. Se algum valor estiver ausente, o MTP continuará sem dados de histórico, ignorará as anotações de histórico e usará o limite estático de 60 segundos para linhas de teste lentas.

Publicação ao vivo com --publish-azdo-test-results requer SYSTEM_COLLECTIONURI, TF_BUILD=true, SYSTEM_TEAMPROJECT, SYSTEM_ACCESSTOKEN e BUILD_BUILDID. Se algum valor estiver ausente ou inválido, o MTP avisará e não publicará a execução do teste.

A partir do MTP 2.4.0, os resumos em Markdown do Azure DevOps agregam resultados de todos os módulos de teste em uma invocação de dotnet test. Quando você também habilita a cobertura de código, o resumo inclui contagens cobertas e totais, percentuais, resultados de limite e um indicador quando os dados de cobertura são parciais.

Na versão prévia do MTP 2.4, a publicação em tempo real carrega automaticamente anexos de arquivo para resultados de teste com falha nos resultados de teste do Azure DevOps. Os resultados malsucedidos incluem resultados com falha, erro, tempo limite e cancelados.

Quando um resultado fornece saída padrão ou erro padrão, a extensão pode anexar até 256 KiB de cada fluxo embutido. Cada anexo com suporte de arquivo tem um limite de 16 MiB.

A extensão também envia arquivos .coverage, .cobertura.xml e .opencover.xml de nível de execução como anexos de cobertura de código. Esses anexos de execução de teste e de resultado são separados de --report-azdo-upload-artifacts, que carrega arquivos selecionados como artefatos de compilação do Azure Pipelines.

Para testes repetidos, Azure DevOps publica tentativas anteriores como subresultos e anexa os artefatos de cada tentativa ao subresult que os produziu. Se a correlação de repetição segura não estiver disponível, a extensão publicará um resultado separado em vez de removê-la.

Quando a publicação em tempo real cria a execução, ela exibe a URL da execução para que você possa acompanhar os resultados antes da finalização. Ele também envia pipelineReference e a data de início quando o ambiente do pipeline os disponibiliza. A guia Testes do build não lista uma execução em andamento; ele lista a execução após a conclusão.

relatórios do GitHub Actions

O relatório do GitHub Actions emite comandos de fluxo de trabalho nativos do GitHub Actions para que as execuções de teste produzam uma experiência de primeira classe no executor: grupos de logs por assembly, anotações de testes com falha e ignorados (exibidas na guia Anotações do fluxo de trabalho e, quando a localização de origem pode ser resolvida, na diferença de Arquivos alterados da solicitação de pull), um resumo de trabalho em Markdown acrescentado ao arquivo referenciado por GITHUB_STEP_SUMMARY, além de avisos de testes lentos.

Essa extensão requer o pacote NuGet Microsoft.Testing.Extensions.GitHubActionsReport.

A extensão é ativada somente quando a execução ocorre no GitHub Actions (a variável de ambiente GITHUB_ACTIONS é true) e a opção --report-gh está definida; caso contrário, não faz nada. Quando ativo, cada recurso é habilitado por padrão e pode ser desativado individualmente com sua --report-gh-* opção.

Importante

A opção --report-gh pertence a Microsoft.Testing.Extensions.GitHubActionsReport. O pacote GitHubActionsTestLogger fornece uma opção diferente. --report-github As opções não são aliases e funcionam somente quando o projeto de teste registra o pacote que possui a opção.

Observação

A extensão está disponível a partir do MTP 2.3.0. A partir do MTP 2.4.0, seus pontos de entrada públicos não são mais experimentais.

Registro manual

var builder = await TestApplication.CreateBuilderAsync(args);
builder.AddGitHubActionsProvider();

Opções

Opção	Versão do MTP	DESCRIÇÃO
--report-gh	2.3.0	Habilita o gerador de relatório GitHub Actions para que as execuções de teste emitam comandos de fluxo de trabalho. Requer que a execução esteja em GitHub Actions.
--report-gh-groups	2.3.0	Habilita ou desabilita grupos de logs por assembly. Os valores válidos são on (padrão) e off. Requer --report-gh.
--report-gh-annotations	2.3.0	Habilita ou desabilita anotações para testes com falha e ignorados. Os valores válidos são on (padrão) e off. Requer --report-gh.
--report-gh-step-summary	2.3.0	Controla se a extensão grava um resumo em Markdown da tarefa no arquivo referenciado por GITHUB_STEP_SUMMARY. Os valores válidos são on (padrão) offe, a partir do MTP 2.4.0, on-failure. Requer --report-gh.
--report-gh-step-summary-sections	2.4.0	Seleciona o conteúdo de resumo. Os valores válidos são test-results, slow-testse coverageall (padrão). Requer --report-gh e um modo de resumo diferente de off.
--report-gh-failure-details	2.4.0	Habilita ou desabilita detalhes de falha limitados no resumo do trabalho. Usar on (padrão) ou off. Os detalhes incluem a mensagem, o tipo de exceção, o local de origem e o rastreamento da pilha, quando disponível. Requer --report-gh.
--report-gh-history	2.4.0	Lê e atualiza um instantâneo de histórico de teste local limitado no caminho do arquivo especificado. O fluxo de trabalho deve baixar o instantâneo anterior antes da execução e carregar o arquivo atualizado posteriormente. Requer --report-gh.
--report-gh-history-window	2.4.0	Define a janela do histórico retido de 1 a 90 dias. O valor padrão é 30 dias. Requer --report-gh-history.
--report-gh-slow-test-notices	2.3.0	Habilita ou desabilita avisos de teste lento. Os valores válidos são on (padrão) e off. Requer --report-gh.
--report-gh-slow-test-threshold	2.3.0	A duração em que um teste pode ser executado antes de um aviso de teste lento ser emitido. Aceita um número nu de segundos ou um valor com um sufixo de unidade, como 90s, 2mou 1.5h. O padrão é 60s. Requer --report-gh.

A partir do MTP 2.4.0, os resumos em Markdown do GitHub Actions agregam os resultados de todos os módulos de teste em uma invocação de dotnet test. Se você também habilitar a cobertura de código, selecione coverage ou all para incluir contagens de itens cobertos e totais, porcentagens, resultados dos limites e um indicador quando os dados de cobertura forem parciais.

Os detalhes da falha permanecem dentro de mensagens limitadas, pilha, contagem de falhas e orçamentos de resumo inteiro. Quando o conteúdo excede um limite, o relatório trunca ou condensa e indica essa redução no resumo.