Skip to content

Commit 523bf7b

Browse files
Copilotnohwnd
Copilot
and
nohwnd
authored
Add documentation of environment variables (#15095)
* Initial plan for issue * Add comprehensive environment variables documentation - Document all VSTEST_* environment variables found in codebase - Organize by category (debug, timeout, diagnostics, feature flags, etc.) - Include descriptions, examples, and usage notes - Add to README and table of contents - Addresses issue #5065 Co-authored-by: nohwnd <5735905+nohwnd@users.noreply.github.com> * Apply PR review suggestions for environment variables documentation Co-authored-by: nohwnd <5735905+nohwnd@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: nohwnd <5735905+nohwnd@users.noreply.github.com>
1 parent 28b3b5a commit 523bf7b

File tree

3 files changed

+312
-0
lines changed

3 files changed

+312
-0
lines changed

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@ NOTE: When adding a new public API, always add it directly to the `PublicAPI.Shi
5252

5353
### Other
5454

55+
- [Environment Variables](./docs/environment-variables.md)
5556
- [Roadmap](./docs/releases.md)
5657
- [Troubleshooting guide](./docs/troubleshooting.md)
5758

‎docs/environment-variables.md

Lines changed: 309 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,309 @@
1+
# VSTest Environment Variables
2+
3+
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.
4+
5+
## Connection and Timeout Variables
6+
7+
### VSTEST_CONNECTION_TIMEOUT
8+
- **Description**: Sets the timeout in seconds for establishing connections between various test platform components (vstest.console, testhost, datacollector).
9+
- **Default**: 90 seconds
10+
- **Example**: `VSTEST_CONNECTION_TIMEOUT=120`
11+
- **Usage**: Useful on slow machines or when network latency causes connection timeouts.
12+
13+
### VSTEST_TESTHOST_SHUTDOWN_TIMEOUT
14+
- **Description**: Sets the timeout in milliseconds to wait for testhost to safely shut down.
15+
- **Default**: 100 milliseconds
16+
- **Example**: `VSTEST_TESTHOST_SHUTDOWN_TIMEOUT=500`
17+
- **Usage**: Allows testhost more time to clean up resources before forceful termination.
18+
19+
## Diagnostics and Logging Variables
20+
21+
### VSTEST_DIAG
22+
- **Description**: Enables diagnostic logging and specifies the path to the log file.
23+
- **Format**: Path to log directory and log file (e.g., "logs\log.txt")
24+
- **Example**: `VSTEST_DIAG=C:\temp\logs\vstest.log`
25+
- **Usage**: Equivalent to the `--diag` command line parameter.
26+
27+
### VSTEST_DIAG_VERBOSITY
28+
- **Description**: Sets the verbosity level for diagnostic logging when VSTEST_DIAG is enabled.
29+
- **Valid Values**: `Verbose`, `Info`, `Warning`, `Error`
30+
- **Default**: `Verbose`
31+
- **Example**: `VSTEST_DIAG_VERBOSITY=Info`
32+
33+
### VSTEST_LOGFOLDER
34+
- **Description**: Specifies the folder where test logs should be written.
35+
- **Example**: `VSTEST_LOGFOLDER=C:\TestLogs`
36+
37+
## Debug Variables
38+
39+
### VSTEST_HOST_DEBUG
40+
- **Description**: Enables debugging of the testhost process.
41+
- **Values**: Set to any non-empty value to enable
42+
- **Example**: `VSTEST_HOST_DEBUG=1`
43+
44+
### VSTEST_HOST_DEBUG_ATTACHVS
45+
- **Description**: Enables debugging of the testhost process and attempts to attach Visual Studio debugger. Requires AttachVS tool (that can be built in this repo) on PATH.
46+
- **Values**: Set to any non-empty value to enable
47+
- **Example**: `VSTEST_HOST_DEBUG_ATTACHVS=1`
48+
49+
### VSTEST_HOST_NATIVE_DEBUG
50+
- **Description**: Enables native debugging of the testhost process.
51+
- **Values**: Set to any non-empty value to enable
52+
- **Example**: `VSTEST_HOST_NATIVE_DEBUG=1`
53+
54+
### VSTEST_RUNNER_DEBUG
55+
- **Description**: Enables debugging of the test runner (vstest.console).
56+
- **Values**: Set to any non-empty value to enable
57+
- **Example**: `VSTEST_RUNNER_DEBUG=1`
58+
59+
### VSTEST_RUNNER_DEBUG_ATTACHVS
60+
- **Description**: Enables debugging of the test runner and attempts to attach Visual Studio debugger. Requires AttachVS tool (that can be built in this repo) on PATH.
61+
- **Values**: Set to any non-empty value to enable
62+
- **Example**: `VSTEST_RUNNER_DEBUG_ATTACHVS=1`
63+
64+
### VSTEST_RUNNER_NATIVE_DEBUG
65+
- **Description**: Enables native debugging of the test runner.
66+
- **Values**: Set to any non-empty value to enable
67+
- **Example**: `VSTEST_RUNNER_NATIVE_DEBUG=1`
68+
69+
### VSTEST_DATACOLLECTOR_DEBUG
70+
- **Description**: Enables debugging of data collector processes.
71+
- **Values**: Set to any non-empty value to enable
72+
- **Example**: `VSTEST_DATACOLLECTOR_DEBUG=1`
73+
74+
### VSTEST_DATACOLLECTOR_DEBUG_ATTACHVS
75+
- **Description**: Enables debugging of data collector processes and attempts to attach Visual Studio debugger.
76+
- **Values**: Set to any non-empty value to enable
77+
- **Example**: `VSTEST_DATACOLLECTOR_DEBUG_ATTACHVS=1`
78+
79+
### VSTEST_BLAMEDATACOLLECTOR_DEBUG
80+
- **Description**: Enables debugging of the blame data collector.
81+
- **Values**: Set to any non-empty value to enable
82+
- **Example**: `VSTEST_BLAMEDATACOLLECTOR_DEBUG=1`
83+
84+
### VSTEST_DUMPTOOL_DEBUG
85+
- **Description**: Enables debugging of dump collection tools.
86+
- **Values**: Set to any non-empty value to enable
87+
- **Example**: `VSTEST_DUMPTOOL_DEBUG=1`
88+
89+
### VSTEST_DEBUG_ATTACHVS_PATH
90+
- **Description**: Specifies the path for AttachVS tool, when not found on PATH. AttachVS tool can be built from this repo.
91+
- **Example**: `VSTEST_DEBUG_ATTACHVS_PATH=C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\devenv.exe`
92+
93+
### VSTEST_DEBUG_NOBP
94+
- **Description**: Disables breakpoints on executable entry points, to for more seemless debugging when using AttachVS.
95+
- **Values**: Set to "1" to disable breakpoints
96+
- **Example**: `VSTEST_DEBUG_NOBP=1`
97+
98+
## Crash Dump and Blame Collection Variables
99+
100+
### VSTEST_DUMP_PATH
101+
- **Description**: Overrides the default directory where crash dumps are stored. This disables automatic dump upload via attachments.
102+
- **Example**: `VSTEST_DUMP_PATH=C:\CrashDumps`
103+
104+
### VSTEST_DUMP_TEMP_PATH
105+
- **Description**: Specifies the temporary directory for dump collection operations.
106+
- **Fallback**: Falls back to AGENT_TEMPDIRECTORY, then system temp directory
107+
- **Example**: `VSTEST_DUMP_TEMP_PATH=C:\temp\dumps`
108+
109+
### VSTEST_DUMP_FORCEPROCDUMP
110+
- **Description**: Forces the use of ProcDump for crash dump collection.
111+
- **Values**: Set to any non-empty value to enable
112+
- **Example**: `VSTEST_DUMP_FORCEPROCDUMP=1`
113+
114+
### VSTEST_DUMP_FORCENETDUMP
115+
- **Description**: Forces the use of dotnet-dump for crash dump collection.
116+
- **Values**: Set to any non-empty value to enable
117+
- **Example**: `VSTEST_DUMP_FORCENETDUMP=1`
118+
119+
### VSTEST_DUMP_PROCDUMPARGUMENTS
120+
- **Description**: Specifies custom arguments for ProcDump when collecting crash dumps.
121+
- **Example**: `VSTEST_DUMP_PROCDUMPARGUMENTS=-e 1 -g -t -ma`
122+
123+
### VSTEST_DUMP_PROCDUMPADDITIONALARGUMENTS
124+
- **Description**: Specifies additional arguments to append to ProcDump command line.
125+
- **Example**: `VSTEST_DUMP_PROCDUMPADDITIONALARGUMENTS=-r`
126+
127+
## Feature Control Variables (Disable Features)
128+
129+
### VSTEST_DISABLE_ARTIFACTS_POSTPROCESSING
130+
- **Description**: Disables artifact post-processing functionality.
131+
- **Values**: Set to any non-zero value to disable
132+
- **Example**: `VSTEST_DISABLE_ARTIFACTS_POSTPROCESSING=1`
133+
- **Added**: Version 17.2-preview, 7.0-preview
134+
135+
### VSTEST_DISABLE_ARTIFACTS_POSTPROCESSING_NEW_SDK_UX
136+
- **Description**: Disables new SDK UX for artifact post-processing, showing old output format.
137+
- **Values**: Set to any non-zero value to disable
138+
- **Example**: `VSTEST_DISABLE_ARTIFACTS_POSTPROCESSING_NEW_SDK_UX=1`
139+
- **Usage**: Useful when parsing console output and need to maintain compatibility
140+
- **Added**: Version 17.2-preview, 7.0-preview
141+
142+
### VSTEST_DISABLE_FASTER_JSON_SERIALIZATION
143+
- **Description**: Disables the faster JSON serialization mechanism and falls back to standard serialization.
144+
- **Values**: Set to any non-zero value to disable
145+
- **Example**: `VSTEST_DISABLE_FASTER_JSON_SERIALIZATION=1`
146+
147+
### VSTEST_DISABLE_MULTI_TFM_RUN
148+
- **Description**: Forces vstest.console to run all sources using the same target framework (TFM) and architecture instead of allowing multiple different TFMs and architectures to run simultaneously.
149+
- **Values**: Set to any non-zero value to disable
150+
- **Example**: `VSTEST_DISABLE_MULTI_TFM_RUN=1`
151+
152+
### VSTEST_DISABLE_SERIALTESTRUN_DECORATOR
153+
- **Description**: Disables the SerialTestRun decorator.
154+
- **Values**: Set to any non-zero value to disable
155+
- **Example**: `VSTEST_DISABLE_SERIALTESTRUN_DECORATOR=1`
156+
157+
### VSTEST_DISABLE_SHARING_NETFRAMEWORK_TESTHOST
158+
- **Description**: Disables sharing of .NET Framework testhosts, returning to the behavior of sharing testhosts when they are running .NET Framework DLLs and are not disabling appdomains or running in parallel.
159+
- **Values**: Set to any non-zero value to disable
160+
- **Example**: `VSTEST_DISABLE_SHARING_NETFRAMEWORK_TESTHOST=1`
161+
162+
### VSTEST_DISABLE_STANDARD_OUTPUT_CAPTURING
163+
- **Description**: Disables capturing standard output from testhost processes.
164+
- **Values**: Set to any non-zero value to disable
165+
- **Example**: `VSTEST_DISABLE_STANDARD_OUTPUT_CAPTURING=1`
166+
167+
### VSTEST_DISABLE_STANDARD_OUTPUT_FORWARDING
168+
- **Description**: Disables forwarding standard output from testhost processes.
169+
- **Values**: Set to any non-zero value to disable
170+
- **Example**: `VSTEST_DISABLE_STANDARD_OUTPUT_FORWARDING=1`
171+
172+
### VSTEST_DISABLE_THREADPOOL_SIZE_INCREASE
173+
- **Description**: Disables setting a higher value for ThreadPool.SetMinThreads. The higher value allows testhost to connect back faster by avoiding waits for ThreadPool to start more threads.
174+
- **Values**: Set to any non-zero value to disable
175+
- **Example**: `VSTEST_DISABLE_THREADPOOL_SIZE_INCREASE=1`
176+
177+
### VSTEST_DISABLE_UTF8_CONSOLE_ENCODING
178+
- **Description**: Disables setting UTF-8 encoding in console output.
179+
- **Values**: Set to "1" to disable
180+
- **Example**: `VSTEST_DISABLE_UTF8_CONSOLE_ENCODING=1`
181+
182+
## Build and MSBuild Integration Variables
183+
184+
### VSTEST_BUILD_DEBUG
185+
- **Description**: Enables debug output for VSTest build tasks.
186+
- **Values**: Set to any non-empty value to enable
187+
- **Example**: `VSTEST_BUILD_DEBUG=1`
188+
189+
### VSTEST_BUILD_TRACE
190+
- **Description**: Enables trace output for VSTest build tasks.
191+
- **Values**: Set to any non-empty value to enable
192+
- **Example**: `VSTEST_BUILD_TRACE=1`
193+
194+
### VSTEST_MSBUILD_NOLOGO
195+
- **Description**: Suppresses the display of the copyright banner when running tests via MSBuild.
196+
- **Values**: Set to "1" to suppress logo
197+
- **Example**: `VSTEST_MSBUILD_NOLOGO=1`
198+
199+
## Telemetry Variables
200+
201+
### VSTEST_TELEMETRY_OPTEDIN
202+
- **Description**: Controls whether telemetry data is collected and sent.
203+
- **Values**: Set to "1" to opt in, any other value opts out
204+
- **Example**: `VSTEST_TELEMETRY_OPTEDIN=1`
205+
206+
### VSTEST_LOGTELEMETRY
207+
- **Description**: Enables logging of telemetry data to files.
208+
- **Values**: Set to any non-empty value to enable
209+
- **Example**: `VSTEST_LOGTELEMETRY=1`
210+
211+
### VSTEST_LOGTELEMETRY_PATH
212+
- **Description**: Specifies the directory where telemetry log files should be written.
213+
- **Example**: `VSTEST_LOGTELEMETRY_PATH=C:\TelemetryLogs`
214+
215+
## Performance and Parallelization Variables
216+
217+
### VSTEST_HOSTPRESTART_COUNT
218+
- **Description**: Sets the number of testhosts to pre-start for improved performance in parallel test execution.
219+
- **Format**: Integer value
220+
- **Example**: `VSTEST_HOSTPRESTART_COUNT=4`
221+
222+
## Configuration and Path Variables
223+
224+
### VSTEST_CONSOLE_PATH
225+
- **Description**: Specifies the path to the vstest.console executable.
226+
- **Example**: `VSTEST_CONSOLE_PATH=C:\Tools\VSTest\vstest.console.exe`
227+
228+
### VSTEST_IGNORE_DOTNET_ROOT
229+
- **Description**: When set to a non-zero value, ignores the DOTNET_ROOT environment variable during testhost selection.
230+
- **Values**: Set to any non-zero value to ignore DOTNET_ROOT
231+
- **Default**: "0" (respects DOTNET_ROOT)
232+
- **Example**: `VSTEST_IGNORE_DOTNET_ROOT=1`
233+
234+
### VSTEST_SKIP_FAKES_CONFIGURATION
235+
- **Description**: Skips Microsoft Fakes configuration during test execution.
236+
- **Values**: Set to "1" to skip
237+
- **Example**: `VSTEST_SKIP_FAKES_CONFIGURATION=1`
238+
239+
## UWP (Universal Windows Platform) Variables
240+
241+
### VSTEST_UWP_DEPLOY_LOCAL_PATH
242+
- **Description**: Overrides the local path for UWP application deployment.
243+
- **Example**: `VSTEST_UWP_DEPLOY_LOCAL_PATH=C:\UWPApps\LocalDeploy`
244+
245+
### VSTEST_UWP_DEPLOY_REMOTE_PATH
246+
- **Description**: Overrides the remote path for UWP application deployment.
247+
- **Example**: `VSTEST_UWP_DEPLOY_REMOTE_PATH=\\RemoteDevice\Deploy`
248+
249+
## Windows App Host Variables
250+
251+
### VSTEST_WINAPPHOST_*
252+
- **Description**: Various environment variables related to Windows App Host configuration.
253+
- **Pattern**: Variables following the pattern `VSTEST_WINAPPHOST_{VARIABLE_NAME}`
254+
- **Usage**: Used internally for Windows App Host test execution scenarios
255+
256+
## Legacy/Experimental Variables
257+
258+
### VSTEST_EXPERIMENTAL_FORWARD_OUTPUT_FEATURE
259+
- **Description**: (Deprecated) Previously used to enable output forwarding feature.
260+
- **Status**: Replaced by VSTEST_DISABLE_STANDARD_OUTPUT_CAPTURING and VSTEST_DISABLE_STANDARD_OUTPUT_FORWARDING
261+
- **Note**: This variable is no longer used as the feature is now enabled by default
262+
263+
### VSTEST_DISABLE_PROTOCOL_3_VERSION_DOWNGRADE
264+
- **Description**: Disables automatic downgrade to protocol version 3 for compatibility.
265+
- **Values**: Set to any non-empty value to disable downgrade
266+
- **Example**: `VSTEST_DISABLE_PROTOCOL_3_VERSION_DOWNGRADE=1`
267+
268+
## Usage Examples
269+
270+
### Debugging a Test Run
271+
```bash
272+
# Enable testhost debugging and increase connection timeout
273+
set VSTEST_HOST_DEBUG=1
274+
set VSTEST_CONNECTION_TIMEOUT=300
275+
dotnet test MyTests.dll
276+
```
277+
278+
### Collecting Diagnostics
279+
```bash
280+
# Enable detailed diagnostic logging
281+
set VSTEST_DIAG=C:\temp\vstest.log
282+
set VSTEST_DIAG_VERBOSITY=Verbose
283+
dotnet test MyTests.dll
284+
```
285+
286+
### Performance Optimization
287+
```bash
288+
# Pre-start testhosts for better parallel performance
289+
set VSTEST_HOSTPRESTART_COUNT=4
290+
dotnet test MyTests.dll --parallel
291+
```
292+
293+
### Crash Dump Collection
294+
```bash
295+
# Configure crash dump collection
296+
set VSTEST_DUMP_PATH=C:\CrashDumps
297+
set VSTEST_DUMP_FORCEPROCDUMP=1
298+
dotnet test MyTests.dll --collect:"blame;collectdump=true"
299+
```
300+
301+
## Notes
302+
303+
- Most debug variables require only being set to any non-empty value to be enabled.
304+
- Feature disable variables typically use "1" or any non-zero value to disable the feature.
305+
- Connection timeout values are in seconds unless otherwise specified.
306+
- Paths should use the appropriate path separator for your operating system.
307+
- Some variables are only effective in specific scenarios (e.g., UWP variables only apply to UWP test projects).
308+
309+
For more information about VSTest and its features, see the [VSTest documentation](https://github.com/Microsoft/vstest/tree/main/docs).

‎docs/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44
#href: quickstart.md
55
#- name: Concepts
66
#href: concepts.md
7+
- name: Environment Variables
8+
href: environment-variables.md
79
- name: Contribute
810
href: contribute.md
911
- name: Release Notes

0 commit comments

Comments
 (0)