fix(engine): lower default maximum parallel tests to 2x processor count

docs/docs/execution/parallelism.md

@@ -13,7 +13,7 @@ Parallel execution is a major contributor to TUnit's speed advantage. See the [p
 
 ## Default Behavior
 
-With no attributes, every test is eligible to run concurrently. The .NET thread pool determines how many execute at once. For most test suites this is the fastest option and requires no configuration.
+With no attributes, every test is eligible to run concurrently. At most 2 x the processor count run at once. Change this limit with `--maximum-parallel-tests`, the `TUNIT_MAX_PARALLEL_TESTS` environment variable or `context.Settings.Parallelism.MaximumParallelTests`. For most test suites the default is the fastest option and requires no configuration. If your tests share a resource with limited capacity, such as a database connection pool, lower the limit for those tests with `[ParallelLimiter<T>]`: extra concurrent tests add no throughput and only wait inside their test bodies, which counts toward `[Timeout]`.
 
 :::note Async tests and the thread pool
 TUnit uses the standard .NET thread pool and, like most .NET applications, is susceptible to thread pool starvation. Blocking calls or heavy CPU-bound `Task.Run` work can delay async continuations in other tests and cause timed waits to expire.

docs/docs/reference/environment-variables.md

@@ -119,11 +119,11 @@ export JUNIT_XML_OUTPUT_PATH=/path/to/output.xml
 
 ### TUNIT_MAX_PARALLEL_TESTS
 
-Sets the maximum number of tests that can run in parallel.
+Sets the maximum number of tests that can run in parallel. The default is 2 x the processor count.
 
 ```bash
 export TUNIT_MAX_PARALLEL_TESTS=4    # Limit to 4 concurrent tests
-export TUNIT_MAX_PARALLEL_TESTS=0    # Unlimited parallelism
+export TUNIT_MAX_PARALLEL_TESTS=0    # Use the default limit (2 x CPU cores)
 ```
 
 **Equivalent to:** `--maximum-parallel-tests`

docs/docs/reference/programmatic-configuration.md

@@ -63,7 +63,7 @@ On Linux and macOS with .NET 8 or later, SIGTERM (sent by `docker stop`, Kuberne
 
 | Property | Type | Default | Description |
 |---|---|---|---|
-| `MaximumParallelTests` | `int?` | `null` (4 x CPU cores) | Maximum number of tests that can execute concurrently. Set to `null` to use the default heuristic. |
+| `MaximumParallelTests` | `int?` | `null` (2 x CPU cores) | Maximum number of tests that can execute concurrently. Set to `null` to use the default heuristic. |
 
 ### `context.Settings.Display`
 

src/TUnit.Core/README.md

@@ -131,11 +131,11 @@ public class DatabaseTests
 
 ## Configuration
 
-### MSBuild Properties
+### Maximum Parallel Tests
 
-| Property | Default | Description |
-|----------|---------|-------------|
-| `TUnitMaxConcurrency` | `ProcessorCount` | Maximum parallel test execution |
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `--maximum-parallel-tests` / `TUNIT_MAX_PARALLEL_TESTS` | `ProcessorCount * 2` | Maximum number of tests that run at once |
 
 ## Advanced Features
 
@@ -230,7 +230,7 @@ public void Test(int a, int b, int c) { }
 
 1. **Expression Compilation**: TestBuilder uses compiled expressions for fast execution
 2. **Share Data Sources**: Use `Shared = true` for expensive data
-3. **Optimize Parallel Execution**: Adjust `TUnitMaxConcurrency`
+3. **Optimize Parallel Execution**: Adjust `--maximum-parallel-tests`, or use `[ParallelLimiter<T>]` for tests that share a limited resource
 4. **Cache Test Data**: Use lazy initialization for expensive setup
 
 ## Contributing

src/TUnit.Core/Settings/ParallelismSettings.cs

@@ -8,7 +8,7 @@ public sealed class ParallelismSettings
     internal ParallelismSettings() { }
 
     /// <summary>
-    /// Maximum number of tests to run in parallel. Default: <c>null</c> (= 4× CPU cores).
+    /// Maximum number of tests to run in parallel. Default: <c>null</c> (= 2× CPU cores).
     /// Precedence: <c>--maximum-parallel-tests</c> → <c>TUNIT_MAX_PARALLEL_TESTS</c> → TUnitSettings → built-in default.
     /// </summary>
     public int? MaximumParallelTests

src/TUnit.Engine/Scheduling/MaxParallelismLimiter.cs

@@ -17,10 +17,12 @@ internal sealed class MaxParallelismLimiter
     private readonly Lazy<SemaphoreSlim> _semaphore;
 
     /// <summary>
-    /// The cap used when nothing configures one, and for "unlimited" (0). ProcessorCount * 4
-    /// is empirically sized for async/IO-bound workloads.
+    /// The cap used when nothing configures one, and for "unlimited" (0). A higher cap gains
+    /// throughput only when nothing downstream limits concurrency. When a database pool, a
+    /// container or a blocking call is the bottleneck, extra concurrent tests add no throughput:
+    /// they wait inside their bodies, which inflates body time toward [Timeout].
     /// </summary>
-    public static int DefaultMaxParallelism => Environment.ProcessorCount * 4;
+    public static int DefaultMaxParallelism => Environment.ProcessorCount * 2;
 
     public MaxParallelismLimiter(Func<int> resolveMaxParallelism)
     {

src/TUnit.Engine/Scheduling/TestScheduler.cs

@@ -596,7 +596,7 @@ private Task ExecuteTestsAsync(
     {
         // All paths run through the shared limiter so the DOP cap is unified in
         // GetMaxParallelism. "Unlimited" is resolved to the default cap
-        // (ProcessorCount * 4) there rather than being a separate code path.
+        // (ProcessorCount * 2) there rather than being a separate code path.
         return ExecuteWithGlobalLimitAsync(tests, _maxParallelismLimiter.Semaphore, cancellationToken);
     }
 
@@ -757,9 +757,9 @@ internal static int GetMaxParallelism(ILogger logger, ICommandLineOptions comman
             return codeLimit;
         }
 
-        // Default: 4x CPU cores (empirically optimized for async/IO-bound workloads)
+        // Default: 2x CPU cores (see MaxParallelismLimiter.DefaultMaxParallelism)
         // Users can override via --maximum-parallel-tests or TUNIT_MAX_PARALLEL_TESTS
-        logger.LogDebug($"Maximum parallel tests limit defaulting to {defaultLimit} ({Environment.ProcessorCount} processors * 4)");
+        logger.LogDebug($"Maximum parallel tests limit defaulting to {defaultLimit} ({Environment.ProcessorCount} processors * 2)");
         return defaultLimit;
     }
 }