CLI reference
Every command, option and environment variable, with what it does, its default and an example. Run td --help for the short version.
td affected [options] Print the projects and tests a change affects
td test [options] [-- <args>] Run only the tests a change affects
td record [options] [-- <args>] Run all tests with coverage and store the map
td audit [options] [-- <args>] Break your code on purpose and check the selection
td --version Print the version (include it in a bug report)
Options for every analysis
These work with affected, test, record and audit; audit always compares with HEAD, so --base does not apply to it.
--base <ref>
The git ref to compare with. TestDetta compares your working tree with the merge base of HEAD and this ref, so commits that landed on the base branch after you branched off are not counted as your changes. Default: origin/main.
td test --base origin/develop
td affected --base HEAD~3 # the last three commits and anything uncommitted
--repo <path>
Any path inside the repository to analyse. Default: the current directory.
td affected --repo ../shop
-v, --verbose and --log-level <level>
Logs go to stderr, so stdout stays machine readable. -v turns on debug logs, which explain every decision: why a project is affected, which member a test class ran, which name a trace followed. --log-level picks any of trace, debug, information, warning (default), error, critical or none; trace adds raw git output.
td affected -v 2> testdetta-debug.log
td test --log-level information
--color <when> and --theme <name>
The text output is laid out as tables and coloured where someone reads it: in a terminal and in a GitHub Actions log. auto (default) leaves files and pipes plain and follows NO_COLOR and FORCE_COLOR; always and never decide outright. --format json is never coloured. --theme picks default, colorblind (blue and yellow instead of green and red) or mono (bold and faint only); TESTDETTA_THEME sets it for every run.
td test --theme colorblind
td affected --color never > affected.txt
--max-map-age <n>
Use a coverage map recorded up to n first-parent commits before the merge base when there is none at the merge base itself. Changes made in between are bridged: classes that ran any member changed since the map and able to reach your change are selected too. 0 uses only a map recorded at the merge base. Default: 50. See How it decides.
td test --max-map-age 20
--drift-fallback <all|name>
What to do when the changes since an older map include something members cannot describe: a build file, configuration, a global using. all (default) runs the affected test projects completely; name decides them by name, which is faster but blind to calls wired by configuration or reflection.
td test --drift-fallback name
--non-code-files <readers|project>
What a changed file in a project folder that is not code runs, such as README.md, CHANGELOG.md or a JSON file. readers (default) runs only the test classes the coverage map saw read it, when the build neither compiles, embeds, copies nor hands it to a tool; a file the build uses, and a test project whose map cannot vouch for every file its tests read, still run completely. project runs the file's project and every project that depends on it completely, whatever the file is. What runs everything explains what the default relies on.
td test --non-code-files project
--not-build-inputs <patterns>
Non-code files your build does not use, as repository-relative patterns separated by ;; the option can be given more than once. Like documentation files (README, CHANGELOG, LICENSE, CONTRIBUTING, SECURITY, CODE_OF_CONDUCT, CLAUDE.md, AGENTS.md and the like), they count as build inputs only when MSBuild builds, embeds or copies them or a target in your MSBuild files names them, never because an item pattern could include them. A test that reads one still runs, and the output lists such changed files. What runs everything explains the rule.
td test --not-build-inputs "docs/**;samples/**/*.json"
--maps-dir <dir>
Keep coverage maps outside the repository, one folder per commit. record saves to <dir>/<commit>/; affected and test restore the newest one within --max-map-age. Use it on CI systems other than GitHub Actions, with a shared disk or synced object storage. Default: maps live in .testdetta/coverage in the repository.
td record --maps-dir /srv/testdetta-maps/shop
td test --base origin/main --maps-dir /srv/testdetta-maps/shop
td affected
Prints what a change affects and why, without running tests. It reads the project files through MSBuild's evaluation, and builds only with --build.
--format <text|json|paths|commands>
| Format | Output | Use it for |
|---|---|---|
text (default) | Affected projects with the reason, then the test plan | Reading |
json | Every project and test class with its decision, evidence and time estimate | Scripts, dashboards |
paths | One affected test .csproj per line | Feeding another tool |
commands | One dotnet test command per test project, with its filter | Running the tests your own way |
td affected --format json > plan.json
td affected --format paths | xargs -n1 dotnet build
--tests-only
List only the affected test projects, not the production projects on the way.
--build
When a change reaches a source generator in the repository, build the test projects that use it and compare what it generates with their coverage map, as td test always does. Without it, an existing build newer than the sources is read; with none, those test projects are listed as running completely.
td test
Builds and runs only the affected tests: a filter per test project when only some classes are affected, the whole project when all are or when a change cannot be narrowed, nothing when none is. Exit code 3 when any test fails. When a change reaches a source generator in the repository, the test projects that use it are built first, and only generated code that changed counts; a build that fails stops here with the compiler's errors.
--dry-run
Print the dotnet test commands instead of running them. A project whose global.json lives in a subfolder is printed as (cd src && dotnet test ...).
--summary-file <path>
Append a Markdown summary: each project's result, which classes ran and why, which were skipped, and the recorded test time saved. Point it at $GITHUB_STEP_SUMMARY in GitHub Actions; the action does this for you. See an example.
td test --summary-file "$GITHUB_STEP_SUMMARY"
--shadow
Shadow mode, for trying TestDetta without skipping anything. TestDetta itself makes no network call in it, and nothing is sent. Your builds restore packages as they always do, and the rerun on the base commit restores that commit's packages like any build. Every test your own -- arguments run, runs, and the exit code is that run's. When they name a solution (.sln, .slnx, .slnf), one project, a directory, or nothing (the one solution or project in the working directory), TestDetta runs exactly that one dotnet test command in your working directory, adding only a test report per project: --logger trx under VSTest, unless you name a TRX logger yourself, or the testing platform's report option. Your results directory, loggers and the files your run writes stay as they are: TestDetta reads the reports where they land and copies them, and deletes only the reports it asked for itself (when you name no TRX logger or report option of your own) once it has read them. Otherwise, for example when there is no single solution to run or two test projects build assemblies of the same name, each test project your command runs runs on its own, one after another, from the same directory, and the report says why. When the test projects your command runs cannot be told, every test project under its directory runs, and the report says that too.
If TestDetta fails before the tests run, your command runs as given without it; if it fails afterwards, the exit code is still that run's; either way the report says why it has no shadow result. Afterwards TestDetta compares the run with what it would have selected, test by test, and reruns each failed class it would have left out: alone with the change; if it passes alone, with the other classes of its project as in the full run (passing there makes it flaky; failing again makes it order-dependent); then the same way on the base commit, in a separate checkout. If every test that fails with the change fails there too, the change did not break it; if one passes there, it is a miss. A class that cannot be rerun counts as a miss until checked. The reruns write their reports only into TestDetta's own temporary folder, and can make the job longer, at most by the classification budget. Ctrl+C or a cancelled job stops the tests and removes that folder and the base checkout.
Nothing about the selection is shown before the full run has finished, so your tests' output comes first. The report then holds every decision: the classes that ran in this job are compared with the selection, a class your filter left out is listed with its decision but not compared, and the totals count the compared classes. The report gives the verdict first, with the measured time of the whole run, then how the run was made, every class's decision and outcome, the measured time per project next to the part the selection would have run, and what you need to reproduce the result: the TestDetta version and its SHA-256, the commits, the coverage maps and their hashes, and the same td test --shadow command.
Limits: reports are found under the repository and in your results directory, so a results directory set outside the repository in run settings is not read. The base checkout lives in a temporary folder outside the repository, so files above the repository root (a Directory.Build.props, global.json or NuGet.config in a parent folder) are not seen there; a class whose base rerun cannot build is reported as not classified. A test project on the testing platform takes its report option according to its build output (an option it does not know would fail its run, so none is guessed from package references): when it was not built before the run, it runs without a report, and the report names it with "no test report: the project was not built before the run", so its failures cannot be compared. Build first and pass --no-build, as below.
dotnet build MySolution.sln -c Release
td test --shadow --summary-file "$GITHUB_STEP_SUMMARY" -- MySolution.sln -c Release --no-build
--shadow-no-classify
Do not rerun the failed classes the selection left out. They are then reported as not classified.
--shadow-report <path>
Where the JSON report goes. Default: .testdetta/testdetta-shadow.json in the repository.
--shadow-analysis-timeout <time>
How long TestDetta's analysis before the tests may take. Default: 10m. Past it the analysis is stopped, every test still runs, and the report says why it has no shadow result.
--shadow-rerun-timeout <time>, --shadow-rerun-idle-timeout <time>
How long one rerun with the change may take, and how long its processes may use almost no CPU before it is stopped as stuck. Defaults: 15m and 5m. The classes of a rerun that is stopped are reported as not classified.
--shadow-base-timeout <time>, --shadow-base-idle-timeout <time>
The same for the rerun on the base commit, which restores and builds in its checkout first. Defaults: 30m and 10m; the idle limit is longer because a restore waits on the network while the CPU is nearly still.
--shadow-classify-budget <time>
How long the whole classification may take: every rerun and the base checkout together. Default: 45m. A running rerun is stopped where the budget ends, and the failures not classified by then are reported as not classified, with the reason. The full run and the exit code are never affected. The report shows the limits used and how much of the budget was spent.
A <time> is 90s, 15m, 1h or 1h30m, at most 168h; a plain number means minutes; 0 or none means no limit. In the GitHub Action, the inputs of the same names (shadow-analysis-timeout, shadow-rerun-timeout, shadow-classify-budget and so on) set them.
td test --shadow --shadow-classify-budget 20m --shadow-base-timeout none
-- <dotnet test arguments>
Everything after -- is passed to every dotnet test call. Your own --filter is kept: TestDetta joins it with its class filter, so only the selected tests inside your filter run. xUnit v3 trait, method and namespace filters narrow the selection the same way. A filter the runner cannot join with a class filter (an xUnit v3 class or query filter, a TUnit tree-node filter) makes the project run completely under your filter. In shadow mode they are your own test command; see --shadow.
With -f <tfm> the run loads that framework's builds only, so a change compiled only for other frameworks (code under an #if those builds leave out) selects nothing, when the changed project and every project between it and your test projects target that framework.
td test -- -c Release --logger trx
td test -- --no-restore
td test -- --filter "Category!=Integration"
td record
Runs every test with coverage and writes one map per test project to .testdetta/coverage (or --maps-dir). Run it on your default branch; it is also that branch's full test run. Exit code 3 when tests fail; the maps are still written, and the failing classes run whenever their project is affected.
-c, --configuration <name>
Build configuration. Default: Debug.
-f, --framework <tfm>
Target framework to record in a multi-targeted test project. Default: the project's first target framework that runs on this machine (.NET Framework only on Windows).
td record -f net10.0
--project <path>
Record only this test project, relative to the repository root; repeat it for several. Leave out projects that cannot run in CI, such as integration tests that need a database; they are then decided by name.
td record --project tests/Shop.Tests/Shop.Tests.csproj --project tests/Api.Tests/Api.Tests.csproj
-- <args>
Your own dotnet test arguments, the ones your test job uses: recording runs under their filter and run settings, combined with its own, and passes their other options as given. A filter and run settings set in your project files are kept as well. See Your test configuration.
td record -- --filter "Category!=Integration" --settings ci.runsettings
--parallel <n>
Spread each project's test classes over n test processes to record faster. Each process still runs its tests one at a time. Your suite must tolerate several test processes at once (no fixed ports or shared files). Default: 1.
--no-build
Record the output of an earlier build with the same configuration instead of building again.
dotnet build -c Release
td record -c Release --no-build
td audit
Tests TestDetta's selection on your own code, the way we test it on open-source repositories. It breaks members of your code one at a time with IL mutants (a method throws, returns a default value, takes the other branch, or a field starts with another value), runs every test project that can load the change completely, and checks that the selection TestDetta makes for that change, from your coverage maps exactly as td test makes it, contains every test class that failed. Every doubt counts against TestDetta: a class the selection left out runs again alone with the change and alone without it before it counts as a miss, and a class it ran counts as caught only after the same two runs. A test run that crashes or hangs with the change runs again without it: when the part the selection left out completes only without the change, and crashes or hangs again when repeated with it, that is a miss (a crash that does not come back leaves the change inconclusive); a crash in the part it ran counts as caught only when it comes back. TestDetta itself makes no network call; the builds and test runs it starts in the copy restore packages as your own do.
Your sources and build output are never written. TestDetta copies the working tree into a work folder (a copy-on-write clone where the file system has one), builds and tests there, and deletes the folder at the end, also after Ctrl+C, a timeout or an error; a folder left by a run that was killed is deleted by the next one. Before anything builds there, it asks MSBuild where every project writes and does not start when any of it lies outside the copy, such as an absolute output path. The working tree must have no uncommitted changes, because every change is compared with HEAD; if the repository moves to another commit or gets changes while the audit runs, it stops with an error. A test project whose own filter cannot be joined with a class filter (an xUnit v3 class or query filter, a TUnit tree-node filter) is not audited, and the report says why; so are projects that need the full MSBuild (legacy, non-SDK projects) and projects that do not build in the copy, write no test report, or do not complete in the run without changes. Members of projects used as a source generator or analyzer are left out of the sample, and the report counts them. Testing-platform projects are built in the copy before that run, which the budget pays for. Members are taken in a fixed order, from a hash of the member and the seed, over all members alike: whether a map says some test ran a member plays no part in the choice.
The result gives the 95% upper bound of the miss rate, rounded up, and the number of changes it rests on; then the changes whose runs could not tell (inconclusive) or that a cancellation or an error cut short (stopped), and the bound if every one of them were a miss:
On your code: 112 changes, 103 broke tests, 0 missed (95% upper bound 2.9%, n = 103); 2 inconclusive, 0 stopped (worst case, counting them as misses: 95% upper bound 5.9%, n = 105); target of 100 reached.
graduation evidence: no: worst case 5.9% > 3.0% because 2 inconclusive and 0 stopped are counted as misses
The second line says whether the run is the evidence shadow mode's graduation asks for: at least 100 changes that broke tests, none missed, and the worst-case bound at most 3.0% as shown. If not, it names every condition the run misses ("not yet: 87 changes broke tests, 100 needed", "no: 1 missed"). A run with --member never counts, and --target-broken does not change the criterion.
The report (.testdetta/testdetta-audit.json, and the job summary with --summary-file) lists every change and its outcome. For a miss it gives the class, the decision chain that left it out (what TestDetta saw change, how the test project and the class were decided and why, the map's commit), the edit to make by hand to see the same decision, and the command that repeats that change alone. Exit code 3 when there is a miss.
td audit --summary-file "$GITHUB_STEP_SUMMARY" -- -c Release
--target-broken <n>
Stop once n changes broke tests. Default: 100; with no miss and no inconclusive or stopped change, that puts the 95% upper bound at 3.0% as shown (2.95%, rounded up).
--max-mutants <n>
Stop after n changes ran tests. Default: no limit.
--budget <time>
Start no change after this long. A change still running then finishes within its own time limits and counts, so the audit can take longer by that change, by one change per worker with --parallel, and a change makes several runs, each allowed up to five times its project's run without changes: stopping it half-way would drop the slowest changes, misses most often. When it ends after the budget, the report says by how much and which changes ran on; leave that room under a CI job's time limit. The <time> syntax of the shadow limits. Default: 4h.
--parallel <n>
Changes tested at once, each in its own copy of the working tree. Each one runs test hosts, so memory use grows with n. Default: 1.
--seed <n>, --kinds <list>, --member <Type.Member>
The seed of the order (default 1); the kinds of change, throw, return-default, flip-branch, field-value or all (the default); and, to repeat a change from a report, the member it broke (repeat the option for several).
--report <path>, --work-dir <dir>
Where the JSON report goes (default: .testdetta/testdetta-audit.json) and where the work folder with the copy goes (default: /tmp, the temp folder on Windows). Keep the work folder on the repository's disk, so the copy can be a clone.
td audit --target-broken 150 --budget 6h --work-dir "$RUNNER_TEMP"
Environment variables
| Variable | What it does |
|---|---|
TESTDETTA_THEME | The colour theme for every run: default, colorblind or mono. --theme takes precedence. See --theme. |
NO_COLOR | Any value turns colour off under --color auto. |
FORCE_COLOR | Under --color auto, any value but 0 turns colour on, also when the output goes to a file or a pipe; 0 turns it off. NO_COLOR wins over it. |
TESTDETTA_MSBUILD | The full MSBuild executable that builds legacy (non-SDK) projects, when the one TestDetta finds is not the one to use. See Compatibility. |
The license variables of earlier versions (TESTDETTA_LICENSE, TESTDETTA_LICENSE_FILE, TESTDETTA_LICENSE_SCOPE, TESTDETTA_LICENSE_REFRESH) are ignored; see License.
Exit codes
| Code | Meaning |
|---|---|
0 | Success, including "no tests needed". |
1 | The analysis failed: git, the file system or a project file; for record also when no test project could be recorded; for audit also when it could not run or was cancelled; for test --shadow when it was cancelled before the tests ran. |
2 | Invalid command line. |
3 | Tests failed (test, the full run of test --shadow, and record); a miss (audit). |