Modernize stale docs (TFMs, code coverage, env vars, MTP context)

docs/Overview.md

@@ -70,7 +70,7 @@ TestPlatform is also known as vstest, or by the names of the tools that use it:
 
 ## How it works?
 
-TestPlatform consists of multiple processes that communicate over sockets, by sending JSON serialized messages. There are 4 processes that usually work together run tests:
+TestPlatform consists of multiple components that communicate by sending JSON serialized messages. A classic VSTest run usually involves these processes:
 
 - Client
 - Runner
@@ -83,7 +83,9 @@ The runner receives the request from the client, and starts an appropriate testh
 
 Testhost receives the request to run tests, and runs them via an appropriate test framework. The most often used .NET test frameworks are XUnit, MSTest and NUnit.
 
-Datacollector observes the testhost to collect additional information about the run.
+Datacollector observes the testhost to collect additional information about the run when data collection is enabled.
+
+Microsoft.Testing.Platform (MTP) test applications are an emerging .NET 10 path. For those sources, the application hosts itself and TestPlatform drives discovery and execution over the MTP protocol instead of launching a VSTest testhost.
 
 While the tests execute, the results are reported back to the runner, aggregated, and forwarded to the client.
 
@@ -248,7 +250,7 @@ The version is negotiated between the components at the beginning of every workf
 
 #### Request, Notification and Response Ordering
 
-The server supports processing only a single request at a time. Unless the request is [Cancel](#cancel) or [Abort](#abort) request.
+The server supports processing only a single request at a time, unless the request is a Cancel or Abort request.
 
 All notifications are sent before a response is sent.
 
@@ -293,7 +295,7 @@ The version is determined by choosing the highest common supported version. When
 
 The receiving side should remember the agreed value, and use it as the highest supported version for any downstream component. In the case above runner should send 6 to testhost, even though the runner supports versions up to 7.
 
-The request was introduced in TestPlatform version `16.0.0`. Runners before this version are not allowed. Testhosts before this version are allowed, the version of testhost is figured out by scanning the assembly, and the request is not sent to them. Version 0 is used for communication.
+The current source defines `Version0` as the lowest supported protocol version and `Version7` as the highest supported protocol version.
 
 Versions:
 

docs/configure.md

@@ -8,8 +8,8 @@ There are three different ways to configure various aspects of a test run.
 
 1. **Using command line arguments**
 Various configuration options can be provided to the `vstest.console` or `dotnet
-test` command line. For example, `--framework` can specify the runtime framework
-version, or `--platform` can specify the architecture of test run (`x86` or
+test` command line. For example, `--framework` can specify the target framework,
+or `--platform` can specify the architecture of test run (`x86` or
 `x64`).
 
 1. **Using a runsettings file**
@@ -61,6 +61,10 @@ The `runsettings` file is a xml file with following sections:
 1. Adapter Configuration
 1. Legacy Settings
 
+TestSettings (`*.testsettings`) are deprecated. Prefer `*.runsettings`; legacy settings
+are supported only for MSTest v1 and ordered-test scenarios that explicitly opt into
+legacy mode.
+
 We will cover these sections in detail later in the document. Let's discuss few
 core principles for runsettings.
 
@@ -93,8 +97,8 @@ document.
     <!-- [x86] | x64: architecture of test host -->  
     <TargetPlatform>x86</TargetPlatform>
 
-    <!-- Framework35 | [Framework40] | Framework45 -->  
-    <TargetFrameworkVersion>Framework40</TargetFrameworkVersion>
+    <!-- net462 | net8.0 | net9.0 | net10.0 (or a valid FrameworkName such as .NETFramework,Version=v4.8) -->
+    <TargetFrameworkVersion>net8.0</TargetFrameworkVersion>
 
     <!-- Path to Test Adapters -->  
     <TestAdaptersPaths>%SystemDrive%\Temp\foo;%SystemDrive%\Temp\bar</TestAdaptersPaths>
@@ -109,7 +113,7 @@ document.
     <!-- Specify timeout in milliseconds. A valid value should be >= 0. If 0, timeout will be infinity-->
     <TestSessionTimeout>10000</TestSessionTimeout>
 
-    <!-- STA | MTA  default is STA for .NET Full and MTA for .NET Core-->
+    <!-- STA | MTA  default is STA for .NET Framework and MTA for .NET -->
     <ExecutionThreadApartmentState>STA</ExecutionThreadApartmentState>
 
     <!-- 2. Hints to adapters to behave in a specific way -->
@@ -150,7 +154,7 @@ document.
   <!-- Configurations for in-proc data collectors -->  
   <InProcDataCollectionRunSettings>  
     <InProcDataCollectors>
-      <InProcDataCollector friendlyName="InProcDataCollectionExample" uri="InProcDataCollector://Vstest.Datacollectors/InProcDataCollectionExample/1.0" codebase="C:\Users\samadala\src\vstest.datacollectors\Examples\bin\Debug\net46\ExamplesDataCollector.dll" assemblyQualifiedName="Vstest.Datacollectors.Examples.InProcDataCollectionExample, ExamplesDataCollector, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" >
+      <InProcDataCollector friendlyName="InProcDataCollectionExample" uri="InProcDataCollector://Vstest.Datacollectors/InProcDataCollectionExample/1.0" codebase="C:\Users\samadala\src\vstest.datacollectors\Examples\bin\Debug\net462\ExamplesDataCollector.dll" assemblyQualifiedName="Vstest.Datacollectors.Examples.InProcDataCollectionExample, ExamplesDataCollector, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" >
       <Configuration>
           <Port>4312</Port>
         </Configuration>
@@ -209,7 +213,7 @@ _Example_
 <RunSettings>  
   <RunConfiguration>  
     <TargetPlatform>x86</TargetPlatform>  
-    <TargetFrameworkVersion>.NET Framework, Version=v4.6</TargetFrameworkVersion>  
+    <TargetFrameworkVersion>net8.0</TargetFrameworkVersion>
     <TestAdaptersPaths>%SystemDrive%\Temp\foo;%SystemDrive%\Temp\bar</TestAdaptersPaths>  
     <ResultsDirectory>.\TestResults</ResultsDirectory>  
     <SolutionDirectory>.\TestResults</SolutionDirectory>  
@@ -230,16 +234,19 @@ _Description_
 | ResultsDirectory  | string | Directory for test run reports. E.g. trx, coverage etc.                                         |
 | SolutionDirectory | string | Working directory for test invocation. Results directory can be relative to this. Used by IDEs. |
 | MaxCpuCount       | int    | Degree of parallelization, spawns `n` test hosts to run tests. Default: 1. Max: Number of cpu cores. |
-| TestSessionTimeout | int   | Testplatform will cancel the test run after it exceeded given TestSessionTimeout in milliseconds and will show the results of tests which ran till that point. **Required Version: 15.5+.** |
-| ExecutionThreadApartmentState       | string    | Apartment state of thread which calls adapter's RunTests and Cancel APIs. Possible values: (MTA, STA). default is STA for .NET Full and MTA for .NET Core.  STA supported only for .NET Full **Required Version: 15.5+.** [More details.](#execution-thread-apartment-state) |
+| TestSessionTimeout | int   | Test Platform will cancel the test run after it exceeded given TestSessionTimeout in milliseconds and will show the results of tests which ran till that point. |
+| ExecutionThreadApartmentState       | string    | Apartment state of thread which calls adapter's RunTests and Cancel APIs. Possible values: (MTA, STA). Default is STA for .NET Framework and MTA for .NET. STA is supported only for .NET Framework. [More details.](#execution-thread-apartment-state) |
 
 Examples of valid `TargetFrameworkVersion`:
 
-* .NETCoreApp, Version=v1.0
-* .NETCoreApp, Version=v1.1
-* .NETFramework, Version=v4.5
+* net462
+* net8.0
+* net9.0
+* net10.0
+* .NETFramework,Version=v4.8
+* .NETCoreApp,Version=v8.0
 
-[FrameworkName]: https://msdn.microsoft.com/en-us/library/dd414023(v=vs.110).aspx
+[FrameworkName]: https://learn.microsoft.com/dotnet/standard/frameworks
 
 2. **Adapter settings**
 These settings are a hint to adapters to behave in a particular way. These are
@@ -482,16 +489,16 @@ This section explains usage of ExecutionThreadApartmentState element in runsetti
 
 vstest.console.exe a.dll -- RunConfiguration.ExecutionThreadApartmentState=STA
 
-dotnet test -f net46 -- RunConfiguration.ExecutionThreadApartmentState=STA
+dotnet test -f net462 -- RunConfiguration.ExecutionThreadApartmentState=STA
 
 ### History
 
 In Test Platform V1 ExecutionThreadApartmentState property can be set from vstest.executionengine*.exe.config file. Default value is `STA`.
 
 ### Behavior
 
-In Test platform V2 ExecutionThreadApartmentState property default value is `MTA` for .NET Core and `STA` for .NET Full. `STA` value is only supported for .NET Framework.
-Warning should be shown on trying to set value `STA` for .NET Core and UAP10.0 frameworks tests.
+In Test Platform V2 ExecutionThreadApartmentState property default value is `MTA` for .NET and `STA` for .NET Framework. `STA` value is only supported for .NET Framework.
+Warning should be shown on trying to set value `STA` for .NET and UAP10.0 framework tests.
 
 * To support adapters which depends on thread test platform creates may need STA apartment state to run UI tests. `ExecutionThreadApartmentState` option can be used to set apartment state. Example: MSTest v1, MSTest v2 and MSCPPTest adapters.
 

docs/dotnetcoretests.md

@@ -1,17 +1,18 @@
-For dotnet core test projects, the test platform is acquired as a nuget package (Microsoft.NET.Test.Sdk) and the runtime (testhost.dll similar to testhost.exe) is also part of the nuget package. 
+For SDK-style .NET test projects, the supported path is to reference
+`Microsoft.NET.Test.Sdk` and run tests with `dotnet test`.
 
-When dotnet build runs, the above mentioned packages are restored to the users' global nuget cache in the absence of any overridden config. When vstest.console.exe runs <UnitTestProject>.runtimeconfig.dev.json is looked into to determine the folders to look for the testhost.dll (something like the below) in addition to the folder where the test dll is present (https://github.com/Microsoft/vstest/blob/c7472a479966a218fb0ac508ed799418eb4bfc00/src/Microsoft.TestPlatform.TestHostProvider/Hosting/DotnetTestHostManager.cs#L374)
+`dotnet test` builds the test project, restores NuGet packages, and runs the test
+assembly with the test platform components provided by `Microsoft.NET.Test.Sdk`.
+The VSTest testhost provider still uses the test assembly's `.deps.json` and, when
+present, `.runtimeconfig.dev.json` to locate `testhost.dll`; if it cannot resolve
+the package-provided testhost for a managed test assembly, it fails with guidance
+to add `Microsoft.NET.Test.Sdk`.
 
-{
-  "runtimeOptions": {
-    "additionalProbingPaths": [
-      "C:\\Users\\shivash\\.dotnet\\store\\|arch|\\|tfm|",
-      "C:\\Users\\shivash\\.nuget\\packages",
-      "C:\\Program Files\\dotnet\\sdk\\NuGetFallbackFolder"
-    ]
-  }
-}
+In normal SDK-style projects there is no separate VSTest-specific probing-path setup
+to document or configure. If you need to run tests from a copied directory or on a
+machine that does not have the restored NuGet packages, publish the test project and
+run from the publish output so the test assembly and its runtime dependencies are
+available together.
 
-In the case of the customer, the nuget packages aren't being restored to the paths defined in the <UnitTestProject>.runtimeconfig.dev.json resulting in the testhost.dll not being determined. The locations used for the nuget packages can be determined using the below : https://learn.microsoft.com/en-us/nuget/consume-packages/managing-the-global-packages-and-cache-folders#viewing-folder-locations
-
-To mitigate the issue and as a general recommendation for running dot net core tests with vstest task please ask the customer to publish the test project and point to the publish location for running tests. Publish ensures all needed dependencies are present for the tests to be executed alongside the test dll in case of dot net core tests.
+Current `dotnet test` usage is documented in the .NET testing guide:
+<https://learn.microsoft.com/dotnet/core/testing/>.

docs/environment-variables.md

@@ -1,6 +1,6 @@
 # VSTest Environment Variables
 
-This document lists all environment variables that are understood and handled by the Visual Studio Test Platform (VSTest). These variables can be used to configure various aspects of test execution, debugging, diagnostics, and feature behavior.
+This document lists environment variables that are currently handled by VSTest source code, plus a few historical variables that are called out as removed or obsolete. It is not an exhaustive list of every variable used by every adapter or hosting environment.
 
 ## Connection and Timeout Variables
 
@@ -31,7 +31,8 @@ This document lists all environment variables that are understood and handled by
 - **Example**: `VSTEST_DIAG_VERBOSITY=Info`
 
 ### VSTEST_LOGFOLDER
-- **Description**: Specifies the folder where test logs should be written.
+- **Status**: Removed. No current `src\` code reference was found.
+- **Previous description**: Specified the folder where test logs should be written.
 - **Example**: `VSTEST_LOGFOLDER=C:\TestLogs`
 
 ## Debug Variables
@@ -91,7 +92,7 @@ This document lists all environment variables that are understood and handled by
 - **Example**: `VSTEST_DEBUG_ATTACHVS_PATH=C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\devenv.exe`
 
 ### VSTEST_DEBUG_NOBP
-- **Description**: Disables breakpoints on executable entry points, to for more seemless debugging when using AttachVS.
+- **Description**: Disables breakpoints on executable entry points for more seamless debugging when using AttachVS.
 - **Values**: Set to "1" to disable breakpoints
 - **Example**: `VSTEST_DEBUG_NOBP=1`
 
@@ -111,9 +112,9 @@ This document lists all environment variables that are understood and handled by
 - **Values**: Set to any non-empty value to enable
 - **Example**: `VSTEST_DUMP_FORCEPROCDUMP=1`
 
-### VSTEST_DUMP_FORCENETDUMP (Removed in 18.5, selection of dumper is automatic.)
-- **Description**: Forces the use of dotnet-dump for crash dump collection.
-- **Values**: Set to any non-empty value to enable
+### VSTEST_DUMP_FORCENETDUMP
+- **Status**: Removed. No current `src\` code reference was found; dump tool selection is automatic.
+- **Previous description**: Forced the use of dotnet-dump for crash dump collection.
 - **Example**: `VSTEST_DUMP_FORCENETDUMP=1`
 
 ### VSTEST_DUMP_PROCDUMPARGUMENTS
@@ -130,14 +131,12 @@ This document lists all environment variables that are understood and handled by
 - **Description**: Disables artifact post-processing functionality.
 - **Values**: Set to any non-zero value to disable
 - **Example**: `VSTEST_DISABLE_ARTIFACTS_POSTPROCESSING=1`
-- **Added**: Version 17.2-preview, 7.0-preview
 
 ### VSTEST_DISABLE_ARTIFACTS_POSTPROCESSING_NEW_SDK_UX
 - **Description**: Disables new SDK UX for artifact post-processing, showing old output format.
 - **Values**: Set to any non-zero value to disable
 - **Example**: `VSTEST_DISABLE_ARTIFACTS_POSTPROCESSING_NEW_SDK_UX=1`
 - **Usage**: Useful when parsing console output and need to maintain compatibility
-- **Added**: Version 17.2-preview, 7.0-preview
 
 ### VSTEST_DISABLE_FASTER_JSON_SERIALIZATION
 - **Description**: Disables the faster JSON serialization mechanism and falls back to standard serialization.
@@ -215,7 +214,8 @@ This document lists all environment variables that are understood and handled by
 ## Configuration and Path Variables
 
 ### VSTEST_CONSOLE_PATH
-- **Description**: Specifies the path to the vstest.console executable.
+- **Status**: Removed. No current `src\` code reference was found.
+- **Previous description**: Specified the path to the vstest.console executable.
 - **Example**: `VSTEST_CONSOLE_PATH=C:\Tools\VSTest\vstest.console.exe`
 
 ### VSTEST_IGNORE_DOTNET_ROOT
@@ -242,14 +242,14 @@ This document lists all environment variables that are understood and handled by
 ## Windows App Host Variables
 
 ### VSTEST_WINAPPHOST_*
-- **Description**: Various environment variables related to Windows App Host configuration.
+- **Status**: Removed or internal to components no longer present in `src\`. No current `src\` code reference was found for the `VSTEST_WINAPPHOST_` prefix.
+- **Previous description**: Various environment variables related to Windows App Host configuration.
 - **Pattern**: Variables following the pattern `VSTEST_WINAPPHOST_{VARIABLE_NAME}`
-- **Usage**: Used internally for Windows App Host test execution scenarios
 
 ## Legacy/Experimental Variables
 
 ### VSTEST_EXPERIMENTAL_FORWARD_OUTPUT_FEATURE
-- **Description**: (Deprecated) Previously used to enable output forwarding feature.
+- **Description**: Obsolete. The source keeps this name only in a comment documenting that it was replaced by the standard-output capture and forwarding disable flags.
 - **Status**: Replaced by VSTEST_DISABLE_STANDARD_OUTPUT_CAPTURING and VSTEST_DISABLE_STANDARD_OUTPUT_FORWARDING
 - **Note**: This variable is no longer used as the feature is now enabled by default
 

docs/extensions/datacollector-migration.md

@@ -5,7 +5,7 @@ This document will walk you through the changes that are required to migrate you
 ## Referencing DataCollector Framework
 Previously, `DataCollector` abstract class was present in `Microsoft.VisualStudio.QualityTools.ExecutionCommon.dll` under namespace `Microsoft.VisualStudio.TestTools.Execution`.
 
-Now, `DataCollector`abstract class is present in Object Model. Add reference to [`Microsoft.TestPlatform.ObjectModel`](https://www.nuget.org/packages/Microsoft.TestPlatform.ObjectModel/15.5.0-preview-20170810-02)  (preview) nuget package. DataCollector APIs are present under namespace `Microsoft.VisualStudio.TestPlatform.ObjectModel.DataCollection`.
+Now, `DataCollector`abstract class is present in Object Model. Add reference to [`Microsoft.TestPlatform.ObjectModel`](https://www.nuget.org/packages/Microsoft.TestPlatform.ObjectModel) nuget package. DataCollector APIs are present under namespace `Microsoft.VisualStudio.TestPlatform.ObjectModel.DataCollection`.
 It is recommended to target your DataCollector to netstandard, so that it can also run cross-platform, i.e. on non-Windows operating systems.
 For more info, refer to this [guide](./datacollector.md).