Add parallel autest runner for faster test execution

CMakeLists.txt

@@ -632,10 +632,16 @@ if(ENABLE_DOCS)
 endif()
 
 if(ENABLE_AUTEST)
+  # Default the sandbox to /tmp to keep paths short. Unix domain socket paths
+  # are limited to 108 characters and deep build directories (e.g. in home
+  # directories) can exceed this limit, causing confusing test failures. A hash
+  # of CMAKE_BINARY_DIR provides per-build isolation while keeping the path
+  # deterministic across runs.
+  string(MD5 _build_dir_hash "${CMAKE_BINARY_DIR}")
+  string(SUBSTRING "${_build_dir_hash}" 0 8 _build_dir_hash)
   set(AUTEST_SANDBOX
-      ${CMAKE_BINARY_DIR}/_sandbox
-      CACHE STRING "Location for autest output (default
-  CMAKE_BINARY_DIR/_sandbox)"
+      "/tmp/sb_${_build_dir_hash}"
+      CACHE STRING "Location for autest output (default /tmp/sb_<hash>)"
   )
   set(AUTEST_OPTIONS
       ""

doc/developer-guide/testing/autests.en.rst

@@ -73,6 +73,15 @@ For example, to run ``cache-auth.test.py``:
 
    ./autest.sh --sandbox /tmp/sbcursor --clean=none -f cache-auth
 
+To run tests in parallel, pass ``-j N`` where ``N`` is the number of worker
+processes. Each worker gets an isolated port range to avoid conflicts:
+
+.. code-block:: bash
+
+   ./autest.sh -j 10 --sandbox /tmp/sbcursor -f cache-auth -f cache-control
+
+Without ``-j``, tests run sequentially.
+
 Recommended Approach: ATSReplayTest
 ====================================
 

tests/CMakeLists.txt

@@ -57,6 +57,7 @@ endif()
 
 configure_file(pyproject.toml pyproject.toml COPYONLY)
 configure_file(autest.sh.in autest.sh)
+configure_file(autest-parallel.py.in autest-parallel.py)
 
 add_custom_target(
   autest

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.