Microsoft.Testing.Platform (MTP) configurações

O MTP dá suporte ao uso de arquivos de configuração e variáveis de ambiente para configurar o comportamento da plataforma de teste. Este artigo descreve as configurações que você pode usar para configurar a plataforma de teste.

testconfig.json

A plataforma de teste usa um arquivo de configuração chamado [appname].testconfig.json para configurar o comportamento da plataforma de teste. O arquivo testconfig.json é um arquivo JSON que contém as configurações da plataforma de teste.

O arquivo testconfig.json tem a seguinte estrutura:

{
    "platformOptions": {
        "resultDirectory": "./TestResults"
    }
}

A plataforma detectará e carregará automaticamente o arquivo [appname].testconfig.json localizado no diretório de saída do projeto de teste (próximo ao executável).

Ao usar Microsoft.Testing.Platform.MSBuild, você pode simplesmente criar um arquivo testconfig.json que será renomeado automaticamente para [appname].testconfig.json e movido para o diretório de saída do projeto de teste.

A partir do MTP 1.5, você pode usar o argumento --config-file de linha de comando para especificar o caminho para o testconfig.json. Esse arquivo tem precedência sobre o arquivo [appname].testconfig.json .

Observação

O arquivo [appname].testconfig.json será substituído em builds subsequentes.

Usar um testconfig.json centralizado

Se você quiser um único arquivo testconfig.json compartilhado entre vários projetos de teste, poderá colocá-lo em um local central e passá-lo via --config-file. Quando o MSBuild está disponível (por exemplo, dotnet test ou dotnet run), você pode usar a TestingPlatformCommandLineArguments propriedade MSBuild para passar automaticamente o argumento. Adicionar isso a um Directory.Build.props na raiz do repositório garante que todos os projetos de teste usem a mesma configuração:

<PropertyGroup>
  <TestingPlatformCommandLineArguments>
    $(TestingPlatformCommandLineArguments) --config-file $(MSBuildThisFileDirectory)testconfig.json
  </TestingPlatformCommandLineArguments>
</PropertyGroup>

Precedência de configuração

Quando a mesma configuração pode ser especificada de várias maneiras, o MTP a resolve na seguinte ordem (a primeira correspondência prevalece):

1. Argumentos de linha de comando (por exemplo, --results-directory)
2. Variáveis de ambiente
3. configurações de testconfig.json
4. Padrões internos

Opções de plataforma

A platformOptions seção do arquivo testconfig.json configura o comportamento principal da plataforma de teste. A tabela a seguir lista todas as opções de plataforma com suporte:

Entry	Default	Descrição
resultDirectory	TestResults	O diretório em que os resultados do teste são colocados. Pode ser um caminho relativo (resolvido do diretório de trabalho atual) ou um caminho absoluto. A --results-directory opção de linha de comando tem precedência.
exitProcessOnUnhandledException	false	Quando definido como true, o processo do host de teste é encerrado imediatamente quando ocorrem exceções sem tratamento, em vez de permitir um encerramento normal. A TESTINGPLATFORM_EXIT_PROCESS_ON_UNHANDLED_EXCEPTION variável de ambiente (valores 1 ou 0) tem precedência.

Observação

Existem opções internas adicionais da plataforma para cenários avançados (como tempos limite de pipes nomeados para controladores de host de teste). Essas opções se destinam ao uso da infraestrutura e não são abordadas aqui.

Exemplo:

{
  "platformOptions": {
    "resultDirectory": "../../TestResults",
    "exitProcessOnUnhandledException": false
  }
}

Variáveis de ambiente no testconfig.json

Observação

Disponível no MTP a partir da versão 2.3.0.

A environmentVariables seção define variáveis de ambiente para o processo de teste antes de começar. Use valores de cadeia de caracteres para cada variável.

{
  "environmentVariables": {
    "DOTNET_ENVIRONMENT": "Development",
    "FEATURE_FLAG": "true"
  }
}

Opções da CLI no testconfig.json

Antes do MTP 2.3.0, recursos da extensão, como crash dump, hang dump, retry, relatórios TRX e cobertura de código, não podem ser configurados por meio de testconfig.json. Esses recursos são configurados exclusivamente por meio de argumentos de linha de comando.

A partir do MTP 2.3.0, o MTP pode ler as opções da CLI de testconfig.json até IConfiguration. Esse suporte inclui opções de extensão, para que você possa usar entradas JSON para opções que você não deseja passar na linha de comando a cada execução. Os argumentos de linha de comando ainda têm precedência.

A configuração não instala nem registra uma extensão. Cada aplicativo de teste deve fazer referência ao pacote que fornece uma opção de extensão, diretamente ou por meio de uma configuração ou perfil do SDK de teste. Caso contrário, a opção permanecerá não reconhecida se você a colocou em testconfig.json ou na linha de comando.

Use o commandLineOptions objeto para opções ativas. Omita o -- inicial de cada chave. Use true para uma opção de argumento zero e use false para desabilitar uma opção. Para um argumento, use uma cadeia de caracteres ou um número. Para argumentos repetidos ou múltiplos, use uma matriz:

{ "commandLineOptions": {
  "report-trx": true,
  "report-trx-filename": "results.trx",
  "filter-uid": ["test-1", "test-2"]
} }

O MTP considera uma cadeia de caracteres ou um escalar numérico como o primeiro argumento de uma opção que aceita argumento. Para passar um argumento booliano, use uma matriz como [true] ou [false]. A matriz distingue o argumento de um valor de presença booliano.

O MTP valida entradas configuradas, como entradas de linha de comando. Opções desconhecidas, valores inválidos e valores com aridade incorreta falham na validação. Uma opção de linha de comando explícita substitui a entrada correspondente commandLineOptions .

As opções exclusivas da Bootstrap são executadas antes que o MTP carregue a configuração. Não coloque config-file, diagnostic, , diagnostic-output-directory, diagnostic-file-prefix, diagnostic-verbosity, diagnostic-synchronous-writeou enable-dynamic-extensions em commandLineOptions.

Configurações padrão da opção passiva de linha de comando

Importante

commandLineOptionDefaults está disponível na versão prévia do MTP 2.4.

Use commandLineOptionDefaults para fornecer um argumento apenas quando um recurso habilitado solicitar essa opção e não existir nenhum valor de prioridade superior. Um padrão passivo não habilita uma opção, registra uma extensão ou ativa um recurso. Omita o -- inicial de cada chave.

{ "commandLineOptionDefaults": {
  "report-trx-filename": "{asm}.trx",
  "show-test-results": ["failed", "skipped"]
} }

O MTP resolve um valor de opção usando a primeira correspondência nesta ordem de prioridade:

• Um valor de linha de comando explícito.
• Uma entrada ativa commandLineOptions .
• Uma commandLineOptionDefaults entrada no testconfig.json.
• Um padrão fornecido pelo MSBuild.

Para um padrão fornecido pelo MSBuild, adicione um TestingPlatformCommandLineOptionDefault item. O valor Include deve omitir hifens iniciais:

<TestingPlatformCommandLineOptionDefault Include="report-trx-filename"
                                         Value="{asm}.trx" />

Para obter uma referência completa das opções de linha de comando, consulte a referência de opções da CLI mtp.

Testar configurações específicas da estrutura

As estruturas de teste podem definir suas próprias seções de configuração no arquivo testconfig.json . Consulte a documentação da estrutura de teste:

• MSTest: Configurar o MSTest — testconfig.json
• xUnit.net v3: xUnit.net testconfig.json
• NUnit: consulte a documentação do NUnit para obter informações sobre o suporte mais recente ao Microsoft.Testing.Platform.
• TUnit: consulte a documentação do TUnit para obter as informações mais recentes sobre o suporte ao Microsoft.Testing.Platform.

Exemplo de testconfig.json

O exemplo a seguir mostra um arquivo testconfig.json que define as opções de plataforma e as configurações do MSTest:

{
  "platformOptions": {
    "resultDirectory": "./TestResults"
  },
  "mstest": {
    "parallelism": {
      "enabled": true,
      "workers": 4,
      "scope": "method"
    },
    "timeout": {
      "test": 30000
    },
    "execution": {
      "considerFixturesAsSpecialTests": true
    }
  }
}

Migrando de .runsettings para testconfig.json

Se você estiver migrando de um arquivo .runsettings , a tabela a seguir mapeará as configurações comuns para seus testconfig.json equivalentes ou alternativas:

Configuração .runsettings	equivalente ao testconfig.json	Observações
RunConfiguration/ResultsDirectory	platformOptions.resultDirectory
RunConfiguration/MaxCpuCount	Nenhum equivalente	O paralelismo em nível de processo é controlado por dotnet test --max-parallel-test-modules ou pela opção /m do MSBuild.
MSTest/*	mstest.*	Consulte Configurar o MSTest — testconfig.json.
xUnit/*	xUnit.*	Consulte xUnit.net testconfig.json.
LoggerRunSettings/Loggers	Opções da CLI	Use a opção da extensão de relatório instalada. Por exemplo, o --report-trx requer Microsoft.Testing.Extensions.TrxReport. A partir da versão 2.3.0 do MTP, o MTP pode ler opções de CLI do arquivo testconfig.json. Consulte os relatórios de teste.
DataCollectionRunSettings (culpa)	Opções da CLI	Use --crashdump de Microsoft.Testing.Extensions.CrashDump ou --hangdump de Microsoft.Testing.Extensions.HangDump. A partir da versão 2.3.0 do MTP, o MTP pode ler opções de CLI do arquivo testconfig.json. Consulte Despejos de falha e travamento.
DataCollectionRunSettings (cobertura)	Opções da CLI	Use --coverage de Microsoft.Testing.Extensions.CodeCoverage. A partir da versão 2.3.0 do MTP, o MTP pode ler opções de CLI do arquivo testconfig.json. Consulte a cobertura do Código.
TestRunParameters	--test-parameter Interface de Linha de Comando (CLI)	Use --test-parameter key=value na linha de comando.

Configuração do MSBuild

Importante

TestingPlatformEnvironmentVariable está disponível na versão prévia do MTP 2.4.

Para definir uma variável de ambiente no processo de teste iniciado InvokeTestingPlatform , adicione um TestingPlatformEnvironmentVariable item:

<TestingPlatformEnvironmentVariable Include="MY_OPTIONS"
                                    Value="first;second" />

Os metadados Value preservam os pontos e vírgulas em vez de separá-los em itens do MSBuild. Os valores declarados se sobrepõem ao ambiente que o processo do MSBuild herda. Sem esses itens, o processo iniciado herda o ambiente inalterado.

Variáveis de ambiente

As variáveis de ambiente podem ser usadas para fornecer algumas informações de configuração de runtime.

Observação

As variáveis de ambiente têm precedência sobre as configurações no arquivo testconfig.json .

Variável de ambiente TESTINGPLATFORM_EXIT_PROCESS_ON_UNHANDLED_EXCEPTION

Quando configurado como 1, o processo host de teste é encerrado imediatamente ao ocorrerem exceções não tratadas. Quando definido como 0, a plataforma permite o desligamento normal. Essa configuração tem precedência sobre a platformOptions:exitProcessOnUnhandledException configuração.

Variável de ambiente TESTINGPLATFORM_DEFAULT_HANG_TIMEOUT

Substitui o tempo limite padrão (300 segundos) usado para conexões de pipes nomeados entre o controlador de host de teste e o host de teste. O valor deve ser uma TimeSpancadeia de caracteres compatível.

Variável de ambiente TESTINGPLATFORM_UI_LANGUAGE

A partir do MTP 1.5, essa variável de ambiente define o idioma da plataforma para exibir mensagens e logs usando um valor de localidade, como en-us. Esse idioma tem precedência sobre as linguagens do SDK do Visual Studio e do .NET. Os valores com suporte são os mesmos do Visual Studio. Para obter mais informações, confira a seção sobre como alterar o idioma do instalador na documentação de instalação do Visual Studio.

Variável de ambiente TESTINGPLATFORM_DIAGNOSTIC

Se definido como 1, habilita o log de diagnóstico.

Variável de ambiente TESTINGPLATFORM_DIAGNOSTIC_VERBOSITY

Define o nível de verbosidade quando o diagnóstico está habilitado. Os valores disponíveis são Trace, Debug, Information, Warning, Errorou Critical.

Variável de ambiente TESTINGPLATFORM_DIAGNOSTIC_OUTPUT_DIRECTORY

O diretório de saída do log de diagnóstico. Se não for especificado, o arquivo será gerado no diretório TestResults padrão.

Variável de ambiente TESTINGPLATFORM_DIAGNOSTIC_FILE_PREFIX

O prefixo do nome do arquivo de log. Por padrão, o MTP usa <asm>_<tfm>_<arch> e acrescenta um carimbo de data/hora. O nome do arquivo resultante é <asm>_<tfm>_<arch>_<timestamp>.diag. A variável corresponde à opção --diagnostic-file-prefix de linha de comando.

Observação

Esse nome de variável de ambiente está disponível no MTP a partir da versão 2.3.0. A variável de ambiente herdada TESTINGPLATFORM_DIAGNOSTIC_OUTPUT_FILEPREFIX ainda é respeitada pela compatibilidade com versões anteriores, mas foi preterida e pode ser removida em uma versão principal futura. Quando ambas as variáveis são definidas, TESTINGPLATFORM_DIAGNOSTIC_FILE_PREFIX tem precedência.

Variável de ambiente TESTINGPLATFORM_DIAGNOSTIC_SYNCHRONOUS_WRITE

Força o logger de arquivos embutido a gravar logs de forma síncrona. Útil para cenários em que você não deseja perder nenhuma entrada de log (se o processo falhar). Isso reduz a velocidade da execução do teste. Corresponde à opção --diagnostic-synchronous-write de linha de comando.

Observação

Esse nome de variável de ambiente está disponível no MTP a partir da versão 2.3.0. A variável de ambiente herdada TESTINGPLATFORM_DIAGNOSTIC_FILELOGGER_SYNCHRONOUSWRITE ainda é respeitada pela compatibilidade com versões anteriores, mas foi preterida e pode ser removida em uma versão principal futura. Quando ambas as variáveis são definidas, TESTINGPLATFORM_DIAGNOSTIC_SYNCHRONOUS_WRITE tem precedência.

Variável de ambiente TESTINGPLATFORM_EXITCODE_IGNORE

Uma lista separada por ponto-e-vírgula de códigos de saída a serem ignorados. Quando um código de saída é ignorado, o processo retorna 0 em vez disso. Por exemplo, TESTINGPLATFORM_EXITCODE_IGNORE=2;8 ignora falhas de teste e cenários sem testes executados.

Variável de ambiente TESTINGPLATFORM_NOBANNER

Quando definido como 1 ou true, suprime o banner de inicialização, a mensagem de direitos autorais e o banner de telemetria. Equivalente à opção --no-banner de linha de comando. A DOTNET_NOLOGO variável de ambiente tem o mesmo efeito.

Variável de ambiente NO_COLOR

Quando definido como qualquer valor não vazio, suprime toda a saída de cor ANSI. O MTP respeita a convenção NO_COLOR.

Observação

Disponível no MTP a partir da versão 2.3.0.

Variável de ambiente DOTNET_NOLOGO

Quando definido como 1 ou true, suprime o banner de inicialização, a mensagem de direitos autorais e o banner de telemetria. Essa é a variável de ambiente padrão da CLI .NET e é respeitada pelo MTP. Consulte também TESTINGPLATFORM_NOBANNER.

Variável de ambiente TESTINGPLATFORM_PIPE_DIRECTORY

A partir do MTP 2.4.0, esta variável sobrescreve o diretório no qual o MTP cria arquivos de soquete de domínio Unix para comunicação por pipe nomeado. Use isso quando um sandbox ou contêiner não permite a criação de socket no diretório temporário padrão. O MTP cria e verifica o diretório e falha com um erro quando o diretório não é gravável ou o caminho do soquete resultante é muito longo.

A variável não tem efeito no Windows, no qual os pipes nomeados não usam caminhos de sistema de arquivos. Ele também não reposiciona um pipe criado por outro processo, como o SDK do .NET.

Protótipo de cancelamento de prazo

Warning

EXPERIMENTAL/PROTÓTIPO: O cancelamento de prazo é um protótipo na versão prévia do MTP 2.4. Suas variáveis e comportamento podem mudar ou ser removidos.

Defina TESTINGPLATFORM_DEADLINE como o instante completo de cancelamento definitivo fornecido pelo gerador do prazo limite. Use um valor em UTC no formato ISO 8601. Não subtraia as margens do MTP do valor.

O MTP solicita uma parada normal antes do prazo final. TESTINGPLATFORM_DEADLINE_STOP_MARGIN controla o quão cedo e padrão é de 60 segundos. Uma estrutura de teste que não dá suporte à parada normal ignora essa solicitação.

Como alternativa, TESTINGPLATFORM_DEADLINE_DUMP_MARGIN inicia uma extensão HangDump ativa antes do prazo. A margem é padrão para 30 segundos. HangDump captura a árvore de processo e, em seguida, mata o host de teste. Sem um prazo, o MTP não inicia um temporizador de prazo.

O gerador do prazo limite continua responsável pelo cancelamento definitivo no instante especificado.

Variável de ambiente TESTINGPLATFORM_WAIT_ATTACH_DEBUGGER

Quando definido como 1, o processo de teste pausa na inicialização e aguarda a conexão de um depurador antes de prosseguir. Equivalente à opção --debug de linha de comando. Não há suporte em plataformas de navegador.

Observação

Essa variável de ambiente está disponível no MTP a partir da versão 1.6.0.

Variável de ambiente TESTINGPLATFORM_LAUNCH_ATTACH_DEBUGGER

Quando definido como 1, o processo de teste chama Debugger.Launch() na inicialização, o que solicita ao sistema que inicie um depurador just-in-time e o conecte ao processo. Use esta variável para depurar problemas de inicialização (por exemplo, handshake no modo servidor) que ocorrem antes que você possa se conectar manualmente. Em plataformas não Windows, o comportamento depende do depurador JIT configurado.

Observação

Essa variável de ambiente está disponível no MTP a partir da versão 1.6.0.

Observação

As variáveis de ambiente relacionadas ao diagnóstico têm precedência sobre seus argumentos de linha de comando correspondentes --diagnostic-* .

Consulte também

• Referência de opções da CLI MTP
• Recursos do MTP
• Configurar o MSTest
• Solução de problemas do MTP