Add How to Develop and Fix Bugs in NUnit, for the framework and the adapter by OsirisTerje · Pull Request #1310 · nunit/docs

OsirisTerje · 2026-10-26T20:01:54Z

New Developer Info pages on how we fix bugs:

How to Develop and Fix Bugs in NUnit (Developing-NUnit.md): the common workflow, the issues repositories (nunit.issues and nunit3-vs-adapter.issues), what a repro folder contains, marker files and run scripts, running the repros with IssueRunner, and testing an unreleased package from a local feed.
Developing the Framework: build targets, and fixing a bug with a repro in nunit.issues.
Developing the Adapter: build targets, the adapter's dump files, checking filters from the command line, and checking Visual Studio Test Explorer with te-dump (full session and single test runs).

Also:

The Developer Info toc is grouped into The Teams, Working Together (issue tracking, contributions, the new pages), Code (coding standards, XML documentation, specifications) and Packaging (the packaging pages under the Packaging page).
The Team Practices page is dropped: it only linked to pages the toc and the Packaging page already list. Team-Practices.html redirects to The Teams, and classic.md links to The Teams and the new page instead.
The landing page's Developer info box links to the new page instead of Team practices, so the box keeps its size.
Contributions links to the new page.
repros added to cSpell.json.

markdownlint and cspell pass locally; I could not run DocFX here.

…dapter A common page on reproducing a bug in the issues repositories, running the repros with IssueRunner and testing an unreleased package, with one page for the framework and one for the adapter. The adapter page covers the dump files, checking filters from the command line, and te-dump for Test Explorer. Merge The Teams into Team Practices, so the landing page keeps its size; The-Teams.html redirects there. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Team Practices only linked to pages the Developer Info toc and the Packaging page already list. The toc now has the sections Working Together, Code and Packaging, The Teams is the team page again, and Team-Practices.html redirects to it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-actions · 2026-10-26T20:05:06Z

📖 Docs preview: https://pr-1310.nunit-docs.pages.dev

Built from bb46410. This link always shows the latest build for this PR; the build for this exact commit is at https://c584af1d.nunit-docs.pages.dev.

Previews are hosted on Cloudflare Pages, are not indexed by search engines, and are removed when the PR is closed. They omit the archived NUnit 2.x documentation (the /2.x/ pages), which never changes; use the live site for those.

Copilot

🟡 Changes recommended

The guides need corrections to package-update instructions, IssueRunner behavior, and adapter-result interpretation to avoid misleading contributors.

4 open issues

What changed in this PR

Adds contributor guides for reproducing, fixing, and verifying bugs in the NUnit framework and adapter, integrated into the existing developer documentation.

Changes:

Documents the shared bug-fixing workflow, IssueRunner, and local package testing.
Adds framework build guidance and adapter diagnostics, including Test Explorer checks.
Consolidates teams and practices documentation and updates navigation.

File	Description
docs/index.md	Links to the new workflow and consolidated team page.
docs/articles/nunit/release-notes/framework.md	Updates the team membership link.
docs/articles/developer-info/toc.yml	Adds the workflow and project-specific guides.
docs/articles/developer-info/The-Teams.md	Redirects to Teams and Practices.
docs/articles/developer-info/Team-Practices.md	Incorporates team information and links to the workflow.
docs/articles/developer-info/Developing-the-Framework.md	Documents framework builds and bug verification.
docs/articles/developer-info/Developing-the-Adapter.md	Documents adapter builds and diagnostic tools.
docs/articles/developer-info/Developing-NUnit.md	Describes repros, IssueRunner, and local package testing.
docs/articles/developer-info/Contributions.md	Links to the bug-fixing guide.
cSpell.json	Adds “repros” to the dictionary.

_{Review effort: Balanced}

…te NUnit for framework fixes, and read the execution dump carefully Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…EXPECT comments are information Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

manfred-brands

@OsirisTerje Lots of new information.

Some questions, comments.

manfred-brands · 2026-10-26T23:31:48Z

+
+* Use the code from the issue where you can, and add a comment that explains what the bug is.
+* Use the current target framework and package versions, unless the bug needs older ones.
+* Always reference `Microsoft.NET.Test.Sdk` and `coverlet.collector`, as a real test project does.


coverlet.collector is a 3rd party coverage tool. It should not be relevant for an issue.

At work we use the .NET built-in coverage (dotnet test --collect:"Code Coverage;Format=cobertura")

coverlet.collector is part of the dotnet nunit template. I would assume most of the users use this to create a new nunit project, either from dotnet test or from VS, in both cases they will get the coverlet.collector.

Line 37 should be rewritten to state one should use the dotnet nunit template.

The latter is ok, but how come we say what coverage tool users should use?
It might predate dotnet's built-in support.

Getting full coverage of the SUT is a separate issue.

I'm deleting that now. They can use whatever they like, right?

manfred-brands · 2026-10-26T23:50:19Z

+Update the repro to the new package with [dotnet-outdated](https://github.com/dotnet-outdated/dotnet-outdated),
+instead of editing the version by hand. `-inc` updates the packages whose names contain the text, and `-exc` leaves
+out the packages whose names contain the text:
+
+```cmd
+REM An adapter fix
+dotnet outdated -u -pre Always -inc NUnit3TestAdapter
+
+REM A framework fix: the NUnit package, not the adapter or the analyzers
+dotnet outdated -u -pre Always -inc NUnit -exc NUnit3TestAdapter -exc NUnit.Analyzers
+```


This is built-in in dotnet package update

I prefer commands that do not require installing tools unless they really add to it.

REM An adapter fix dotnet package update NUnit3TestAdapter REM A framework fix: dotnet package update NUnit

dotnet outdated is doing more, and is one of the most used and recommended tools. It is first in SDK 10 that package update can do full csprojs. I trust outdated more than package update.
It also do:

Automatic upgrades limited to the current major or minor version.

Prompts to approve individual updates.

Package inclusion/exclusion filters.

Ignoring versions released within the last few days.

And it is less to write.

I can make it less authoritative, it sounds a bit too harsh now perhaps.

"Ensure you have updated all packages" and "We find it easiest to use a tool for this,
e.g. dotnet package update --project MySolution.slnx" or use 3rd party tool dotnet outdated -u at solution root.

I like outdated though, since it's less to write

More the what, less the how, but suggestions are ok.

manfred-brands · 2026-10-26T23:59:10Z

+`nugetc add myget` adds the NUnit MyGet feed, `https://www.myget.org/F/nunit/api/v3/index.json`.
+`nugetc remove local`, `disable local` and `enable local` change the file again, and `nugetc reset` sets it back to
+nuget.org only.


There is some functionality in the standard dotnet nuget

dotnet new nuget.config dotnet nuget add source c:\nuget --name local dotnet nuget remove source local dotnet nuget disable source local

But it does know about myget

Yeah I know, but I am lazy and I don't remember all the commands, which is why nugetc. And, I can add sources to it that it remembers, so I type less.

manfred-brands · 2026-10-26T23:59:30Z

+| Marker file                                     | Optional. Says what kind of repro it is, see below.                       |
+| `issue_metadata.json`, `issue_initialstate.json`, `issue_results.json` | Written by IssueRunner, see below. |
+
+The `issue_*.json` files are information, and you don't need to make them: the issue's state, milestone and labels


Thanks. First time I heard of this.

I actually dont use it so much anymore, but keeps it. Now I use Claude to do it for me - that is, run the repros. It's actually faster, but I do consume more tokens.
What is nice though is to have it run on the latest package, and warn if anything is broken, a good regression testing. Was hit by that recently with the adapter, and approving an external PR without checking absolutely everything.

manfred-brands · 2026-10-27T00:04:12Z

+1. Make the repro in [nunit.issues](https://github.com/nunit/nunit.issues): a folder `Issue<number>` with a
+   `readme.md` that links to the issue, and a project that builds and runs. Link the folder from the issue.
+2. Add a failing test to the framework's test projects that shows the bug, then fix the code. Run
+   `build --target=Test`: the framework targets several frameworks, and a fix can behave differently on each.
+3. Run `build` and `build --target=Package`, and copy the `NUnit` package from `package\` to your local feed.
+4. Update the repro to that package, see [Testing an unreleased package](xref:developingnunit#testing-an-unreleased-package),
+   and check that the bug is gone. The repro runs through the NUnit3 VS Adapter, so a bug that only shows in Visual
+   Studio can be checked there too, see [Checking Test Explorer with te-dump](Developing-the-Adapter.md#checking-test-explorer-with-te-dump).


For clear items, I only do 2. It is TDD but only in the framework.
Dictating all 4 steps is a lot of extra work.

I think I agree with @manfred-brands in that "it depends".

1 is helpful for community contributions of issue reproductions without a fix
2 is helpful when actually developing a fix
3+4 can be helpful if fixing an issue that just be verified by a consumer (ex: framework/console or framework/adapter interaction). It's rare that I require 3+4, but I think it could also be very challenging for a community member to figure out that workflow themselves when it is needed.

I wonder if splitting up the flow by scenario could help?

I do 1 for all external issues, and also many of the internal issues.
I try to do 2 for the cases, but sometimes I need to do the acceptance test instead.

The adapter is hard to work with, since it sits between the testhost, and the engine/framework, and now also the MTP platform. And the testhost is driven by the test explorer, which is an annoying piece of work. The te-dump was a saving grace there, since Claude can use it. Otherwise Claude can't run VS, and can't read anything from the TE.

3 and 4 is only needed when you have done 1, so...
I do this most of the times. I don't trust the unit tests alone.

But, yes, splitting by scenario is a good idea.

Copilot AI balanced review requested due to automatic review settings October 26, 2026 20:01

Copilot started reviewing on behalf of OsirisTerje October 26, 2026 20:02

View session

Copilot AI reviewed Oct 26, 2026

View reviewed changes

Comment thread docs/articles/developer-info/Developing-NUnit.md Outdated

Comment thread docs/articles/developer-info/Developing-NUnit.md Outdated

Comment thread docs/articles/developer-info/Developing-NUnit.md Outdated

Comment thread docs/articles/developer-info/Developing-the-Adapter.md Outdated

OsirisTerje and others added 4 commits October 26, 2026 21:08

Describe what IssueRunner does with markers and EXPECT comments, upda…

37fddf4

…te NUnit for framework fixes, and read the execution dump carefully Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Lead with using a single repro; IssueRunner is optional, markers and …

351ae2d

…EXPECT comments are information Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Use the current IssueRunner scope values

bee36c4

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Move IssueRunner to the end, and show nugetc for the local feed

7ccff0f

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

manfred-brands reviewed Oct 27, 2026

View reviewed changes

Updated developing-nunit

bb46410

Conversation

OsirisTerje commented Oct 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

manfred-brands left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

OsirisTerje Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

OsirisTerje commented Oct 26, 2026 •

edited

Loading

github-actions Bot commented Oct 26, 2026 •

edited

Loading

OsirisTerje Oct 27, 2026 •

edited

Loading