MSTest: document testconfig.json

Author: Evangelink

docs/core/testing/unit-testing-mstest-configure.md

@@ -100,3 +100,97 @@ Each element of the file is optional because it has a default value.
 
 </RunSettings>
 ```
+
+## testconfig.json
+
+Starting with MSTest 3.7, when running your tests through MSTest runner (a.k.a Microsoft.Testing.Platform), you can use a `testconfig.json` file to configure the behavior of the test runner. The `testconfig.json` file is a JSON file that contains the configuration settings for the test runner. The file is used to configure the test runner and the test execution environment. For more information, refer to [Microsoft.Testing.Platform testconfig.json documentation](unit-testing-platform-config.md#testconfigjson).
+
+### MSTest element
+
+MSTest settings are grouped by functionality that are described in the sections below.
+
+| Entry | Default | Description |
+|-------|---------|-------------|
+| orderTestsByNameInClass | false | If you want to run tests by test names both in Test Explorers and on the command line, set this value to **true**. |
+| enableBaseClassTestMethodsFromOtherAssemblies | true | A value indicating whether to enable discovery of test methods from base classes in a different assembly from the inheriting test class. |
+| classCleanupLifecycle | EndOfAssembly | If you want the class cleanup to occur at the end of the class, set it to **EndOfClass**. |
+
+#### AssemblyResolution settings
+
+| Entry | Default | Description |
+|-------|---------|-------------|
+| paths | None | You can specify paths to extra assemblies when finding and running unit tests. For example, use these paths for dependency assemblies that aren't in the same directory as the test assembly. You can specify a path in the shape `{ "path": "...", "includeSubDirectories": "true/false" }`. |
+
+#### Deployment settings
+
+| Entry | Default | Description |
+|-------|---------|-------------|
+| deleteDeploymentDirectoryAfterTestRunIsComplete | true | To retain the deployment directory after a test run, set this value to **false**. |
+| deployTestSourceDependencies | true |A value indicating whether the test source references are to be deployed. |
+| enabled | true | If you set the value to **false**, deployment items that you specify in your test method aren't copied to the deployment directory. |
+
+#### Output settings
+
+| Entry | Default | Description |
+|-------|---------|-------------|
+| captureTrace | false | Capture text messages coming from the `Console.Write*`, `Trace.Write*`, and `Debug.Write*` APIs that will be associated to the current running test. |
+
+#### Parallelism settings
+
+| Entry | Default | Description |
+|-------|---------|-------------|
+| enabled | false | Enable test parallelization. |
+| scope | class | The scope of parallelization. You can set it to `method`. The default, `class`, corresponds to running all tests of a given class sequentially but multiple classes in parallel. |
+| workers | 0 | The number of threads/workers to be used for parallelization. The default value maps to the number of processors on the current machine. |
+
+#### Run settings
+
+| Entry | Default | Description |
+|-------|---------|-------------|
+| considerEmptyDataSourceAsInconclusive | false | When set to `true`, an empty data source is considered as inconclusive. |
+| considerFixturesAsSpecialTests | false | To display `AssemblyInitialize`, `AssemblyCleanup`, `ClassInitialize`, `ClassCleanup` as individual entries in Visual Studio and Visual Studio Code `Test Explorer` and _.trx_ log, set this value to **true**. |
+| mapInconclusiveToFailed | false | If a test completes with an inconclusive status, it's mapped to the skipped status in **Test Explorer**. If you want inconclusive tests to be shown as failed, set the value to **true**. |
+| mapNotRunnableToFailed | true | A value indicating whether a not runnable result is mapped to failed test. |
+| treatClassAndAssemblyCleanupWarningsAsErrors | false | To see your failures in class cleanups as errors, set this value to **true**. |
+| treatDiscoveryWarningsAsErrors | false | To report test discovery warnings as errors, set this value to **true**. |
+
+#### Timeout settings
+
+| Entry | Default | Description |
+|-------|---------|-------------|
+| assemblyCleanup | 0 | Specify globally the timeout to apply on each instance of assembly cleanup method. |
+| assemblyInitialize | 0 | Specify globally the timeout to apply on each instance of assembly initialize method. |
+| classCleanup | 0 | Specify globally the timeout to apply on each instance of class cleanup method. |
+| classInitialize | 0 | Specify globally the timeout to apply on each instance of class initialize method. |
+| test | 0 | Specify globally the test timeout. |
+| testCleanup | 0 | Specify globally the timeout to apply on each instance of test cleanup method. |
+| testInitialize | 0 | Specify globally the timeout to apply on each instance of test initialize method. |
+| useCooperativeCancellation | false | When set to `true`, in case of timeout, MSTest will only trigger cancellation of the `CancellationToken` but will not stop observing the method. This is more performant but relies on user to correctly flow the token through all paths. |
+
+> [!NOTE]
+> `[Timeout]` attribute specified on a method overrides the global timeout. For example, `[Timeout(1000)]` on a method marked with [AssemblyCleanup] will override the global `assemblyCleanup` timeout.
+
+### Example *testconfig.json* file
+
+The following json shows the contents of a typical *.testconfig.json* file. Copy this code and edit it to suit your needs.
+
+Each element of the file is optional because it has a default value.
+
+```json
+{
+  "mstest": {
+    "execution": {
+        "mapInconclusiveToFailed" : true,
+        "disableAppDomain": true,
+        "considerFixturesAsSpecialTests" : false,
+    },
+    "parallelism" : {
+        "enabled": true,
+        "scope": "method",
+    },
+    "output": {
+        "captureTrace": false
+    }
+  }
+}
+```