Configuring xUnit.net with JSON

Configuration files can be used to configure xUnit.net on a per test-assembly basis. All platforms support configuration with a JSON file, though the steps required to get that configuration file recognized by xUnit.net vary by platform.

More supported platforms will be coming soon.

In these examples, we tell you to use the file name xunit.runner.json. You can also use <AssemblyName>.xunit.runner.json (where <AssemblyName> is the name of your unit test assembly, without the file extension like .dll or .exe). You should only need to use this longer name format if your unit tests DLLs will all be placed into the same output folder, and you need to disambiguate the various configuration files.

The assembly-specific filename takes precedence over the non-specific filename; there is no merging of values between files.

Adding the configuration file

To use JSON-based configuration, you must instruct Visual Studio to copy the JSON file into the output folder of your project.

  1. Add a new JSON file to root of your test project. Name the file xunit.runner.json. (If your version of Visual Studio does not have "JSON file" as an option for a new file, just choose to add a text file, and make sure it has the right name.)
  2. Right click on the newly added file in Solution Explorer, and choose Properties. In the Properties window, change the setting for Copy to Output Directory to Copy if newer. This ensures that the file to copied into your bin folder where the xUnit.net runners can find it.

Supported configuration items

The configuration elements are placed inside a top-level object:

{
  "enum-or-string-key": "value1",
  "boolean-key": true,
  "integer-key": 42
}

A JSON schema is published on this site, and referenced from SchemaStore; versions of Visual Studio with JSON support should be able to automatically detect the schema based on the configuration filename, and automatically provide Intellisense for you.

Key Supported Values
appDomain
[Runners v2.1+]

Set this value to determine whether app domains are used. By default, they will be used when available (the ifAvailable value). If you set this to required, it will require that app domains are available; if you set this to denied, it will not use app domains. Note that only desktop runners (and desktop unit tests) can use app domains, so this value will be ignored when used with non-desktop runners or with unit tests that are not targetting the desktop CLR.

JSON schema type: enum
Default value: ifAvailable

diagnosticMessages
[Runners v2.1+]

Set this value to true to include diagnostic information during test discovery and execution. Each runner has a unique method of presenting diagnostic messages.

JSON schema type: boolean
Default value: false

longRunningTestSeconds
[Runners v2.2+]

Set this value to enable long-running (hung) test detection. When the runner is idle waiting for tests to finished, it will report that fact once the timeout has passed. Use a value of 0 to disable the feature, or a positive integer value to enable the feature (time in seconds).

JSON schema type: integer
Default value: 0 (disabled)

maxParallelThreads
[Runners v2.1+]

Set this to override the maximum number of threads to be used when parallelizing tests within this assembly. Use a value of 0 to indicate that you would like the default behavior; use a value of -1 to indicate that you do not wish to limit the number of threads used for parallelization.

JSON schema type: integer
Default value: the number of logical processors in your PC

methodDisplay
[Runners v2.1+]

Set this to override the default display name for test cases. If you set this to method, the display name will be just the method (without the class name); if this set this value to classAndMethod, the default display name will be the fully qualified class name and method name.

JSON schema type: enum
Default value: "classAndMethod"

parallelizeAssembly
[Runners v2.1+]

Set this to true if this assembly is willing to participate in parallelization with other assemblies. Test runners can use this information to automatically enable parallelization across assemblies if all the assemblies agree to it.

JSON schema type: boolean
Default value: false

parallelizeTestCollections
[Runners v2.1+]

Set this to true if the assembly is willing to run tests inside this assembly in parallel against each other. Tests in the same test collection will be run sequentially against each other, but tests in different test collections will be run in parallel against each other. Set this to false to disable all parallelization within this test assembly.

JSON schema type: boolean
Default value: true

preEnumerateTheories
[Runners v2.1+]

Set this to true to pre-enumerate theories so that there is an individual test case for each theory data row. Set this to false to return a single test case for each theory without pre-enumerating the data ahead of time (this is how xUnit.net v1.x used to behave). This is most useful for developers running tests inside Visual Studio, who wish to have the Code Lens test runner icons on their theory methods, since Code Lens does not support multiple tests from a single method.

JSON schema type: boolean
Default value: true

shadowCopy
[Runners v2.1+]

Set this to true to use shadow copying when running tests in separate app domains; set to false to run tests without shadow copying. When running tests without app domains, this value is ignored.

JSON schema type: boolean
Default value: true

Copyright © 2017 .NET Foundation. Contributions welcomed at https://github.com/xunit/xunit.github.io.