Add documentation for serial execution

Co-authored-by: Claude <noreply@anthropic.com>

Author: giordano

docs/src/advanced.md

@@ -127,6 +127,53 @@ end # hide
 ```
 The `init_worker_code` is evaluated once per worker, so all definitions can be imported for use by the test module.
 
+## Serial Tests
+
+Some tests cannot safely run in parallel with other tests — for example, tests that allocate very large arrays and would exhaust memory if multiple ran simultaneously.
+The `serial` keyword argument to [`runtests`](@ref) lets you designate specific tests to run one at a time, while the remaining tests still run in parallel.
+
+```@example mypackage
+using ParallelTestRunner
+using MyPackage
+
+testsuite = Dict(
+    "big_alloc" => quote
+        # This test allocates ~4 GB and should not overlap with other tests
+        @test true
+    end,
+    "huge_matrix" => quote
+        @test true
+    end,
+    "fast_unit" => quote
+        @test 1 + 1 == 2
+    end,
+    "fast_integration" => quote
+        @test true
+    end,
+)
+
+# "big_alloc" and "huge_matrix" run one at a time; the rest run in parallel
+runtests(MyPackage, ARGS; testsuite, serial=["big_alloc", "huge_matrix"])
+```
+
+By default serial tests run **before** the parallel batch.
+Use `serial_position=:after` to run them after instead:
+
+```@example mypackage
+runtests(MyPackage, ARGS; testsuite, serial=["big_alloc", "huge_matrix"], serial_position=:after)
+```
+
+Serial tests participate in the same ordering logic as parallel tests (sorted by historical
+duration, longest first) and their results appear in the same overall summary.
+
+!!! tip
+    With automatic test discovery via [`find_tests`](@ref), the `serial` names are the same
+    keys that appear in the testsuite dictionary (e.g. `"subdir/memory_test"`).
+
+!!! note
+    If the user filters tests via positional arguments (e.g. `julia test/runtests.jl unit`),
+    any serial test names that were filtered out are silently removed from the serial list.
+
 ## Custom Workers
 
 For tests that require specific environment variables or Julia flags, you can use the `test_worker` keyword argument to [`runtests`](@ref) to assign tests to custom workers:
@@ -254,3 +301,5 @@ function jltest {
    Having few long-running test files and other short-running ones hinders scalability.
 
 1. **Use custom workers sparingly**: Custom workers add overhead. Only use them when tests genuinely require different configurations.
+
+1. **Use `serial` for resource-intensive tests**: If a test allocates significant memory or uses exclusive hardware resources, mark it as serial rather than reducing `--jobs` globally. This keeps the rest of your suite running in parallel.

docs/src/api.md

@@ -39,12 +39,13 @@ addworkers
 default_njobs
 ```
 
-## Internal Types
+## Internal Functionalities
 
-These are internal types, not subject to semantic versioning contract (could be changed or removed at any point without notice), not intended for consumption by end-users.
+These are internal types or functions, not subject to semantic versioning contract (could be changed or removed at any point without notice), not intended for consumption by end-users.
 They are documented here exclusively for `ParallelTestRunner` developers and contributors.
 
 ```@docs
 ParsedArgs
 WorkerTestSet
+partition_tests
 ```

docs/src/index.md

@@ -107,6 +107,13 @@ Pkg.test("MyPackage"; test_args=`--verbose --jobs=4 integration`)
 Tests run concurrently in isolated worker processes, each inside own module.
 `ParallelTestRunner` records historical tests duration for each package, so that in subsequent runs long-running tests are executed first, to improve load balancing.
 
+### Serial Test Support
+
+Certain tests (e.g. memory-hungry tests) may need to run one at a time.
+The `serial` keyword argument to [`runtests`](@ref) lets you designate specific tests
+for sequential execution, either before or after the parallel batch.
+See [Serial Tests](@ref) in the advanced usage guide for details.
+
 ### Real-time Progress
 
 The test runner provides real-time output showing: