In NUnit 5, what do [NonParallelizable] and [LevelOfParallelism] control, and how many worker threads does a run use by default?
answer
- a separate non-parallel shift
- assembly-only worker count
- max of processor count and 2
- the runner's NumberOfTestWorkers setting
- zero workers means sequential
basics
~10 s[NonParallelizable] keeps a fixture or test out of parallel execution, so it never overlaps parallel work. [LevelOfParallelism(n)], assembly-only, sets the parallel worker count, which defaults to the larger of the processor count and 2.
solid answer
~40 s`[NonParallelizable]` (which is `ParallelScope.None`) puts a fixture or test on NUnit's **non-parallel queue**. NUnit's dispatcher works in **shifts** that never overlap: parallel items run in the parallel shift, non-parallel items in their own shift, so a non-parallel fixture never runs while parallel tests are in flight. It also overrides a parallel scope inherited from the assembly. `[LevelOfParallelism(n)]` is valid **only on the assembly** and sets how many parallel workers NUnit creates; without it NUnit uses `Math.Max(Environment.ProcessorCount, 2)`. A runner can override both through the `NumberOfTestWorkers` setting, and a value of 0 makes NUnit use a simple sequential dispatcher. The workers only matter for items that opted in with `[Parallelizable]`.
code
csharp · 12 lines// Test project, assembly level
[assembly: Parallelizable(ParallelScope.Fixtures)]
[assembly: LevelOfParallelism(4)]
namespace Bank.Tests;
[NonParallelizable] // the only fixture that uses the shared ledger file
public class LedgerExportTests
{
[Test]
public void Export_appends_to_daily_file() { /* ... */ }
}go deeper
Recall that [NonParallelizable] opts an item out and that the worker count defaults to the processor count, with a minimum of two.
Explain the non-overlapping shifts, why [LevelOfParallelism] is assembly-only, and the order in which the runner setting, the attribute and the default are applied.
Size workers for the suite's real bottleneck, and replace blanket [NonParallelizable] markers with isolated resources where the run time matters.
Set agent sizing and worker policy for CI so test parallelism, shared sandboxes and build capacity are planned together rather than tuned per project.
## Two different controls These attributes are often confused because both mention parallelism, but they answer different questions: | Attribute | Question it answers | Valid on | |---|---|---| | `[NonParallelizable]` | may **this** item overlap other tests? | assembly, class, method | | `[LevelOfParallelism(n)]` | how many **parallel workers** does the run get? | assembly only | `[LevelOfParallelism]` is declared with `AttributeTargets.Assembly`, so putting it on a class does not compile. ## How NUnit dispatches work When parallel execution is enabled, NUnit's `ParallelWorkItemDispatcher` creates **queues** and **workers**: - a parallel queue served by `n` workers (named `NUnit.Fw.ParallelWorker#1` to `#n`); - a parallel queue for tests that need an STA thread, with its own worker; - a non-parallel queue and a non-parallel STA queue, each with a single worker. Queues are grouped into **shifts**. Work in a shift continues until its queues are empty and its workers idle; then the next shift may start. The parallel shift and the non-parallel shifts **never run at the same time**. That is what `[NonParallelizable]` buys: a fixture on the non-parallel queue runs with nothing else in flight. ## [NonParallelizable] in practice - It derives from `[Parallelizable]` with scope `None`; a scope that combines `Self` and `None` is rejected as "Test may not be both parallel and non-parallel". - It **overrides an inherited context**: under `[assembly: Parallelizable(ParallelScope.Fixtures)]`, a fixture marked `[NonParallelizable]` still runs on the non-parallel path. - Use it for fixtures that touch something the others also touch and that cannot be isolated: one fixed ledger file, a process-wide environment variable, the current culture, a single shared external account in a sandbox. - It is coarse. Each non-parallel fixture runs alone, so a suite with many of them gains little from parallelism. Isolating the resource (a unique temp directory per test, a unique account id) is usually the better long-term fix. ## The worker count The default comes from `NUnitTestAssemblyRunner.DefaultLevelOfParallelism`, which is `Math.Max(Environment.ProcessorCount, 2)`: a 16-core build agent gets 16 parallel workers, a single-core container still gets 2. The value NUnit uses is resolved in this order: 1. The runner setting `NumberOfTestWorkers`, if the runner passes one. 2. `[assembly: LevelOfParallelism(n)]`, if present. 3. The default above. If the result is greater than zero, NUnit uses the parallel dispatcher; if it is **zero**, it uses a simple sequential dispatcher and nothing runs in parallel, whatever the attributes say. That makes a worker count of 0 a quick way to check whether an intermittent failure disappears without parallelism. ## Reading the dispatcher in a log Each parallel worker has a stable name, and `TestContext.CurrentContext.WorkerId` returns it inside a test. Logging it beside the test name shows at a glance which tests overlapped, which ran on the non-parallel worker, and whether the configured count was used: with `[assembly: LevelOfParallelism(4)]` no name beyond `NUnit.Fw.ParallelWorker#4` should appear. ## Choosing a value for a banking suite - **CPU-bound tests** (interest calculations, statement formatting) scale roughly with cores; the default is a sensible start. - **I/O-bound tests** (a local database, HTTP to a sandbox) may tolerate more workers than cores, but they also put load on the shared dependency; too many workers make the dependency the bottleneck or trip its rate limits. - **Memory-heavy tests** may need fewer workers on small agents. - Measure: run with a few values and compare wall-clock time and failure rate rather than assuming more workers is faster. ## Common mistakes - Expecting `[LevelOfParallelism]` to enable parallel execution. It only sizes the pool; tests still need `[Parallelizable]`. - Marking every slow fixture `[NonParallelizable]` "to be safe", which quietly returns most of the suite to sequential speed. - Leaving a high worker count on a machine shared by several test runs, where the processor count no longer reflects what the run actually gets.
- How many parallel workers does NUnit create on a 1-CPU container if nothing configures it?Two. The default level of parallelism is `Math.Max(Environment.ProcessorCount, 2)`, so even a single-processor machine gets two parallel workers, plus the separate STA and non-parallel workers NUnit always creates for the parallel dispatcher.
- Which wins in NUnit: [assembly: LevelOfParallelism(4)] or the runner's NumberOfTestWorkers setting?The runner setting. NUnit reads `NumberOfTestWorkers` from the run settings first and only falls back to the assembly attribute, then to the default, when the setting is absent.
- How do you turn off NUnit parallel execution for one CI run without editing code?Pass a worker count of 0 through the runner's `NumberOfTestWorkers` setting. With zero workers NUnit uses its simple sequential dispatcher, so `[Parallelizable]` attributes have no effect for that run.
A workshop runs a day shift with several technicians working side by side and a separate night shift for the one job that needs the whole floor to itself. The two shifts never overlap. Parallel tests are the day crew; a [NonParallelizable] fixture is the night job.
- [LevelOfParallelism] on a fixture limits that fixture's threads
- Setting [LevelOfParallelism(8)] makes tests run in parallel by itself
- NUnit's default worker count is always exactly 1
- [NonParallelizable] fixtures still overlap with parallel fixtures
- The assembly attribute overrides the runner's NumberOfTestWorkers setting
- A single-core agent gets only one parallel worker by default