Dependency on procdump.exe not documented (and optional env variable PROCDUMP_PATH)

[dargilco]

I spent a lot of time trying to get crash dumps working when running vstest.console.exe, that could have been avoided by documenting the usage of procdump.exe.

The vstext.console.exe command line for the blame switch simply says:

--Blame|/Blame:[CollectDump];[CollectAlways]=[Value];[DumpType]=[Value]
Runs the test in blame mode. This option is helpful in isolating the problematic test causing test host crash.
It creates an output file in the current directory as "Sequence.xml",
that captures the order of execution of test before the crash.
You may optionally choose to collect process dump for the test host.
When you choose to collect dump, by default, a mini dump will be collected on a crash.
You may also choose to override this default behaviour by some optional parameters:
CollectAlways - To collect dump on exit even if there is no crash (true/false)
DumpType - To specify dump type (mini/full).
Example: /Blame
/Blame:CollectDump
/Blame:CollectDump;CollectAlways=true;DumpType=full

Why does it not also say that you need to download procdump.exe and have its path defined by PATH or PROCDUMP_PATH env variables? Only after searching user forums and following links around I got back to this page that mention procdump: https://github.com/microsoft/vstest-docs/blob/b9f8340f850b9e03a3fab6537cc47fade213ac42/RFCs/0028-BlameCollector-Hang-Detection.md.

Please consider updating the console help to mention procdump.exe.

Thanks,

Darren

AB#1327039

[nohwnd]

You are right. The help on dotnet test is much better:

--blame Runs the tests in blame mode. This option is helpful in isolating problematic tests that cause the test host to crash or hang.
When a crash is detected, it creates an sequence file in TestResults/guid/guid_Sequence.xml that captures the order of tests that were run before the crash.
Based on the additional settings, hang dump or crash dump can also be collected.
Example:
Timeout the test run when test takes more than the default timeout of 1 hour, and collect crash dump when the test host exits unexpectedly.
(Crash dumps require additional setup, see below.)
dotnet test --blame-hang --blame-crash
Example:
Timeout the test run when a test takes more than 20 minutes and collect hang dump.
dotnet test --blame-hang-timeout 20min
--blame-crash Runs the tests in blame mode and enables collecting crash dump when testhost exits unexpectedly.
This option is currently only supported on Windows, and requires procdump.exe and procdump64.exe to be available in PATH.
Or PROCDUMP_PATH environment variable to be set, and point to a directory that contains procdump.exe and procdump64.exe.
The tools can be downloaded here: https://docs.microsoft.com/sysinternals/downloads/procdump
Implies --blame.
--blame-crash-dump-type <DUMP_TYPE> The type of crash dump to be collected. Implies --blame-crash.
--blame-crash-collect-always Enables collecting crash dump on expected as well as unexpected testhost exit.
--blame-hang Run the tests in blame mode and enables collecting hang dump when test exceeds the given timeout. Implies --blame-hang.
--blame-hang-dump-type <DUMP_TYPE> The type of crash dump to be collected. When None, is used then test host is terminated on timeout, but no dump is collected. Implies --blame-hang.
--blame-hang-timeout Per-test timeout, after which hang dump is triggered and the testhost process is terminated.
The timeout value is specified in the following format: 1.5h / 90m / 5400s / 5400000ms. When no unit is used (e.g. 5400000), the value is assumed to be in milliseconds.
When used together with data driven tests, the timeout behavior depends on the test adapter used. For xUnit and NUnit the timeout is renewed after every test case,
For MSTest, the timeout is used for all testcases.
This option is currently supported only on Windows together with netcoreapp2.1 and newer. And on Linux with netcoreapp3.1 and newer. OSX and UWP are not supported.

[KirillOsenkov]

Surprised the possible values for --blame-crash-dump-type <DUMP_TYPE> are not documented anywhere.

[KirillOsenkov]

That help is still completely inadequate.