Add example to test doc for generating Core_Root without building tests (#44504)

diff --git a/docs/workflow/testing/coreclr/unix-test-instructions.md b/docs/workflow/testing/coreclr/unix-test-instructions.md
index aae608d..eeee613 100644 (file)
--- a/docs/workflow/testing/coreclr/unix-test-instructions.md
+++ b/docs/workflow/testing/coreclr/unix-test-instructions.md
@@ -24,6 +24,17 @@ Please note that this builds the Priority 0 tests. To build priority 1:
 ./src/tests/build.sh -priority1
 ```
 
+## Generating Core_Root
+
+The `src/tests/build.sh` script generates the Core_Root folder, which contains the test host (`corerun`), libraries, and coreclr product binaries necessary to run a test. To generate Core_Root without building the tests:
+
+```
+./src/tests/build.sh generatelayoutonly
+```
+
+The output will be at `<repo_root>/artifacts/tests/coreclr/<os>.<arch>.<configuration>/Tests/Core_Root`.
+
+
 ## Building Individual Tests
 
 During development there are many instances where building an individual test is fast and necessary. All of the necessary tools to build are under `coreclr`. It is possible to use `~/runtime/dotnet.sh msbuild` as you would normally use MSBuild with a few caveats.
@@ -33,9 +44,11 @@ During development there are many instances where building an individual test is
 ## Building an Individual Test
 
 ```sh
-./dotnet.sh msbuild src/coreclr/tests/src/path-to-proj-file /p:TargetOS=<TargetOS> /p:Configuration=<BuildType>
+./dotnet.sh msbuild src/tests/path-to-proj-file /p:TargetOS=<TargetOS> /p:Configuration=<BuildType>
 ```
 
+In addition to the test assembly, this will generate a `.sh` script next to the test assembly in the test's output folder. The test's output folder will be under `<repo_root>/artifacts/tests/coreclr/<os>.<arch>.<configuration>` at a subpath based on the test's location in source.
+
 ## Running Tests
 
 The following instructions assume that on the Unix machine:
@@ -76,6 +89,14 @@ Tests which never should be built or run are marked
 This propoerty should not be conditioned on Target properties to allow
 all tests to be built for `allTargets`.
 
+## Running Individual Tests
+
+After [building an individual test](#building-individual-tests), to run the test:
+
+1) Set the `CORE_ROOT` environment variable to the [Core_Root folder](#generating-core_root).
+
+2) Run the test using the `.sh` generated for the test.
+
 PAL tests
 ---------
 

diff --git a/docs/workflow/testing/coreclr/windows-test-instructions.md b/docs/workflow/testing/coreclr/windows-test-instructions.md
index 540c079..5b7457a 100644 (file)
--- a/docs/workflow/testing/coreclr/windows-test-instructions.md
+++ b/docs/workflow/testing/coreclr/windows-test-instructions.md
@@ -6,13 +6,13 @@ Building and running tests on Windows
 Building coreclr tests must be done using a specific script as follows:
 
 ```
-> src\tests\build.cmd
+src\tests\build.cmd
 ```
 
 ## Building Precompiled Tests
 
 ```
-> src\tests\build.cmd crossgen
+src\tests\build.cmd crossgen
 ```
 
 This will use `crossgen.exe` to precompile test executables before they are executed.
@@ -20,26 +20,42 @@ This will use `crossgen.exe` to precompile test executables before they are exec
 ## Building Specific Priority Tests
 
 ```
-> src\tests\build.cmd -priority=1
+src\tests\build.cmd -priority=1
 ```
 
 The above is an example of requesting that priority '1' and below be built. The default priority value is '0'. If '1' is specified, all tests with `CLRTestPriorty` `0` **and** `1` will be built and run.
 
+## Generating Core_Root
+
+The `src\tests\build.cmd` script generates the Core_Root folder, which contains the test host (`corerun`), libraries, and coreclr product binaries necessary to run a test. To generate Core_Root without building the tests:
+
+```
+src\tests\build.cmd generatelayoutonly
+```
+
+The output will be at `<repo_root>\artifacts\tests\coreclr\windows.<arch>.<configuration>\Tests\Core_Root`. For example, the location for x64 checked would be: `<repo_root>\artifacts\tests\coreclr\windows.x64.Checked\Tests\Core_Root`
+
 ## Examples
 
-To run a priority '0' and '1' and crossgen'd test pass:
+To build crossgen'd priority '0' and '1' tests:
 
 ```
-> src\tests\build.cmd crossgen -priority=1
+src\tests\build.cmd crossgen -priority=1
+```
+
+To generate Core_Root for x86 release without building tests:
+
+```
+src\tests\build.cmd x86 Release generatelayoutonly
 ```
 
 For additional supported parameters use the following:
 
 ```
-> src\tests\build.cmd -?
+src\tests\build.cmd -?
 ```
 
-### Building Individual Tests
+## Building Individual Tests
 
 **Note:** `build.cmd skipmanaged [Any additional flags]` needs to be run at least once if the individual test has native assets.
 
@@ -47,18 +63,20 @@ For additional supported parameters use the following:
 
 * Managed Test: Use `dotnet.cmd` from the root of the repo on the test project directly.
 
-### Running Tests
+In addition to the test assembly, this will generate a `.cmd` script next to the test assembly in the test's output folder. The test's output folder will be under `<repo_root>\artifacts\tests\coreclr\windows.<arch>.<configuration>` at a subpath based on the test's location in source.
+
+## Running Tests
 
 Will list supported parameters.
 
 ```
-> src\tests\run.cmd /?
+src\tests\run.cmd /?
 ```
 
 In order to run all of the tests using your checked build:
 
 ```
-> src\tests\run.cmd checked
+src\tests\run.cmd checked
 ```
 
 This will generate a report named `TestRun_<arch>_<flavor>.html` (e.g. `TestRun_windows_x64_Checked.html`) in the subdirectory `<repo_root>\artifacts\log`. Any tests that failed will be listed in `TestRunResults_windows_x64_Checked.err`.
@@ -74,21 +92,18 @@ There are 2 files of interest:
 - `Finalizer.output.txt` - Contains all the information logged by the test.
 - `Finalizer.error.txt` - Contains the information reported by CoreRun.exe (which executed the test) when the test process crashes.
 
-### Re-run a failed test
+To re-run a failed test, follow the instructions for [running individual tests](#running-individual-tests). The test report for the failed test will contain the test command to run - for example, `<repo_root>\artifacts\tests\coreclr\windows.x64.Checked\Exceptions\Finalization\Finalizer.cmd`.
 
-If you wish to re-run a failed test, follow the following steps:
+## Running Individual Tests
 
-1) Set an environment variable, `CORE_ROOT`, pointing to the path to product binaries that was passed to run.cmd.
-For example using a checked build the location would be: `<repo_root>\artifacts\tests\coreclr\windows.x64.Checked\Tests\Core_Root`
+After [building an individual test](#building-individual-tests), to run the test:
 
-2) Run the failed test, the command to which is also present in the test report for a failed test. It will be something like `<repo_root>\artifacts\tests\coreclr\windows.x64.Checked\Exceptions\Finalization\Finalizer.cmd`.
+1) Set the `CORE_ROOT` environment variable to the [Core_Root folder](#generating-core_root).
 
-If you wish to run the test under a debugger (e.g. [WinDbg](http://msdn.microsoft.com/library/windows/hardware/ff551063(v=vs.85).aspx)), append `-debug <debuggerFullPath>` to the test command. For example:
+2) Run the test using the `.cmd` generated for the test.
 
-```
-> artifacts\tests\coreclr\windows.x64.Checked\Exceptions\Finalization\Finalizer.cmd -debug <debuggerFullPath>
-```
+If you wish to run the test under a debugger (e.g. [WinDbg](http://msdn.microsoft.com/library/windows/hardware/ff551063(v=vs.85).aspx)), append `-debug <debuggerFullPath>` to the test command.
 
-### Modifying a test
+## Modifying a test
 
-If test changes are needed, make the change, and build the test project. This will binplace the binaries in the test binaries folder (e.g. `<repo_root>\artifacts\tests\coreclr\windows.x64.Checked\Exceptions\Finalization`). Then re-run the test following the instructions above.
+If test changes are needed, make the change, and re-build the test project. This will binplace the binaries in the test binaries folder (e.g. `<repo_root>\artifacts\tests\coreclr\windows.x64.Checked\Exceptions\Finalization`). Then re-run the test following the instructions above.
\ No newline at end of file