In xunit.v3, why do tests in one class run one after another while different classes run in parallel, and how do you change that?
answer
- the test collection is the parallel unit
- default: one collection per class
- ParallelMode.Collections by default
- max threads = processor count
- [assembly: Parallelization(Mode = ...)]
basics
~10 sxUnit.net parallelises test collections, and by default each class is its own collection whose tests run serially. Regroup with [Collection] or [CollectionBehavior]; set mode and thread count with [assembly: Parallelization(...)] or xunit.runner.json.
solid answer
~40 sThe unit of parallel scheduling is the **test collection**. With the default `CollectionBehavior.CollectionPerClass`, every class is its own collection, and the default `ParallelMode.Collections` runs collections in parallel and the tests inside a collection serially, with up to `Environment.ProcessorCount` tests at once. So two tests in one class never overlap, while two classes can. To change it: `[Collection("Search")]` groups classes so they run serially together; `[CollectionDefinition(..., DisableParallelization = true)]` runs a collection alone; `[assembly: CollectionBehavior(CollectionBehavior.CollectionPerAssembly)]` puts every class into one collection; and in xunit.v3 4.x `[assembly: Parallelization(Mode = ParallelMode.None, MaxThreads = 4)]`, or `parallelMode` and `maxParallelThreads` in `xunit.runner.json`, set the mode and thread count. The older `CollectionBehavior(DisableTestParallelization = true)` and `MaxParallelThreads` properties are now obsolete errors. `ParallelMode.All` parallelises even tests inside a class.
code
csharp · 16 linesusing Xunit.Sdk;
using Xunit.v3;
// One declaration per assembly: cap concurrency at 4 tests
[assembly: Parallelization(Mode = ParallelMode.Collections, MaxThreads = 4)]
// Classes that rewrite the shared on-disk index run alone
[CollectionDefinition("IndexRebuild", DisableParallelization = true)]
public class IndexRebuildCollection { }
[Collection("IndexRebuild")]
public class ReindexTests
{
[Fact]
public void Full_rebuild_replaces_segments() { /* ... */ }
}go deeper
Remember: tests in one class run one after another; different classes can run at the same time.
Explain test collections as the parallel unit, the CollectionPerClass and ParallelMode.Collections defaults, and how [Collection] changes grouping.
Diagnose suites that fail only in parallel, isolate collections with DisableParallelization, and use the xunit.v3 4.x Parallelization attribute instead of obsolete CollectionBehavior properties.
Trade suite wall-clock time against isolation: decide thread budgets for CI agents and which shared resources justify serial collections.
## The test collection is the unit of parallelism xUnit.net does not decide parallelism test by test. It groups tests into **test collections** and schedules collections: - **Collections run in parallel** with each other, up to a thread limit. - **Tests inside one collection run serially**, one after another. - By default, `CollectionBehavior.CollectionPerClass` makes **each test class its own collection**. Put together, that explains the behaviour interviewers ask about: two tests in one class never overlap, which is why tests in a class can share a class fixture without locking, while tests in two different classes can run at the same moment. A class that silently depends on another class's side effects, such as a static field or a shared file, is the classic source of failures that appear only when the whole suite runs. ## The defaults in xunit.v3 4.x | Setting | Default | Meaning | |---|---|---| | collection behaviour | `CollectionPerClass` | one collection per test class | | parallel mode | `ParallelMode.Collections` | collections in parallel, tests within a collection serial | | maximum threads | `Environment.ProcessorCount` | `0` or unset means processor count; a negative value means unlimited | | algorithm | `ParallelAlgorithm.Conservative` | starts no more tests than the thread limit | ## Changing the grouping - `[Collection("Search")]` on several classes, or `[Collection<SearchCollection>]` with an unnamed definition, merges them into one collection, so they run serially with respect to each other. That is also how a collection fixture is shared. - `[CollectionDefinition("Search", DisableParallelization = true)]` makes that collection run **alone**, never alongside any other tests; it suits tests that change process-wide state. - `[assembly: CollectionBehavior(CollectionBehavior.CollectionPerAssembly)]` puts every class not assigned elsewhere into one assembly-wide collection, which effectively makes the suite serial. ## Changing the mode and the thread count In xunit.v3 4.x these live on one assembly attribute, `ParallelizationAttribute` in the `Xunit.v3` namespace, with `ParallelMode` from `Xunit.Sdk`: ```csharp // Alternatives: an assembly may declare the attribute only once [assembly: Parallelization(Mode = ParallelMode.None)] // everything serial [assembly: Parallelization(MaxThreads = 4)] // at most 4 tests at once [assembly: Parallelization(Mode = ParallelMode.All)] // tests inside a class too ``` The attribute allows one use per assembly, so combine properties in a single declaration when you need more than one. The same settings exist in `xunit.runner.json`: `"parallelMode": "none" | "collections" | "all"`, `"maxParallelThreads"` as a number, `"default"`, `"unlimited"` or a multiplier such as `"2x"` of the processor count, and `"parallelAlgorithm"`. The older `"parallelizeTestCollections": false` is still honoured when `parallelMode` is not set and maps to no parallelism. The properties many v2-era suites used, `[assembly: CollectionBehavior(DisableTestParallelization = true)]` and `CollectionBehavior.MaxParallelThreads`, are marked `[Obsolete(..., error: true)]` in xunit.v3 4.x with a pointer to `ParallelizationAttribute`, so they no longer compile. ## Conservative versus aggressive scheduling `ParallelAlgorithm` decides how the thread limit is enforced: - **Conservative** (default) uses a semaphore so that no more tests are **started** than the limit allows. Tests that have started finish sooner because nothing new competes with them, but CPU use drops when many async tests sit waiting on I/O. - **Aggressive** limits the number of tests **running** through a synchronization context, so more tests can be in flight and the CPU stays busier, at the cost of started tests waiting longer in the queue to resume. xUnit.net warns that per-test `Timeout` values are only reliable under the conservative algorithm or with parallelism off. ## Full parallelism `ParallelMode.All` lifts the per-collection restriction and runs tests in parallel regardless of collection, including tests in the same class. Two consequences: 1. Class fixtures and collection fixtures can now be read by several tests at once, so they must be thread-safe. 2. Individual tests that cannot run concurrently opt out with `[Fact(DisableParallelization = true)]`, a property that only takes effect in this mode. ## Diagnosing a suite that fails only in parallel 1. Confirm it with `parallelMode` set to `none`: if the failures vanish, tests share state. 2. Look for statics, shared files, ports, environment variables and culture changes touched by different classes. 3. Remove the sharing where possible; otherwise group the offending classes in one collection, or mark that collection `DisableParallelization = true`. 4. Turning parallelism off for the whole assembly fixes the symptom at the cost of the suite's speed.
- Why are tests inside one class safe to share a class fixture without locks under the default settings?Because a class is its own collection by default and a collection runs its tests serially, no two tests of that class execute at the same time, so they never read or write the fixture concurrently. That guarantee disappears under `ParallelMode.All`, where tests in one class can overlap and the fixture must be thread-safe.
- Your suite fails only when run in full. What is the quickest confirmation that parallelism is involved?Run it once with `"parallelMode": "none"` in `xunit.runner.json`, or `[assembly: Parallelization(Mode = ParallelMode.None)]`. If the failures disappear, tests in different collections share state such as statics, files or environment variables. Then fix the sharing or group the classes into one collection rather than leaving the whole suite serial.
- xUnit.net runs the tests inside one class in parallel by default.
- [assembly: CollectionBehavior(DisableTestParallelization = true)] is how xunit.v3 4.x turns parallelism off.
- maxParallelThreads defaults to 1 unless configured.
- [Fact(DisableParallelization = true)] serialises a test under the default parallel mode.
- Putting classes in one [Collection] makes their tests run in parallel with each other.
Assumes xunit.v3 4.x, where [assembly: Parallelization(Mode, MaxThreads, Algorithm)] and ParallelMode replace CollectionBehavior's DisableTestParallelization, MaxParallelThreads and ParallelAlgorithm properties, which are marked obsolete as errors.