Configuring Unit Tests by using a .runsettings File

  • Article

Unit tests in Visual Studio 2012 can be configured by using a .runsettings file. For example, you can change the .NET Framework on which the tests will be run, the directory where test results are delivered, and the data collected during a test run.

Note

.runsettings and .testsettings

.runsettings is new in Visual Studio 2012. If you’re familiar with unit testing in previous versions of Visual Studio, you might know about .testsettings files. You can still use .testsettings in Visual Studio 2012, so any test configurations you wrote for previous editions will still work. But .testsettings can be used only to configure tests written for the MSTest adapter. By contrast, .runsettings can be used with any of the adapters built for the extensible unit test framework in Visual Studio 2012, such as xUnit.net and NUnit.

Tests that use .testsettings files might run more slowly than tests that use .runsettings files, or for which there is no configuration file at all.

You still need a .testsettings file for some kinds of tests:

  • Tests that are deployed on a lab environment.

  • Web performance and load tests.

  • Customizing some types of diagnostic data adapters, such as IntelliTrace and ent log.

For more information about .testsettings, see Specifying Test Settings for Visual Studio Tests.

Customizing tests with a .runsettings file

  1. Add an XML file to your Visual Studio solution and rename it so that its file extension is .runsettings.

  2. Replace the file content with the example.

    Edit it to your own needs.

  3. On the Test menu, choose Test Settings, Select Test Settings File.

You can create more than one .runsettings file in your solution, and enable or disable them at different times by using the Test Settings menu.

Enabling a run settings file

Copy this example .runsettings file

Here is a typical .runsettings file. Each element of the file is optional, because every value has a default.

<?xml version="1.0" encoding="utf-8"?>
<RunSettings>
  <!-- Configurations that affect the Test Framework -->
  <RunConfiguration>
    <!-- Path relative to solution directory -->
    <ResultsDirectory>.\TestResults</ResultsDirectory>

    <!-- [x86] | x64  
      - You can also change it from menu Test, Test Settings, Default Processor Architecture -->
    <TargetPlatform>x86</TargetPlatform>

    <!-- Framework35 | [Framework40] | Framework45 -->
    <TargetFrameworkVersion>Framework40</TargetFrameworkVersion>
  </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>
          </CodeCoverage>
        </Configuration>
      </DataCollector>
      
    </DataCollectors>
  </DataCollectionRunSettings>
  
  <!-- Adapter Specific sections -->
  
  <!-- MSTest adapter -->
  <MSTest>
    <MapInconclusiveToFailed>True</MapInconclusiveToFailed>
    <CaptureTraceOutput>false</CaptureTraceOutput>
    <DeleteDeploymentDirectoryAfterTestRunIsComplete>False</DeleteDeploymentDirectoryAfterTestRunIsComplete>
    <DeploymentEnabled>False</DeploymentEnabled>
  </MSTest>
  
  
</RunSettings>

The .runsettings file is also used to configure Code Coverage.

The remainder of this topic describes the file content.

Edit your .runsettings file

The .runsettings file has the following elements.

Test run configuration

Node

Default

Values

ResultsDirectory

The directory where test results will be placed.

TargetFrameworkVersion

Framework40

Framework35, Framework40, Framework45

This specifies which version of the unit test framework is used to discover and execute the tests. It can be different from the version of the .NET platform that you specify in the build properties of the unit test project.

TargetPlatform

x86

x86, x64

TreatTestAdapterErrorsAsWarnings

false

false, true

Diagnostic Data Adapters (Data Collectors)

The DataCollectors element specifies settings of diagnostic data adapters. Diagnostic data adapters are used to gather additional information about the environment and the application under test. Each adapter has default settings, and you only have to provide settings if you don’t want to use the defaults.

Code coverage adapter

The code coverage data collector creates a log of which parts of the application code have been exercised in the test. For more information about customizing the settings for code coverage, see Customizing Code Coverage Analysis.

Other diagnostic data adapters

The code coverage adapter is currently the only adapter that can be customized by using the run settings file.

To customize any other type of diagnostic data adapter, you must use a test settings file. For more information, see Specifying Test Settings for Visual Studio Tests.

MSTest Run Settings

These settings are specific to the test adapter that runs test methods that have the [TestMethod] attribute.

Configuration

Default

Values

ForcedLegacyMode

false

In Visual Studio 2012, the MSTest adapter has been optimized to make it faster and more scalable. Some behavior, such as the order in which tests are run, might not be exactly as it was in previous editions of Visual Studio. Set this value true to use the older test adapter.

For example, you might use this if you have an app.config file specified for a unit test.

We recommend that you consider refactoring your tests to allow you to use the newer adapter.

IgnoreTestImpact

false

The test impact feature prioritizes tests that are affected by recent changes, when run in MSTest or from Microsoft Test Manager. This setting deactivates the feature. For more information, see How to: Collect Data to Check Which Tests Should be Run After Code Changes.

SettingsFile

You can specify a test settings file to use with the MS Test adapter here. You can also specify a test settings file using the menu Test, Test Settings, Select Test Settings File.

If you specify this value, you must also set the ForcedlegacyMode to true.

KeepExecutorAliveAfterLegacyRun

false

After a test run is completed, MSTest is shut down. Any process that is launched as part of the test will also be killed at this time. If you want to keep the test executor alive, turn this configuration to true.

For example, you could use this to keep the browser running between coded UI tests.

DeploymentEnabled

true

If you set this to false, deployment items that you have specified in your test method will not be copied to the deployment directory.

CaptureTraceOutput

true

You can write to the debug trace from your Test method using Trace.WriteLine. Using this configuration, you can turn off these debug traces.

DeleteDeploymentDirectoryAfterTestRunIsComplete

true

You can retain the Deployment Directory after a test run by setting this value to false.

MapInconclusiveToFailed

false

If a test returns with an inconclusive status, it is usually mapped to Skipped status in Test Explorer. If you want Inconclusive tests to be showed as Failed, use this configuration.

InProcMode

false

If you want your tests to be run in the same process as the MS Test adapter, set this value to true. This setting provides a minor performance gain. But if a test exits with an exception, the other tests will not continue.

See Also

Concepts

Customizing Code Coverage Analysis

Other Resources

Specifying Test Settings for Visual Studio Tests