From 1034489ceafb61330a520a5b9072ca5300b4751f Mon Sep 17 00:00:00 2001 From: Aleksey Kliger Date: Wed, 17 Apr 2024 11:25:45 -0400 Subject: [PATCH 1/2] [docs] Document tools tests workflow --- .../workflow/testing/testing-managed-tools.md | 46 +++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 docs/workflow/testing/testing-managed-tools.md diff --git a/docs/workflow/testing/testing-managed-tools.md b/docs/workflow/testing/testing-managed-tools.md new file mode 100644 index 00000000000000..dbacd48d961edf --- /dev/null +++ b/docs/workflow/testing/testing-managed-tools.md @@ -0,0 +1,46 @@ +# Testing managed tools + +Managed unit and functional tests for a number of tools are included in the product including the +compiler for NativeAOT, and the trimmer (illink) + +## Adding new testsuites + +To add new test suite, create a new `.csproj` with a name that ends in `Tests`, such as: +`MyTool.Tests.csproj`. The property `IsTestProject` will be set by the `Directories.Build.props` in +the repository root. The property will, in turn, add references to the xunit package and the +apropriate test runner. + +Now add a `ProjectToBuild` item to `eng/Substes.props` to one of the existing subsets such as +`clr.toolstests` or add a new subset. + +## Adding new testsuites to CI + +To run the tests in CI, add a new pipeline or add to an exsiting pipeline such as `CLR_Tools_Tests` +in `eng/pipelines/runtime.yml`. Update the trigger condition, perhaps by adding a new set of paths +to `eng/pipelines/common/evaluate-default-paths.yml` in order to run the tests when the tool source +or the test sources change./ + +## Running tests locally + +Build and run the tests locally either with + +```console +./build.[sh|cmd] -s clr.toolstests -c [Release|Debug] -build -test +``` + +or + +```console +./dotnet.[sh|cmd] test .../MyTool.Tests.csproj -c [Release|Debug] +``` + +The `dotnet-test` xunit filter mechanisms work to run a single test or a subset of the tests + +```console +./dotnet.[sh|cmd] test .../MyTool.Tests.csproj -c [Release|Debug] --filter "FullyQualifiedName~MyTest" +``` + +The above command runs all tests whose fully-qualified name contains the substring `MyTest`. See +[dotnet test - Run selective unit +test](https://learn.microsoft.com/en-us/dotnet/core/testing/selective-unit-tests?pivots=mstest#syntax) +for the full syntax. From 689d28cf2d5f7ec0fee9bf97a86ee994a1cbb9fb Mon Sep 17 00:00:00 2001 From: Aleksey Kliger Date: Wed, 17 Apr 2024 12:55:52 -0400 Subject: [PATCH 2/2] typos --- docs/workflow/testing/testing-managed-tools.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/workflow/testing/testing-managed-tools.md b/docs/workflow/testing/testing-managed-tools.md index dbacd48d961edf..6e2fddbdbd7736 100644 --- a/docs/workflow/testing/testing-managed-tools.md +++ b/docs/workflow/testing/testing-managed-tools.md @@ -1,24 +1,24 @@ # Testing managed tools -Managed unit and functional tests for a number of tools are included in the product including the -compiler for NativeAOT, and the trimmer (illink) +There are managed unit and functional tests for a number of tools including the +compiler for NativeAOT (`ILCompiler`), and the trimmer (`illink`). ## Adding new testsuites -To add new test suite, create a new `.csproj` with a name that ends in `Tests`, such as: +To add a new test suite, create a new `.csproj` with a name that ends in `Tests`, such as: `MyTool.Tests.csproj`. The property `IsTestProject` will be set by the `Directories.Build.props` in the repository root. The property will, in turn, add references to the xunit package and the apropriate test runner. -Now add a `ProjectToBuild` item to `eng/Substes.props` to one of the existing subsets such as -`clr.toolstests` or add a new subset. +Now add a `ProjectToBuild` item in `eng/Substes.props` to one of the existing subsets, such as +`clr.toolstests`, or a new subset. ## Adding new testsuites to CI To run the tests in CI, add a new pipeline or add to an exsiting pipeline such as `CLR_Tools_Tests` in `eng/pipelines/runtime.yml`. Update the trigger condition, perhaps by adding a new set of paths to `eng/pipelines/common/evaluate-default-paths.yml` in order to run the tests when the tool source -or the test sources change./ +or the test sources change. ## Running tests locally @@ -41,6 +41,5 @@ The `dotnet-test` xunit filter mechanisms work to run a single test or a subset ``` The above command runs all tests whose fully-qualified name contains the substring `MyTest`. See -[dotnet test - Run selective unit -test](https://learn.microsoft.com/en-us/dotnet/core/testing/selective-unit-tests?pivots=mstest#syntax) +[dotnet test - Run selective unit tests](https://learn.microsoft.com/en-us/dotnet/core/testing/selective-unit-tests?pivots=mstest#syntax) for the full syntax.