tests, misc: Updating TESTING.md to describe running unit tests
Previously we did not have any documentation discussing how gem5's GTests
were built and executed. TESTING.md has thereby been updated to highlight
how this is done. These unit tests should be run prior to each new
submission to Gerrit. This has been noted in TESTING.md also.
Change-Id: If5867fa0a2e4f6ea0921191a51e779c19a28117a
Reviewed-on: https://gem5-review.googlesource.com/c/public/gem5/+/21479
Reviewed-by: Andreas Sandberg <andreas.sandberg@arm.com>
Reviewed-by: Jason Lowe-Power <jason@lowepower.com>
Maintainer: Jason Lowe-Power <jason@lowepower.com>
Tested-by: kokoro <noreply+kokoro@google.com>
diff --git a/TESTING.md b/TESTING.md
index cb79286..cf160e6 100644
--- a/TESTING.md
+++ b/TESTING.md
@@ -10,7 +10,46 @@
* 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
@@ -24,7 +63,7 @@
./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
@@ -120,7 +159,7 @@
./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.
@@ -156,7 +195,7 @@
(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`.
@@ -186,7 +225,7 @@
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
