Introduce a BuildAllTestsAsStandalone environment variable to suppo…

…rt some local dev scenarios. (dotnet#100709)

docs/workflow/testing/coreclr/testing.md

@@ -7,11 +7,13 @@
   * [Building an Individual Test](#building-an-individual-test)
   * [Building a Test Directory](#building-a-test-directory)
   * [Building a Test Subtree](#building-a-test-subtree)
+  * [Test Executors](#test-executors)
+    * [The Standalone Test Runner and Build Time Test Filtering](#the-standalone-test-runner-and-build-time-test-filtering)
+    * [Building all tests with the Standalone Runner](#building-all-tests-with-the-standalone-runner)
   * [Building C++/CLI Native Test Components Against the Live Ref Assemblies](#building-ccli-native-test-components-against-the-live-ref-assemblies)
   * [Test Priorities](#test-priorities)
 * [Running the Tests](#running-the-tests)
   * [Running Individual Tests](#running-individual-tests)
-    * [Tests Without a Main Method](#tests-without-a-main-method)
   * [PAL Tests (macOS and Linux only)](#pal-tests-macos-and-linux-only)
     * [Building PAL Tests](#building-pal-tests)
     * [Running PAL Tests](#running-pal-tests)
@@ -62,7 +64,7 @@ This example assumes you built CoreCLR on _Debug_ mode and the Libraries on _Rel
 
 The following subsections will explain how to segment the test suite according to your needs. There are three main scopes of building tests:
 
-* Individual Test
+* Individual Test Runner
 * Full Directory
 * Entire Subtree
 
@@ -83,19 +85,19 @@ To build an individual test, you have to pass the `-test` flag along with the pa
 On Windows:
 
 ```cmd
-.\src\tests\build.cmd test JIT\Intrinsics\MathRoundDouble_ro.csproj test JIT\Intrinsics\MathFloorDouble_ro.csproj
+.\src\tests\build.cmd test JIT\Methodical\Methodical_d1.csproj test JIT\JIT_ro.csproj
 ```
 
 On macOS and Linux:
 
 ```bash
-./src/tests/build.sh -test:JIT/Intrinsics/MathRoundDouble_ro.csproj -test:JIT/Intrinsics/MathFloorDouble_ro.csproj
+./src/tests/build.sh -test:JIT/Methodical/Methodical_d1.csproj -test:JIT/JIT_ro.csproj
 ```
 
 Alternatively, you can call _build_ directly using the `dotnet.cmd/dotnet.sh` script at the root of the repo and pass all arguments directly yourself:
 
 ```bash
-./dotnet.sh build -c <Your Configuration> src/tests/path/to/test/csproj
+./dotnet.sh build -c <Your Configuration> src/tests/path/to/test.csproj
 ```
 
 ### Building a Test Directory
@@ -105,13 +107,13 @@ To build all the tests contained in an individual directory, you have to pass th
 On Windows:
 
 ```cmd
-.\src\tests\build.cmd dir JIT\Methodical\Arrays\lcs dir JIT\Methodical\cctor\misc\Desktop
+.\src\tests\build.cmd dir JIT dir Loader
 ```
 
 On macOS and Linux:
 
 ```bash
-./src/tests/build.sh -dir:JIT/Methodical/Arrays/lcs -dir:JIT/Methodical/cctor/misc/Desktop
+./src/tests/build.sh -dir:JIT -dir:Loader
 ```
 
 ### Building a Test Subtree
@@ -130,6 +132,24 @@ On macOS and Linux:
 ./src/tests/build.sh -tree:baseservices/exceptions -tree:JIT/Methodical
 ```
 
+### Test Executors
+
+We have multiple different mechanisms of executing tests.
+
+Our test entrypoints are generally what we call "merged test runners", as they provide an executable runner project for multiple different test assemblies. These projects can be identified by the `<Import Project="$(TestSourceDir)MergedTestRunner.targets" />` line in their .csproj file. These projects provide a simple experience for running tests. When executing a merged runner project, it will run each test sequentially and record if it passes or fails in an xunit results file. The merged test runner support runtime test filtering. If specified, the first argument to the test runner is treated as a `dotnet test --filter` argument following the xUnit rules in their documentation. Today, the runner only supports the simple form, a substring of a test's fully-qualified name, in the format `Namespace.ContainingTypeName.TypeName.Method`. If support for further filtering options is desired, please open an issue requesting it.
+
+Some tests need to be run in their own process as they interact with global process state, they have a custom test entrypoint, or they interact poorly with other tests in the same process. These tests are generally marked with `<RequiresProcessIsolation>true</RequiresProcessIsolation>` in their project files. These tests can be run directly, but they can also be invoked through their corresponding merged test runner. The merged test runner will invoke them as a subprocess in the same manner as if they were run individually.
+
+#### The Standalone Test Runner and Build Time Test Filtering
+
+Sometimes you may want to run a test with the least amount of code before actually executing the test. In addition to the merged test runner, we have another runner mode known as the "Standalone" runner. This runner is used by default in tests that require process isolation. This runner consists of a simple `try-catch` around executing each test sequentially, with no test results file or runtime test filtering.
+
+To filter tests on a merged test runner built as standalone, you can set the `TestFilter` property, like so: `./dotnet.sh build -c Checked src/tests/path/to/test.csproj -p:TestFilter=SubstringOfFullyQualifiedTestName`. This mechanism supports the same filtering as the runtime test filtering. Using this mechanism will allow you to skip individual test cases at build time instead of at runtime.
+
+#### Building all tests with the Standalone Runner
+
+If you wish to use the Standalone runner described in the [previous section](#the-standalone-test-runner-and-build-time-test-filtering), you can set the `BuildAllTestsAsStandalone` environment variable to `true` when invoking the `./src/tests/build.sh` or `./src/tests/build.cmd` scripts (for example, `export BuildAllTestsAsStandalone=true` or `set BuildAllTestsAsStandalone=true`). This will build all tests that are not directly in a merged test runner's project as separate executable tests and build only the tests that are compiled into the runner directly. If a runner has no tests that are built directly into the runner, then it will be excluded.
+
 ### Building C++/CLI Native Test Components Against the Live Ref Assemblies
 
 By default, the _C++/CLI_ native test components build against the _ref pack_ from the SDK specified in the `global.json` file in the root of the repository. To build these components against the _ref assemblies_ produced in the build, pass the `-cmakeargs -DCPP_CLI_LIVE_REF_ASSEMBLIES=1` parameters to the test build. For example:
@@ -233,9 +253,7 @@ cd path/to/JIT/Intrinsics/MathRoundDouble_ro
 ./MathRoundDouble_ro.sh -coreroot=<repo_root>/artifacts/tests/coreclr/<OS>.<Arch>.<Configuration>/Tests/Core_Root
 ```
 
-#### Tests Without a Main Method
-
-Guide on how to run tests without a `Main()` Method coming soon!
+If you want to run an individual test from a test runner, use the filtering capabilities described in the [Test Executors section](#test-executors).
 
 ### PAL Tests (macOS and Linux only)
 

src/tests/Directory.Build.targets

@@ -34,8 +34,8 @@
 
   <!-- Default priority building values. -->
   <PropertyGroup>
-    <DisableProjectBuild Condition="'$(IsMergedTestRunnerAssembly)' == 'true' and $(BuildAsStandalone)">true</DisableProjectBuild>
-    <OutputType Condition="('$(IsMergedTestRunnerAssembly)' == 'true' and !$(BuildAsStandalone)) or ('$(RequiresProcessIsolation)' == 'true' and '$(CLRTestKind)' != 'SharedLibrary')">Exe</OutputType>
+    <DisableProjectBuild Condition="'$(IsMergedTestRunnerAssembly)' == 'true' and '$(BuildAllTestsAsStandalone)' == 'true' and '$(HasMergedInTests)' != 'true'">true</DisableProjectBuild>
+    <OutputType Condition="('$(IsMergedTestRunnerAssembly)' == 'true' and '$(BuildAllTestsAsStandalone)' != 'true') or ('$(RequiresProcessIsolation)' == 'true' and '$(CLRTestKind)' != 'SharedLibrary')">Exe</OutputType>
 
     <CLRTestKind Condition="'$(CLRTestKind)' == '' and '$(OutputType)' == 'Exe'">BuildAndRun</CLRTestKind>
     <CLRTestKind Condition="'$(CLRTestKind)' == ''">SharedLibrary</CLRTestKind>
@@ -441,7 +441,7 @@
 
     <ItemGroup>
       <Content Include="$(AssemblyName).reflect.xml" Condition="Exists('$(AssemblyName).reflect.xml')" CopyToOutputDirectory="PreserveNewest" />
-      <MarkerFile Include="$(IntermediateOutputPath)\$(MSBuildProjectName).MergedTestAssembly" Condition="'$(IsMergedTestRunnerAssembly)' == 'true'">
+      <MarkerFile Include="$(IntermediateOutputPath)\$(MSBuildProjectName).MergedTestAssembly" Condition="'$(IsMergedTestRunnerAssembly)' == 'true' and '$(BuildAllTestsAsStandalone)' != 'true'">
         <Type>MergedTestAssembly</Type>
       </MarkerFile>
       <MarkerFile Include="$(IntermediateOutputPath)\$(AssemblyName).NoMonoAot" Condition="'$(MonoAotIncompatible)' == 'true'">

src/tests/Directory.Merged.props

@@ -1,6 +1,7 @@
 <Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
   <PropertyGroup>
     <InMergedTestDirectory>true</InMergedTestDirectory>
+    <BuildAsStandalone Condition="'$(BuildAllTestsAsStandalone)' == 'true'">true</BuildAsStandalone>
     <BuildAsStandalone Condition="'$(BuildAsStandalone)' == ''">false</BuildAsStandalone>
   </PropertyGroup>
 </Project>

src/tests/Interop/Interop.csproj

@@ -6,6 +6,7 @@
     <Configurations>Debug;Release;Checked</Configurations>
     <!-- Tracking issue: https://github.com/dotnet/runtime/issues/90427 -->
     <CLRTestTargetUnsupported Condition="'$(RuntimeFlavor)' == 'mono' and '$(RuntimeVariant)' == 'minifullaot'">true</CLRTestTargetUnsupported>
+    <HasMergedInTests>true</HasMergedInTests>
   </PropertyGroup>
   <ItemGroup>
     <SupportProject Include="$(TestLibraryProjectPath)" />

src/tests/Interop/StringMarshalling/AnsiBSTR/AnsiBStrTest.csproj

@@ -13,5 +13,6 @@
   </ItemGroup>
   <ItemGroup>
     <ProjectReference Include="$(TestLibraryProjectPath)" />
+    <CMakeProjectReference Include="./CMakeLists.txt" />
   </ItemGroup>
 </Project>

src/tests/Interop/StringMarshalling/LPTSTR/LPTSTRTest.csproj

@@ -12,5 +12,6 @@
   </ItemGroup>
   <ItemGroup>
     <ProjectReference Include="$(TestLibraryProjectPath)" />
+    <CMakeProjectReference Include="./CMakeLists.txt" />
   </ItemGroup>
 </Project>

src/tests/Interop/StringMarshalling/UTF8/UTF8Test.csproj

@@ -7,5 +7,6 @@
   </ItemGroup>
   <ItemGroup>
     <ProjectReference Include="$(TestLibraryProjectPath)" />
+    <CMakeProjectReference Include="./CMakeLists.txt" />
   </ItemGroup>
 </Project>

src/tests/Interop/StringMarshalling/VBByRefStr/VBByRefStrTest.csproj

@@ -6,5 +6,6 @@
   </PropertyGroup>
   <ItemGroup>
     <Compile Include="*.cs" />
+    <CMakeProjectReference Include="./CMakeLists.txt" />
   </ItemGroup>
 </Project>

src/tests/MergedTestRunner.targets

@@ -17,6 +17,11 @@
     <!-- string.Concat("_", string.Copy("%(Filename)").Replace("-", "_").Replace(".", "_")) -->
     <MergedWrapperProjectReference Update="**" Aliases="$([System.String]::Concat(&quot;_&quot;,$([System.String]::Copy(&quot;%(Filename)&quot;).Replace(&quot;-&quot;,&quot;_&quot;).Replace(&quot;.&quot;,&quot;_&quot;))))" />
 
-    <ProjectReference Include="@(MergedWrapperProjectReference)" />
+    <!--
+      If the merged test runner was specified to be built as Standalone, don't force the referenced projects to be built that way as well.
+      If we're building all tests as standalone, then don't reference the other test projects from the merged wrapper. We'll only build the tests in the wrapper itself
+      into it.
+    -->
+    <ProjectReference Include="@(MergedWrapperProjectReference)" UndefineProperties="BuildAsStandalone" Condition="'$(BuildAllTestsAsStandalone)' != 'true'" />
   </ItemGroup>
 </Project>

src/tests/build.proj

@@ -567,6 +567,7 @@
 
   <Target Name="BuildManagedTestGroups" DependsOnTargets="RestorePackages;ResolveDisabledProjects;BuildNativeAotFrameworkObjects">
     <Message Importance="High" Text="$(MsgPrefix)Building managed test components" />
+    <Warning Text="Building the whole test suite with the BuildAsStandalone=true environment variable will cause some tests to be executed twice. Use the BuildAllTestsAsStandalone=true environment variable instead." Condition="'$(BuildAsStandalone)' == 'true'" />
     <!-- Execute msbuild test build in stages - workaround for excessive data retention in MSBuild ConfigCache -->
     <!-- See https://github.com/Microsoft/msbuild/issues/2993 -->