Command reference

Contents

Syntax

test-rerun [<path>] [options] [MSBuild arguments] [-- <inline run settings>]

<path> is passed to dotnet test unchanged: a project, a solution, a directory or a test .dll. Without it, dotnet test looks for a project or solution in the current directory. Only one path is accepted.

Run test-rerun --help to see the options of the installed version.

Rerun options

These options control the tool itself and are not passed to dotnet test.

Option Default Description
--rerunMaxAttempts <n> 3 Maximum number of reruns after the first run. With 3, dotnet test runs at most 4 times.
--rerunMaxFailedTests <n> -1 Do not rerun when more than n tests failed. -1 (or 0) means no limit.
--rerunFailedThreshold <percent> -1 Do not rerun when more than this percentage of the tests failed in the first run. Accepts decimals (12.5). -1 means no limit; 0 means never rerun.
--delay, -d <seconds> 0 Wait this many seconds before each rerun. Not applied when nothing is rerun.
--deleteReports off Delete the TRX files of every run at the end. Files from other loggers (for example JUnit) are kept.
--mergeCoverageFormat <format> — Merge the coverage files of all runs into one file: Coverage, Cobertura or Xml. Requires the dotnet-coverage tool. See Code coverage.
--loglevel <level> Verbose Output of the tool itself: Debug, Verbose, Information, Warning, Error. Debug also prints the dotnet test command lines. Any other value is an error.
--logTestResults off Print every test with ✓ or ✗ as soon as it finishes, with the error message and stack trace of failed tests. Does not depend on --verbosity, so --verbosity quiet --logTestResults gives short, live output. The tool adds its own logger to dotnet test (--logger dotnet-test-rerun-live and --test-adapter-path); if that logger reports nothing, the results are read from the TRX files after the run instead.
--logPassedTests off Add a console;verbosity=detailed logger so dotnet test prints each test as it passes. Ignored when --logTestResults is set. Can produce a lot of output.
--generateTestCommand off When tests still fail at the end, print a standalone dotnet test command that runs only those tests, to reproduce them without the tool. Nothing is printed when all tests pass. See Reproducing failed tests.

Options passed to dotnet test

These options mean the same as in dotnet test and are passed on every run.

Option Default Description
--filter <expression> — Run only the tests that match. On reruns it is combined with the failed tests: (your filter)&(failed tests).
--logger, -l <logger> trx Logger for test results. Repeat for several loggers. A trx logger is always added if none of yours is TRX, because the tool reads TRX files.
--results-directory, -r <dir> . Folder for results. Every run writes its TRX files here. See Results folder.
--settings, -s <file> — A .runsettings file.
--configuration, -c <name> — Build configuration, for example Release.
--framework, -f <tfm> — Target framework, for example net8.0.
--no-build off Do not build before testing. Implies --no-restore.
--no-restore off Do not restore before building.
--verbosity, -v <level> — Verbosity of dotnet test: Quiet, Minimal, Normal, Detailed, Diagnostic.
--blame off Run in blame mode, to find the test that crashes the test host.
--collect <name> — Enable a data collector, for example "XPlat Code Coverage" or "Code Coverage". Only one collector.
--environment, -e <NAME=value> — Set an environment variable for the test run. Repeat for several variables.

MSBuild arguments

Arguments that start with /p:, -p:, --property:, /property:, -property:, /m:, -m: or --maxCpuCount: (and /maxCpuCount:, -maxCpuCount:) are passed to dotnet test as they are:

test-rerun MyTests.csproj /p:CollectCoverage=true -m:1

Inline run settings

Everything after -- is passed to dotnet test as inline run settings. Put it at the end of the command:

test-rerun MyTests.csproj --rerunMaxAttempts 2 -- RunConfiguration.MaxCpuCount=1 NUnit.NumberOfTestWorkers=1

Any other argument the tool does not recognise is also treated as an inline run setting. Check the spelling of options: a mistyped option does not fail, it is passed to dotnet test after --.

Exit codes

Code Meaning
0 All tests passed, on the first run or after reruns.
1 Tests still failed after the last rerun, reruns were skipped by --rerunMaxFailedTests / --rerunFailedThreshold, no TRX file was found, or dotnet test (or dotnet-coverage) failed for another reason, such as a build error.
130 The run was cancelled (Ctrl+C).

Examples

# Release build, built in a previous step
test-rerun MySolution.sln --configuration Release --no-build

# Only integration tests; wait 10 s before each rerun; give up if more than 15 fail
test-rerun IntegrationTests.csproj --filter "Category=Integration" --delay 10 --rerunMaxFailedTests 15

# Keep results in ./TestResults and print every test result
test-rerun MyTests.csproj --results-directory TestResults --logTestResults

# JUnit report for GitLab, plus the TRX the tool needs (added automatically)
test-rerun MyTests.csproj --logger "junit;LogFileName=junit.xml"

# Merged Cobertura coverage of all runs
test-rerun MyTests.csproj --collect "XPlat Code Coverage" --mergeCoverageFormat Cobertura

# Environment variables and a run settings file
test-rerun MyTests.csproj -e ASPNETCORE_ENVIRONMENT=Testing --settings ci.runsettings

Back to top

Copyright © 2023-2026 João Pereira. Distributed under the GNU General Public License v3.0.