-:Authors: Jason Lowe-Power
- Sean Wilson
-
This file explains how to use gem5's updated testing infrastructure. Running
tests before submitting a patch is *incredibly important* so unexpected bugs
don't creep into gem5.
* Fast execution in the simple case
* High coverage of gem5 code
-# Running tests
+# Running unit tests
+
+gem5 comes with unit tests, created using the Google Test framework. These can
+be built through SCons.
+
+To build and run all the unit tests:
+
+```shell
+scons build/NULL/unittests.opt
+```
+
+All unit tests should be run prior to posting a patch to
+https://gem5-review.googlesource.com
+
+To compile and run just one set of tests (e.g. those declared within
+`src/base/bitunion.test.cc`):
+
+```shell
+scons build/NULL/base/bitunion.test.opt
+./build/NULL/base/bitunion.test.opt
+```
+
+To list the available test functions from a test file:
+
+```shell
+./build/NULL/base/bitunion.test.opt --gtest_list_tests
+```
+
+To run a specific test function (e.g., BitUnionData.NormalBitfield):
+
+```shell
+./build/NULL/base/bitunion.test.opt --gtest_filter=BitUnionData.NormalBitfield
+```
+
+# Running system-level tests
+
+Within the `tests` directory we have system-level tests. These tests run
+the gem5 framework against various hardware configurations, with different
+ISAs, then verify the simulations execute correctly. These should be seen as
+high-level, coarse-grained tests to compliment the unit-tests.
Below is the most common way the tests are run. This will run all of the
"quick" tests for X86, ARM, and RISC-V. These tests make up our best-supported
./main.py run
```
-The above is the *minumum* you should run before posting a patch to
+The above is the *minumum* you should run before posting a patch to
https://gem5-review.googlesource.com
## Specifying a subset of tests to run
./main.py rerun
```
-# If something goes wrong
+## If something goes wrong
The first step is to turn up the verbosity of the output using `-v`. This will
allow you to see what tests are running and why a test is failing.
(e.g., it's not a new-style test).
-# Binary test applications
+## Binary test applications
-The code for test binaries that are run in the gem5 guest during testing are
-found in `tests/test-progs`.
+The code for some test binaries that are run in the gem5 guest during
+testing can be found in `tests/test-progs`.
There's one directory per test application.
The source code is under the `source` directory.
You may have a `bin` directory as well.
The `bin` directory is automatically created when running the test case that
-uses the test binary. The binary is downloaded from the gem5 servers the first
+uses the test binary.
+This is not the case when a test is run via the --bin-path option.
+In that scenario a bin directory will be created in the selected path
+rather than in `tests/test-progs`.
+The binary is downloaded from the gem5 servers the first
time it is referenced by a test.
+Some other tests (like Linux-boot) don't have sources inside gem5 and
+are simply downloaded from gem5 servers.
+
## Updating the test binaries
The test infrastructure should check with the gem5 servers to ensure you have
maintainer (see MAINTAINERS).*
-# Running Tests in Parallel
+## Running Tests in Parallel
Whimsy has support for parallel testing baked in. This system supports
running multiple suites at the same time on the same computer. To run