This is an automated email from the ASF dual-hosted git repository. bcall pushed a commit to branch parallel-autest in repository https://gitbox.apache.org/repos/asf/trafficserver.git
commit 63f6bc8bffca04514a26e6b28ef2825365d481a4 Author: Bryan Call <[email protected]> AuthorDate: Sun Feb 8 08:28:48 2026 -0800 docs: Add parallel test runner section to tests/README.md Document usage of autest-parallel.py including key options, timing-based load balancing, and how to add serial tests. --- tests/README.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/tests/README.md b/tests/README.md index 5a8ae9dc4a..57127a45a4 100644 --- a/tests/README.md +++ b/tests/README.md @@ -40,6 +40,41 @@ The corresponding `autest.sh` command is: $ ./autest.sh --filter=something_descriptive +# Running tests in parallel + +For faster test execution, a parallel test runner is available that distributes +tests across multiple workers. This is especially useful on machines with many +CPU cores. + + $ python3 autest-parallel.py -j 16 --ats-bin <install>/bin --build-root <build-dir> --sandbox /tmp/autest-parallel + +Key options: + +* `-j N` - Number of parallel workers (default: number of CPU cores) +* `--ats-bin` - Path to the ATS install bin directory +* `--build-root` - Path to the build directory (for test plugins) +* `--sandbox` - Directory for test sandboxes (default: `/tmp/autest-parallel`) +* `-v` - Verbose output with real-time test progress per worker +* `--collect-timings` - Run tests individually to collect per-test timing data +* `--list` - List all tests and exit (useful for checking test discovery) + +The parallel runner uses port offsets to ensure each worker gets a unique port +range, preventing conflicts between concurrent test instances. Tests known to +require serial execution (listed in `serial_tests.txt`) are run sequentially +after the parallel phase completes. + +## Timing-based load balancing + +If a `test-timings.json` file exists (generated by a previous run with +`--collect-timings`), the runner uses the Longest Processing Time (LPT) +algorithm to distribute tests across workers for balanced execution times. +Without timing data, tests are distributed round-robin. + +## Adding serial tests + +If a test cannot run in parallel (e.g., it uses hardcoded global resources), +add its path relative to `gold_tests/` to `serial_tests.txt`. + # Advanced setup AuTest and the relevant tools can be install manually instead of using the wrapper script. By doing this, it is often easier to debug issues with the testing system, or the tests. There are two ways this can be done.
