Configurar testes de unidade usando um .runsettings

O arquivo .runsettings pode ser usado para configurar como serão executados os testes de unidade. Por exemplo, ele pode ser usado para alterar a versão do .NET na qual os testes serão executados, o diretório para os resultados de teste ou os dados coletados durante uma execução de teste. Um uso comum de um arquivo .runsettings é personalizar a análise de cobertura de código.

Os arquivos de configurações de execução podem ser usados para configurar os testes executados na linha de comando, no IDE ou em um fluxo de trabalho de build usando o Azure Test Plans ou o Azure DevOps Server (conhecido anteriormente como TFS – Team Foundation Server).

Arquivos de runsettings são opcionais. Se você não precisar de nenhuma configuração especial, não será necessário ter um arquivo .runsettings.

Criar um arquivo de configurações de execução e personalizá-lo

1. Adicione um arquivo de configurações de execução à sua solução. Na Gerenciador de Soluções, no menu de atalho da solução, escolha Adicionar>Novo Item e selecione arquivo XML. Salve o arquivo com um nome como test.runsettings.

   Caso você não veja todos os modelos de item, escolha Mostrar todos os modelos e escolha o modelo de item.

   Dica

   O nome do arquivo não é importante, desde que você use a extensão .runsettings.

2. Adicione o conteúdo do Arquivo de exemplo *.runsettings e personalize-o de acordo com suas necessidades conforme descrito nas seções a seguir.

3. Especifique o arquivo *.runsettings que você deseja usando um dos seguintes métodos:

   • Visual Studio IDE
   • Linha de comando
   • Crie um fluxo de trabalho usando o Azure Test Plans ou o Azure DevOps Server (conhecido anteriormente como TFS – Team Foundation Server).

4. Execute os testes de unidade para usar as configurações de execução personalizadas.

Para desativar e ativar as configurações personalizadas no IDE, desmarque ou selecione o arquivo no menu Testar.

Especificar um arquivo de configurações de execução no IDE

Os métodos disponíveis dependem de sua versão do Visual Studio.

Visual Studio 2019 versão 16.4 e posteriores

Há três maneiras de especificar um arquivo de configurações de execução no Visual Studio 2019 versão 16.4 e posterior.

• Detecção automática das configurações de execução
• Definir manualmente as configurações de execução
• Definir uma propriedade de build

Arquivo de detecção automática das configurações de execução

Para detectar o arquivo de configurações de execução automaticamente, coloque-o na raiz da solução.

Se a detecção automática de arquivos de configurações de execução estiver habilitada, as configurações nesse arquivo serão aplicadas em todos os testes executados. Você pode ativar a detecção automática de arquivos runsettings usando dois métodos:

• Selecione Ferramentas>Opções>Testar>Detectar arquivos runsettings automaticamente

  

• Selecione Testar>Definir configurações de execução>Detectar arquivos runsettings automaticamente

  

Selecionar manualmente o arquivo de configurações de execução

No IDE, selecione Testar>Definir Configurações de Execução>Selecione runsettings Arquivo runsettings em toda a solução e, em seguida, selecione o arquivo .runsettings.

• Esse arquivo substitui o arquivo .runsettings na raiz da solução, se houver, e é aplicado a todos os testes executados.
• Essa seleção de arquivo só persiste localmente.

Definir uma propriedade de build

Adicione uma propriedade de build a um projeto por meio do arquivo de projeto ou de um arquivo Directory.Build.props. O arquivo de configurações de execução de um projeto é especificado pela propriedade RunSettingsFilePath.

• Atualmente, há suporte para as configurações de execução no nível do projeto em projetos C#, VB, C++ e F#.
• Um arquivo especificado para um projeto substitui qualquer outro arquivo de configurações de execução especificado na solução.
• Essas propriedades do MSBuild podem ser usadas para especificar o caminho para o arquivo runsettings.

Exemplo de especificação de um arquivo .runsettings para um projeto:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <RunSettingsFilePath>$(MSBuildProjectDirectory)\example.runsettings</RunSettingsFilePath>
  </PropertyGroup>
  ...
</Project>

Visual Studio 2019 versão 16.3 e anteriores

Para especificar um arquivo de configurações de execução no IDE, selecione Testar>Selecionar Arquivo de Configurações. Navegue até o arquivo .runsettings e selecione-o.

O arquivo será exibido no menu de Teste e você poderá marcá-lo ou desmarcá-lo. Quando estiver marcado, o arquivo de configurações de execução se aplicará sempre que você selecionar Analisar Cobertura de Código.

Especificar um arquivo de configurações de execução na linha de comando

Para executar testes na linha de comando, use o vstest.console.exe e especifique o arquivo de configurações usando o parâmetro /Settings.

1. Abra Prompt de Comando do Desenvolvedor para Visual Studio.

2. Insira um comando semelhante a:

   vstest.console.exe MyTestAssembly.dll /EnableCodeCoverage /Settings:CodeCoverage.runsettings
   

   ou

   vstest.console.exe --settings:test.runsettings test.dll
   

Para obter mais informações, consulte Opções de linha de comando de VSTest.Console.exe.

O arquivo *.runsettings

O arquivo *.runsettings é um arquivo XML que contém diferentes elementos de configuração dentro do elemento RunSettings. As seções a seguir detalham os diferentes elementos. Para obter um exemplo completo, confira Exemplo de arquivo *.runsettings.

<?xml version="1.0" encoding="utf-8"?>
<RunSettings>
  <!-- configuration elements -->
</RunSettings>

Cada elemento da configuração é opcional, porque tem um valor padrão.

Elemento RunConfiguration

<RunConfiguration>
    <MaxCpuCount>1</MaxCpuCount>
    <ResultsDirectory>.\TestResults</ResultsDirectory>
    <TargetPlatform>x86</TargetPlatform>
    <TargetFrameworkVersion>net6.0</TargetFrameworkVersion>
    <TestAdaptersPaths>%SystemDrive%\Temp\foo;%SystemDrive%\Temp\bar</TestAdaptersPaths>
    <TestCaseFilter>(TestCategory != Integration) &amp; (TestCategory != UnfinishedFeature)</TestCaseFilter>
    <TestSessionTimeout>10000</TestSessionTimeout>
    <TreatNoTestsAsError>true</TreatNoTestsAsError>
</RunConfiguration>

O elemento RunConfiguration pode incluir os seguintes elementos:

Elemento DataCollectors (adaptadores de dados de diagnóstico)

O elemento DataCollectors especifica as configurações de adaptadores de dados de diagnóstico. Os adaptadores de dados de diagnóstico coletam informações adicionais sobre o ambiente e o aplicativo em teste. Cada adaptador tem configurações padrão e você só precisará fornecer configurações caso não deseje usar os padrões.

<DataCollectionRunSettings>
  <DataCollectors>
    <!-- data collectors -->
  </DataCollectors>
</DataCollectionRunSettings>

Coletor de dados CodeCoverage

O coletor de dados de cobertura de código cria um log das partes do código do aplicativo que foram utilizadas no teste. Para obter informações mais detalhadas sobre como personalizar as configurações de cobertura de código, confira Personalizar a análise de cobertura de código.

<DataCollector friendlyName="Code Coverage" uri="datacollector://Microsoft/CodeCoverage/2.0" assemblyQualifiedName="Microsoft.VisualStudio.Coverage.DynamicCoverageDataCollector, Microsoft.VisualStudio.TraceCollector, Version=11.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a">
  <Configuration>
    <CodeCoverage>
      <ModulePaths>
        <Exclude>
          <ModulePath>.*CPPUnitTestFramework.*</ModulePath>
        </Exclude>
      </ModulePaths>

      <UseVerifiableInstrumentation>True</UseVerifiableInstrumentation>
      <AllowLowIntegrityProcesses>True</AllowLowIntegrityProcesses>
      <CollectFromChildProcesses>True</CollectFromChildProcesses>
      <CollectAspDotNet>False</CollectAspDotNet>
    </CodeCoverage>
  </Configuration>
</DataCollector>

Coletor de dados VideoRecorder

O coletor de dados de vídeo captura uma gravação de tela quando os testes são executados. A gravação é útil para solucionar problemas de testes de interface do usuário. O coletor de dados de vídeo está disponível no Visual Studio 2017 versão 15.5 e posterior. Para obter um exemplo de configuração desse coletor de dados, consulte o Arquivo de exemplo *.runsettings.

Para personalizar qualquer outro tipo de adaptador de dados de diagnóstico, use um arquivo de configurações do teste.

Coletor de dados de blame

Essa opção pode ajudá-lo a isolar um teste problemático que causa uma falha no host de teste. A execução do coletor cria um arquivo de saída (Sequence.xml) em TestResults, que captura a ordem de execução do teste antes da falha.

Você pode executar blame em três modos diferentes:

• Modo de arquivo de sequência: para criar um arquivo com a lista de testes até o travamento
• Modo de despejo de memória: para criar um despejo quando o testhost falha
• Modo de despejo de travamento: para criar um despejo quando o teste não é concluído antes do tempo limite especificado

A configuração XML deve ser colocada diretamente no nó <RunSettings>:

<RunSettings>
  <RunConfiguration>
  </RunConfiguration>
  <LoggerRunSettings>
    <Loggers>
      <Logger friendlyName="blame" enabled="True" />
    </Loggers>
  </LoggerRunSettings>
  <DataCollectionRunSettings>
    <DataCollectors>
      <!-- Enables blame -->
      <DataCollector friendlyName="blame" enabled="True">
        <Configuration>
          <!-- Enables crash dump, with dump type "Full" or "Mini".
          Requires ProcDump in PATH for .NET Framework. -->
          <CollectDump DumpType="Full" />
          <!-- Enables hang dump or testhost and its child processes 
          when a test hangs for more than 10 minutes. 
          Dump type "Full", "Mini" or "None" (just kill the processes). -->
          <CollectDumpOnTestSessionHang TestTimeout="10min" HangDumpType="Full" />
        </Configuration>
      </DataCollector>
    </DataCollectors>
  </DataCollectionRunSettings>
</RunSettings>

TestRunParameters

<TestRunParameters>
    <Parameter name="webAppUrl" value="http://localhost" />
    <Parameter name="docsUrl" value="https://video2.skills-academy.com" />
</TestRunParameters>

Os parâmetros de execução de teste fornecem uma maneira de definir variáveis e valores disponíveis para os testes no tempo de execução. Acesse os parâmetros usando a propriedade MSTest TestContext.Properties (ou o NUnit TestContext):

private string _appUrl;
public TestContext TestContext { get; set; }

[TestMethod] // [Test] for NUnit
public void HomePageTest()
{
    string _appUrl = TestContext.Properties["webAppUrl"];
}

Para usar parâmetros de execução de teste, adicione uma propriedade TestContext pública à classe de teste.

Elemento LoggerRunSettings

A seção LoggerRunSettings define um ou mais agentes a serem usados para execução do teste. Os agentes mais comuns são console, Arquivo de Resultados de Teste do Visual Studio (trx) e html.

<LoggerRunSettings>
    <Loggers>
      <Logger friendlyName="console" enabled="True">
        <Configuration>
            <Verbosity>quiet</Verbosity>
        </Configuration>
      </Logger>
      <Logger friendlyName="trx" enabled="True">
        <Configuration>
          <LogFileName>foo.trx</LogFileName>
        </Configuration>
      </Logger>
      <Logger friendlyName="html" enabled="True">
        <Configuration>
          <LogFileName>foo.html</LogFileName>
        </Configuration>
      </Logger>
    </Loggers>
  </LoggerRunSettings>

Elemento MSTest

Essas configurações são específicas para o adaptador de teste que executa os métodos de teste que têm o atributo TestMethodAttribute.

<MSTest>
    <MapInconclusiveToFailed>True</MapInconclusiveToFailed>
    <CaptureTraceOutput>false</CaptureTraceOutput>
    <DeleteDeploymentDirectoryAfterTestRunIsComplete>False</DeleteDeploymentDirectoryAfterTestRunIsComplete>
    <DeploymentEnabled>False</DeploymentEnabled>
    <ConsiderFixturesAsSpecialTests>False</ConsiderFixturesAsSpecialTests>
    <AssemblyResolution>
      <Directory path="D:\myfolder\bin\" includeSubDirectories="false"/>
    </AssemblyResolution>
</MSTest>

Arquivo .runsettings de exemplo

O XML a seguir mostra o conteúdo de um arquivo .runsettings típico. Copie esse código e edite-o para atender às suas necessidades.

Cada elemento do arquivo é opcional, porque tem um valor padrão.

<?xml version="1.0" encoding="utf-8"?>
<RunSettings>
  <!-- Configurations that affect the Test Framework -->
  <RunConfiguration>
    <!-- Use 0 for maximum process-level parallelization. This does not force parallelization within the test DLL (on the thread-level). You can also change it from the Test menu; choose "Run tests in parallel". Unchecked = 1 (only 1), checked = 0 (max). -->
    <MaxCpuCount>1</MaxCpuCount>
    <!-- Path relative to directory that contains .runsettings file-->
    <ResultsDirectory>.\TestResults</ResultsDirectory>

    <!-- Omit the whole tag for auto-detection. -->
    <!-- [x86] or x64, ARM, ARM64, s390x  -->
    <!-- You can also change it from the Test menu; choose "Processor Architecture for AnyCPU Projects" -->
    <TargetPlatform>x86</TargetPlatform>

    <!-- Any TargetFramework moniker or omit the whole tag for auto-detection. -->
    <!-- net48, [net40], net6.0, net5.0, netcoreapp3.1, uap10.0 etc. -->
    <TargetFrameworkVersion>net40</TargetFrameworkVersion>

    <!-- Path to Test Adapters -->
    <TestAdaptersPaths>%SystemDrive%\Temp\foo;%SystemDrive%\Temp\bar</TestAdaptersPaths>

    <!-- TestCaseFilter expression -->
    <TestCaseFilter>(TestCategory != Integration) &amp; (TestCategory != UnfinishedFeature)</TestCaseFilter>

    <!-- TestSessionTimeout was introduced in Visual Studio 2017 version 15.5 -->
    <!-- Specify timeout in milliseconds. A valid value should be greater than 0 -->
    <TestSessionTimeout>10000</TestSessionTimeout>

    <!-- true or false -->
    <!-- Value that specifies the exit code when no tests are discovered -->
    <TreatNoTestsAsError>true</TreatNoTestsAsError>
  </RunConfiguration>

  <!-- Configurations for data collectors -->
  <DataCollectionRunSettings>
    <DataCollectors>
      <DataCollector friendlyName="Code Coverage" uri="datacollector://Microsoft/CodeCoverage/2.0" assemblyQualifiedName="Microsoft.VisualStudio.Coverage.DynamicCoverageDataCollector, Microsoft.VisualStudio.TraceCollector, Version=11.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a">
        <Configuration>
          <CodeCoverage>
            <ModulePaths>
              <Exclude>
                <ModulePath>.*CPPUnitTestFramework.*</ModulePath>
              </Exclude>
            </ModulePaths>

            <!-- We recommend you do not change the following values: -->
            <UseVerifiableInstrumentation>True</UseVerifiableInstrumentation>
            <AllowLowIntegrityProcesses>True</AllowLowIntegrityProcesses>
            <CollectFromChildProcesses>True</CollectFromChildProcesses>
            <CollectAspDotNet>False</CollectAspDotNet>

          </CodeCoverage>
        </Configuration>
      </DataCollector>

      <DataCollector uri="datacollector://microsoft/VideoRecorder/1.0" assemblyQualifiedName="Microsoft.VisualStudio.TestTools.DataCollection.VideoRecorder.VideoRecorderDataCollector, Microsoft.VisualStudio.TestTools.DataCollection.VideoRecorder, Version=15.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" friendlyName="Screen and Voice Recorder">
        <!--Video data collector was introduced in Visual Studio 2017 version 15.5 -->
        <Configuration>
          <!-- Set "sendRecordedMediaForPassedTestCase" to "false" to add video attachments to failed tests only -->
          <MediaRecorder sendRecordedMediaForPassedTestCase="true"  xmlns="">           ​
            <ScreenCaptureVideo bitRate="512" frameRate="2" quality="20" />​
          </MediaRecorder>​
        </Configuration>
      </DataCollector>

      <!-- Configuration for blame data collector -->
      <DataCollector friendlyName="blame" enabled="True">
      </DataCollector>

    </DataCollectors>
  </DataCollectionRunSettings>

  <!-- Parameters used by tests at run time -->
  <TestRunParameters>
    <Parameter name="webAppUrl" value="http://localhost" />
    <Parameter name="webAppUserName" value="Admin" />
    <Parameter name="webAppPassword" value="Password" />
  </TestRunParameters>

  <!-- Configuration for loggers -->
  <LoggerRunSettings>
    <Loggers>
      <Logger friendlyName="console" enabled="True">
        <Configuration>
            <Verbosity>quiet</Verbosity>
        </Configuration>
      </Logger>
      <Logger friendlyName="trx" enabled="True">
        <Configuration>
          <LogFileName>foo.trx</LogFileName>
        </Configuration>
      </Logger>
      <Logger friendlyName="html" enabled="True">
        <Configuration>
          <LogFileName>foo.html</LogFileName>
        </Configuration>
      </Logger>
      <Logger friendlyName="blame" enabled="True" />
    </Loggers>
  </LoggerRunSettings>

  <!-- Adapter Specific sections -->

  <!-- MSTest adapter -->
  <MSTest>
    <MapInconclusiveToFailed>True</MapInconclusiveToFailed>
    <CaptureTraceOutput>false</CaptureTraceOutput>
    <DeleteDeploymentDirectoryAfterTestRunIsComplete>False</DeleteDeploymentDirectoryAfterTestRunIsComplete>
    <DeploymentEnabled>False</DeploymentEnabled>
    <AssemblyResolution>
      <Directory path="D:\myfolder\bin\" includeSubDirectories="false"/>
    </AssemblyResolution>
  </MSTest>

</RunSettings>

Especificar variáveis de ambiente no arquivo .runsettings

As variáveis de ambiente podem ser definidas no arquivo .runsettings, que pode interagir diretamente com o host de teste. É necessário especificar variáveis de ambiente no arquivo .runsettings para dar suporte a projetos não triviais que exigem a configuração de variáveis de ambiente como DOTNET_ROOT. Essas variáveis são definidas durante a geração do processo de host de teste e estão disponíveis no host.

Exemplo

O código a seguir é um arquivo .runsettings de exemplo que passa variáveis de ambiente:

<?xml version="1.0" encoding="utf-8"?>
<!-- File name extension must be .runsettings -->
<RunSettings>
  <RunConfiguration>
    <EnvironmentVariables>
      <!-- List of environment variables we want to set-->
      <DOTNET_ROOT>C:\ProgramFiles\dotnet</DOTNET_ROOT>
      <SDK_PATH>C:\Codebase\Sdk</SDK_PATH>
    </EnvironmentVariables>
  </RunConfiguration>
</RunSettings>

O nó RunConfiguration deve conter um nó EnvironmentVariables. Uma variável de ambiente pode ser especificada como um nome de elemento e seu valor.

Conteúdo relacionado

• Configurar uma execução de teste
• Personalizar a análise de cobertura de código
• Tarefa de teste do Visual Studio (Azure Test Plans)