1
0
Fork 0
mirror of https://github.com/VSadov/Satori.git synced 2025-06-11 02:13:38 +09:00

Update library testing docs page to reduce confusion (#54324)

* Add warning on unmaintained testing doc page

* Update testing.md

Some example text that seems more clear to me, but only offered as a suggestion. 
Feel free to adjust it or if you want to use it as-is please double check what I wrote is accurate : )

I think the useful elements are:
1. Being explicit about what workflow steps need to happen in total
2. Being explicit about which commands are covering the entire workflow and which ones are only covering a part of it
3. Show the simple "do-it-all" options first before showing more complex partial options. Glancing at the first example and blindly copying it should land in the pit of success.

Co-authored-by: Viktor Hofer <viktor.hofer@microsoft.com>
This commit is contained in:
Noah Falk 2021-06-23 00:00:47 -07:00 committed by GitHub
parent 0aafceb47a
commit d783a8c812
Signed by: github
GPG key ID: 4AEE18F83AFDEB23

View file

@ -1,54 +1,71 @@
# Testing Libraries
We use the OSS testing framework [xunit](https://github.com/xunit/xunit).
## Full Build and Test Run
To build the tests and run them you can call the libraries build script. For libraries tests to work, you must have built the coreclr or mono runtime for them to run on.
These example commands automate the test run and all pre-requisite build steps in a single command from a clean enlistment.
**Examples**
- The following shows how to build only the tests but not run them:
```
build.cmd/sh -subset libs.tests
```
- The following builds and runs all tests using clr:
```
build.cmd/sh -subset clr+libs.tests -test
```
- The following builds and runs all tests using mono:
```
build.cmd/sh -subset mono+libs.tests -test
```
- The following builds and runs all tests in release configuration:
```
build.cmd/sh -subset libs.tests -test -c Release
```
- The following builds clr in release, libs in debug and runs all tests:
- Run all tests - Builds clr in release, libs+tests in debug:
```
build.cmd/sh -subset clr+libs+libs.tests -test -rc Release
```
- The following builds mono and libs for x86 architecture and runs all tests:
- Run all tests - Builds Mono in release, libs+tests in debug:
```
build.cmd/sh -subset mono+libs+libs.tests -test -rc Release
```
- Run all tests - Build Mono and libs for x86 architecture in debug (choosing debug for runtime will run very slowly):
```
build.cmd/sh -subset mono+libs+libs.tests -test -arch x86
```
- The following example shows how to pass extra msbuild properties to ignore tests ignored in CI:
## Partial Build and Test Runs
Doing full build and test runs takes a long time and is very inefficient if you need to iterate on a change.
For greater control and efficiency individual parts of the build + testing workflow can be run in isolation.
See the [Building instructions](../../building/libraries/README.md) for more info on build options.
### Test Run Pre-requisites
Before any tests can run we need a complete build to run them on. This requires building (1) a runtime, and
(2) all the libraries. Examples:
- Build release clr + debug libraries
```
build.cmd/sh -subset libs.tests -test /p:WithoutCategories=IgnoreForCI
build.cmd/sh -subset clr+libs -rc Release
```
Unless you specifiy `-testnobuild`, test assemblies are implicitly built when invoking the `Test` action.
- The following shows how to only test the libraries without building them
- Build release mono + debug libraries
```
build.cmd/sh -subset mono+libs -rc Release
```
Building the `libs` subset or any of individual library projects automatically copies product binaries into the testhost folder
in the bin directory. This is where the tests will load the binaries from during the run. However System.Private.CorLib is an
exception - the build does not automatically copy it to the testhost folder. If you [rebuild System.Private.CoreLib](https://github.com/dotnet/runtime/blob/main/docs/workflow/building/libraries/README.md#iterating-on-systemprivatecorelib-changes) you must also build the `libs.pretest` subset to ensure S.P.C is copied before running tests.
### Running tests for all libraries
- Build and run all tests in release configuration.
```
build.cmd/sh -subset libs.tests -test -c Release
```
- Build the tests without running them
```
build.cmd/sh -subset libs.tests
```
- Run the tests without building them
```
build.cmd/sh -subset libs.tests -test -testnobuild
```
## Running tests on the command line
- The following example shows how to pass extra msbuild properties to ignore tests ignored in CI.
```
build.cmd/sh -subset libs.tests -test /p:WithoutCategories=IgnoreForCI
```
To build tests you need to specify the `test` subset when invoking build.cmd/sh: `build.cmd/sh -subset libs.tests`.
### Running tests for a single library
The easiest (and recommended) way to build and run the tests for a specific library, is to invoke the `Test` target on that library:
```cmd
@ -68,21 +85,21 @@ dotnet build /t:Test /p:TargetArchitecture=x86
There may be multiple projects in some directories so you may need to specify the path to a specific test project to get it to build and run the tests.
#### Running a single test on the command line
### Running a single test on the command line
To quickly run or debug a single test from the command line, set the XunitMethodName property, e.g.:
```cmd
dotnet build /t:Test /p:XunitMethodName={FullyQualifiedNamespace}.{ClassName}.{MethodName}
```
#### Running outer loop tests
### Running outer loop tests
To run all tests, including "outer loop" tests (which are typically slower and in some test suites less reliable, but which are more comprehensive):
```cmd
dotnet build /t:Test /p:Outerloop=true
```
#### Running tests on a different target framework
### Running tests on a different target framework
Each test project can potentially have multiple target frameworks. There are some tests that might be OS-specific, or might be testing an API that is available only on some target frameworks, so the `TargetFrameworks` property specifies the valid target frameworks. By default we will build and run only the default build target framework which is `net5.0`. The rest of the `TargetFrameworks` will need to be built and ran by specifying the `BuildTargetFramework` option, e.g.:
```cmd