skip to content

In NUnit 5, what do [NonParallelizable] and [LevelOfParallelism] control, and how many worker threads does a run use by default?

level: middleimportance: should knowfreq 24%

answer

  1. a separate non-parallel shift
  2. assembly-only worker count
  3. max of processor count and 2
  4. the runner's NumberOfTestWorkers setting
  5. 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
csharp
// 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

for a junior

Recall that [NonParallelizable] opts an item out and that the worker count defaults to the processor count, with a minimum of two.

for a middle

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.

for a senior

Size workers for the suite's real bottleneck, and replace blanket [NonParallelizable] markers with isolated resources where the run time matters.

for a principal

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