Editja

Microsoft.Testing.Platform (MTP) configuration settings

MTP supports the use of configuration files and environment variables to configure the behavior of the test platform. This article describes the configuration settings that you can use to configure the test platform.

testconfig.json

The test platform uses a configuration file named [appname].testconfig.json to configure the behavior of the test platform. The testconfig.json file is a JSON file that contains configuration settings for the test platform.

The testconfig.json file has the following structure:

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

The platform will automatically detect and load the [appname].testconfig.json file located in the output directory of the test project (close to the executable).

When using Microsoft.Testing.Platform.MSBuild, you can simply create a testconfig.json file that will be automatically renamed to [appname].testconfig.json and moved to the output directory of the test project.

Starting with MTP 1.5, you can use the command-line argument --config-file to specify the path to the testconfig.json. This file takes precedence over the [appname].testconfig.json file.

Note

The [appname].testconfig.json file will get overwritten on subsequent builds.

Use a centralized testconfig.json

If you want a single testconfig.json shared across multiple test projects, you can place it in a central location and pass it via --config-file. When MSBuild is available (for example, dotnet test or dotnet run), you can use the TestingPlatformCommandLineArguments MSBuild property to automatically pass the argument. Adding this to a Directory.Build.props at the repository root ensures all test projects use the same configuration:

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

Configuration precedence

When the same setting can be specified in multiple ways, MTP resolves it in the following order (first match wins):

  1. Command-line arguments (for example, --results-directory)
  2. Environment variables
  3. testconfig.json settings
  4. Built-in defaults

Platform options

The platformOptions section of the testconfig.json file configures the core behavior of the test platform. The following table lists all supported platform options:

Entry Default Description
resultDirectory TestResults The directory where the test results are placed. Can be a relative path (resolved from the current working directory) or an absolute path. The --results-directory command-line option takes precedence.
exitProcessOnUnhandledException false When set to true, the test host process exits immediately on unhandled exceptions instead of allowing graceful shutdown. The TESTINGPLATFORM_EXIT_PROCESS_ON_UNHANDLED_EXCEPTION environment variable (values 1 or 0) takes precedence.

Note

Additional internal platform options exist for advanced scenarios (such as named-pipe timeouts for test host controllers). These options are intended for infrastructure use and are not covered here.

Example:

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

Extension options are CLI-only

Extension features such as crash dump, hang dump, retry, TRX reports, and code coverage are not configurable via testconfig.json. These features are configured exclusively through command-line arguments.

For a complete reference of command-line options, see MTP CLI options reference.

Test framework-specific settings

Test frameworks can define their own configuration sections in the testconfig.json file. Refer to the documentation for your test framework:

Example testconfig.json

The following example shows a testconfig.json file that configures platform options and MSTest settings:

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

Migrating from .runsettings to testconfig.json

If you're migrating from a .runsettings file, the following table maps common settings to their testconfig.json equivalents or alternatives:

.runsettings setting testconfig.json equivalent Notes
RunConfiguration/ResultsDirectory platformOptions.resultDirectory
RunConfiguration/MaxCpuCount No equivalent Process-level parallelism is controlled by dotnet test --max-parallel-test-modules or MSBuild /m option.
MSTest/* mstest.* See Configure MSTest — testconfig.json.
xUnit/* xUnit.* See xUnit.net testconfig.json.
LoggerRunSettings/Loggers CLI only Use --report-trx or similar CLI options.
DataCollectionRunSettings (blame) CLI only Use --crashdump and --hangdump CLI options. See Crash and hang dumps.
DataCollectionRunSettings (coverage) CLI only Use --coverage CLI option. See Code coverage.
TestRunParameters --test-parameter CLI Use --test-parameter key=value on the command line.

Environment variables

Environment variables can be used to supply some runtime configuration information.

Note

Environment variables take precedence over configuration settings in the testconfig.json file.

TESTINGPLATFORM_EXIT_PROCESS_ON_UNHANDLED_EXCEPTION environment variable

When set to 1, the test host process exits immediately on unhandled exceptions. When set to 0, the platform allows graceful shutdown. This setting takes precedence over the platformOptions:exitProcessOnUnhandledException configuration.

TESTINGPLATFORM_DEFAULT_HANG_TIMEOUT environment variable

Overrides the default timeout (300 seconds) used for named-pipe connections between the test host controller and test host. The value must be a TimeSpan-compatible string.

TESTINGPLATFORM_UI_LANGUAGE environment variable

Starting with MTP 1.5, this environment variable sets the language of the platform for displaying messages and logs using a locale value such as en-us. This language takes precedence over the Visual Studio and .NET SDK languages. The supported values are the same as for Visual Studio. For more information, see the section on changing the installer language in the Visual Studio installation documentation.

TESTINGPLATFORM_DIAGNOSTIC environment variable

If set to 1, enables the diagnostic logging.

TESTINGPLATFORM_DIAGNOSTIC_VERBOSITY environment variable

Defines the verbosity level when diagnostics are enabled. The available values are Trace, Debug, Information, Warning, Error, or Critical.

TESTINGPLATFORM_DIAGNOSTIC_OUTPUT_DIRECTORY environment variable

The output directory of the diagnostic logging. If not specified, the file is generated in the default TestResults directory.

TESTINGPLATFORM_DIAGNOSTIC_OUTPUT_FILEPREFIX environment variable

The prefix for the log file name. Defaults to "log_".

TESTINGPLATFORM_DIAGNOSTIC_FILELOGGER_SYNCHRONOUSWRITE environment variable

Forces the built-in file logger to synchronously write logs. Useful for scenarios where you don't want to lose any log entries (if the process crashes). This does slow down the test execution.

TESTINGPLATFORM_EXITCODE_IGNORE environment variable

A semicolon-separated list of exit codes to ignore. When an exit code is ignored, the process returns 0 instead. For example, TESTINGPLATFORM_EXITCODE_IGNORE=2;8 ignores test failures and no-tests-ran scenarios.

Note

Diagnostic-related environment variables take precedence over their corresponding --diagnostic-* command-line arguments.

See also

  • Last updated on