Running the tests

Running the test suite on your own machine, and running it in CI on GitHub's runners if you have write access to the repository. Why CI runs only when dispatched is on Branches and workflow.

Before you start

What you'll have

Every test project's results, either in your terminal or as a .trx file from a CI run.

What you need

• The .NET 10 SDK from the 10.0.4xx band. global.json pins 10.0.400 and takes the latest patch in that band.
• For CI runs: write access to NexusTomorrow/server and the GitHub CLI, signed in.

How it works

The tests use xUnit v3 on Microsoft Testing Platform, which global.json names as the test runner. That's why dotnet test takes the solution through --solution, and why options for the test framework itself go after a --. Each project under Tests/ builds to its own test application.

Run them locally

The whole suite

From the repository root:

dotnet test --solution Source/NexusTomorrow.slnx

One test class

Pass a filter through to the test applications:

dotnet test --solution Source/NexusTomorrow.slnx -- --filter-class "*Srp6*"

Tip

Filter to the class you're working on while you iterate, then run the whole suite once before you commit.

The checks CI runs besides the tests

CI also checks formatting and commit messages. To catch both before you push:

1. Build, then format the tree, and commit what it changes. The formatter needs the build first, because it loads the codec's source generator from the build output; without it, every generated member looks missing:

   dotnet build Source/NexusTomorrow.slnx
   dotnet format Source/NexusTomorrow.slnx

2. Read your commit messages since main, and check each one has a blank second line and a headline of 72 characters or fewer with no full stop:

   git log origin/main..HEAD --format="%h %s%n%b"

Run them in CI

On a pushed branch

1. Dispatch the workflow on the branch, with any filter as args:

   gh workflow run Tests --repo NexusTomorrow/server --ref bootstrap -f args="--filter-class *Srp6*"

   Leave args out to run everything.

2. Find the run it started:

   gh run list --repo NexusTomorrow/server --workflow Tests --branch bootstrap --limit 1

3. Watch it to the end:

   gh run watch <run id> --repo NexusTomorrow/server

4. Download the results. The workflow uploads them as test-results even when tests fail:

   gh run download <run id> --repo NexusTomorrow/server --name test-results

On work that isn't pushed yet

Push a throwaway copy, run it, and delete it afterwards:

1. Push your current commit as a wip/ branch:

   git push origin HEAD:wip/<topic>

2. Dispatch, watch and download as above, with --ref wip/<topic> and --branch wip/<topic>.

3. Delete the branch once you have the results:

   git push origin --delete wip/<topic>

Important

Never merge from a wip/ branch. It's a copy for one test run, and it's gone once the run is.

Troubleshooting

The SDK isn't found

global.json asks for the 10.0.4xx band. A 10.0.3xx SDK, or any earlier band, doesn't satisfy it. Install the latest 10.0.4xx SDK and run dotnet --list-sdks to check it's there. CI installs the same band; its runs so far resolve to 10.0.402.

The run fails before the test step

There are no test results to download, so read the log: gh run view <run id> --log-failed. The failing step says which check stopped it.

Step	Means	Fix
Commit messages	A commit since main has no blank second line, a headline over 72 characters, or a full stop at its end. The log names the commit	Reword it. A commit already on a shared branch can't be, so check before you push
Em dashes	A .cs or .md file holds an em dash. The log lists each line	Use a comma, a colon, parentheses or two sentences
Method words	A .cs or .md file says how a fact about the client was found. The log lists each line	State the fact as a fact, and leave out how it was found
Build	A compiler or analyser finding. Every warning is an error, style rules included, and a hot-path project also refuses its banned APIs	Fix it, or suppress the rule for that code with its reason, as CONTRIBUTING.md describes
Format	dotnet format would change something	Build, run dotnet format Source/NexusTomorrow.slnx, and commit the result

My pull request shows no checks

The workflow doesn't run on pull requests. A maintainer dispatches it on your branch, or on a copy of it.

Quick reference

To	Run
Format before committing	dotnet build Source/NexusTomorrow.slnx, then dotnet format Source/NexusTomorrow.slnx
Run everything locally	dotnet test --solution Source/NexusTomorrow.slnx
Run one class locally	dotnet test --solution Source/NexusTomorrow.slnx -- --filter-class "*Name*"
Dispatch CI	gh workflow run Tests --repo NexusTomorrow/server --ref <branch>
Watch a run	gh run watch <run id> --repo NexusTomorrow/server
Get the results	gh run download <run id> --repo NexusTomorrow/server --name test-results
Read a failed build	gh run view <run id> --repo NexusTomorrow/server --log-failed

Where the code lives

Piece	Path
The SDK band and the test runner	global.json
The CI workflow and its checks	.github/workflows/test.yml
Suppressing a rule with its reason	CONTRIBUTING.md