[SeanKilleen]

Closes #272.

What this adds

A Running Tests in Parallel topic page under Writing Tests, in the same style as Flaky and Slow Tests: question-shaped sections, a few sentences each, executable snippets. It answers the questions that came up repeatedly in nunit/nunit discussions (listed in #272):

• Turning parallel execution on, and what Fixtures vs Children mean at assembly level (described, not recommended, per @CharliePoole's note in the issue)
• Tests that only fail when run in parallel: fixture instance state, static state, external resources, and the InstancePerTestCase pattern (the Selenium static-driver case)
• Running fixtures in parallel while each fixture's tests run in order
• Running the cases of one parameterized test in parallel
• Keeping a group of fixtures apart from the rest, and what NUnit cannot do (namespace groups in parallel with serial fixtures inside)
• Limiting parallelism for one test with a SemaphoreSlim
• Why a parallel run can be slower, and that assembly-level parallelism is the runner's job (MaxCpuCount), with a pointer to AssemblySelectLimit

The page is linked from the Writing Tests TOC, the home page (the "Running tests in parallel" popular link now goes here instead of to the technical note, plus a card entry), and from the Parallelizable, NonParallelizable and LevelOfParallelism reference pages. Those reference pages also now link to the Framework Parallel Test Execution note, which nothing outside Technical Notes linked before.

Corrections to existing pages

Verified against NUnit 5.0.0 source and a timing experiment:

• parallelizable.md: the ParallelScope table listed All as valid on methods. All is Self | Children, and Children is rejected on a non-parameterized test method (May not specify ParallelScope.Children on a non-parameterized test method). It is valid on a parameterized one, where it runs the cases in parallel. Table and notes updated.
• Framework-Parallel-Test-Execution.md, case 4: claimed a [Parallelizable] SetUpFixture with [NonParallelizable] fixtures runs as a group in parallel with other groups. It does not. IsolateQueues is only called from the non-parallel worker, so every non-parallel fixture in the assembly queues on that single worker and runs one at a time after the parallel shift. In the experiment (two namespaces, each with a parallel SetUpFixture and two non-parallel fixtures) all four fixtures ran sequentially on one thread. Case 3 (non-parallel SetUpFixture, parallel fixtures inside) works as described. This is what @OsirisTerje saw in Tests in parallel fixtures not running in parallel per namespace nunit#4679 when the console runner also did not run the namespaces in parallel. The case text now describes the real behaviour and points to case 3.

Snippets

ParallelTestsGuideExamples.cs holds the six page examples plus ParallelScopeVerification, which is not referenced from the docs. It builds a test method with NUnitTestCaseBuilder and a parameterized one with DefaultTestCaseBuilder and asserts the run states and skip reason above, so the claims stay checked.

Checks

• dotnet test on Snippets.NUnit: 631 passed, 0 failed
• markdownlint-cli2 and cspell: clean
• docfx docs/docfx.json: builds, all xrefs resolve (only the usual missing-API warnings in a checkout without code-output)

🤖 Generated with Claude Code

[github-actions]

📖 Docs preview removed because this PR was closed.

[Copilot]

🟡 Changes recommended

The guide needs corrections to runner-specific concurrency advice, parallel opt-in wording, and the distinction between parameterless and non-parameterized tests.

3 open issues

• Clarify fixture parallelization versus test code thread safety · New
• Describe restriction as non-parameterized tests, not argument count · New
• Distinguish runner-specific settings for parallel test modules · New

What changed in this PR

Adds a practical parallel-testing guide to NUnit’s documentation, addressing shared state, execution scopes, fixture grouping, and concurrency limits.

Changes:

• Adds six executable examples and scope-validation tests.
• Links the guide from the home page, Writing Tests navigation, and attribute references.
• Updates scope-validity documentation and SetUpFixture scheduling explanations.

File	Description
docs/​snippets/​Snippets.NUnit/​ParallelTestsGuideExamples.cs	Adds guide examples and scope-validation tests.
docs/​index.md	Links the new guide from popular topics and the Writing Tests card.
docs/​articles/​nunit/​writing-tests/​toc.yml	Adds the guide to navigation.
docs/​articles/​nunit/​writing-tests/​parallel-tests.md	Introduces practical parallel-testing guidance.
docs/​articles/​nunit/​writing-tests/​attributes/​parallelizable.md	Updates valid scopes and adds guide links.
docs/​articles/​nunit/​writing-tests/​attributes/​nonparallelizable.md	Links practical and technical parallelism guidance.
docs/​articles/​nunit/​writing-tests/​attributes/​levelofparallelism.md	Adds per-test throttling guidance and related links.
docs/​articles/​nunit/​technical-notes/​usage/​Framework-Parallel-Test-Execution.md	Revises scope and fixture-group scheduling explanations.

_{Review effort: Balanced}

[manfred-brands]

Nice document.
I had one question that could use clarification.

[manfred-brands]

Would ParallelScope.Children work to allow running the test cases in parallel but not with other tests concurrently.

[CharliePoole]

@manfred-brands I think it should, barring bugs. Might be good to try both as parameterized test suites have been a source of many of them in the past.

[SeanKilleen]

@manfred-brands Yes, and it turns out Children and All are identical on a test method. I took @CharliePoole's advice and tried both, with a [TestCase] method next to two plain tests in the same fixture, under two configurations:

• Fixture not parallel (no assembly setting): with either scope, the three cases overlapped each other and nothing else, not even the sibling tests in the same fixture.
• Fixture parallel ([assembly: Parallelizable(ParallelScope.Fixtures)]): with either scope, the cases overlapped each other, the sibling tests, and other fixtures.

The scheduler explains it: GetExecutionStrategy returns Direct for any TestSuite that isn't a fixture, which includes a ParameterizedMethodSuite, before it ever checks Self. So the suite always runs on the fixture's thread, and the only thing the attribute contributes is Children in the context for the cases, which sends them to the parallel queue. Whether they overlap anything else is decided by the fixture, not by the method's scope.

So the pattern you describe is a non-parallel fixture with Children (or All) on the method. I've updated the section to say that (40a3ee2), switched the snippet to Children since it says what it does, and added a sentence to the technical note's ParallelScope list so the why is recorded in the "how it works" place.

[manfred-brands]

Thanks @SeanKilleen for investigating and clarifying my question.