Getting started

TestDetta compares your branch with its base, works out which test projects and which test classes can observe the change, and runs just those. When it cannot be sure, it runs more, never less; what it cannot see is listed under Limitations.

Requirements

Quick start

GitHub Actions

The GitHub Action fetches the TestDetta package it pins from nuget.org and checks its SHA-512 before running it; there is nothing to install. Add this workflow, for example as .github/workflows/tests.yml: on pushes to your default branch it records a coverage map, on pull requests it runs only the affected tests.

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read
  actions: read # lets pull requests find the newest coverage map in the Actions cache

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7 # pin to a commit SHA
        with:
          fetch-depth: 0 # TestDetta compares with the merge base
          persist-credentials: false

      - uses: actions/setup-dotnet@v6 # pin to a commit SHA
        with:
          global-json-file: global.json # without a global.json: dotnet-version: 10.0.x

      - if: github.event_name == 'push'
        uses: TestDetta/action@8750db18099a2af0436788d20dc591e94b550c07 # v0.5.2
        with:
          mode: record

      - if: github.event_name == 'pull_request'
        uses: TestDetta/action@8750db18099a2af0436788d20dc591e94b550c07 # v0.5.2
        with:
          mode: test

Merge the workflow first: the first push to the default branch records the first map. Until then, and for pull requests whose merge base is older than the first map, mode: test selects by name only, which is safe but selects more; such a pull request becomes precise once it merges or rebases onto the default branch. The permissions, every input and the other modes are in GitHub Actions.

Other CI systems

GitLab CI, Jenkins, Azure DevOps, Bitbucket and on-premises setups run the same two commands, with a folder of per-commit coverage maps (--maps-dir) kept on a shared disk or in object storage. Install TestDetta as a .NET tool:

dotnet tool install --global TestDetta --version 0.5.2

Pipelines for each system are in Other CI systems.

No license key

TestDetta is free and open source under the Apache License 2.0, for public and private repositories alike, on every CI and on developer machines. There is no license key to pass, no secret to set and no account to create. See License; the source is on GitHub.

First commands

Run these from anywhere inside your repository. --base defaults to origin/main.

# On main, the commit your branches start from: run every test with coverage and
# write one map per test project to .testdetta/coverage. A map recorded on a
# commit of your feature branch is not used.
td record

# What does my branch affect, and why?
td affected --base origin/main

# Run only the affected tests (add --dry-run to print the dotnet test commands)
td test --base origin/main

Without a coverage map, td test still works: it decides by name only, which is safe but selects more. Once td record has run at the base of your branch, or up to 50 commits before it, selection becomes precise. Maps recorded by TestDetta 0.1.x are of an older format and are ignored with the warning "record the maps again" until you record them again; see Limitations.

Add .testdetta/ to your .gitignore. It holds coverage maps and caches, never anything to commit.

Commands

CommandWhat it does
td affected [--format text|json|paths|commands] [--tests-only] [--build]Print what a change affects and why. --tests-only lists only affected test projects; --build builds the test projects that use a changed source generator, to compare what it generates.
td test [--dry-run] [--summary-file <path>] [-- <dotnet test args>]Run only the affected tests. --summary-file appends a Markdown summary, for example to $GITHUB_STEP_SUMMARY. Arguments after -- go to every dotnet test, for example -- -c Release.
td test --shadow [--shadow-no-classify] [--shadow-report <path>] [-- <dotnet test args>]Shadow mode: run every test your own dotnet test arguments run, and report what the selection would have left out, rerunning each failed class it would have left out to tell a miss from a flaky or pre-existing failure. The exit code is the full run's. Testing-platform projects need a build first and --no-build. See --shadow.
td record [--project <csproj>]... [-c <configuration>] [-f <tfm>] [--parallel <n>] [--no-build] [-- <dotnet test args>]Run all tests with coverage and write one map per test project to .testdetta/coverage. --parallel spreads each project's test classes over n test processes; --no-build records the output of an earlier build with the same configuration. Arguments after -- (your filter, settings) are kept while recording; see Your test configuration.
td audit [--target-broken <n>] [--max-mutants <n>] [--budget <time>] [--parallel <n>] [--member <Type.Member>]... [-- <dotnet test args>]Check the selection on your own code: break members one at a time in a copy of the working tree, run every test that can see each change, and report every failing class the selection left out. See td audit.

Shared options

OptionMeaning
--base <ref>Git ref to compare against. Default: origin/main.
--repo <path>Any path inside the repository. Default: the current directory.
--max-map-age <n>Use coverage maps recorded up to n commits before the merge base, bridging the changes in between. Default: 50; 0 uses only exact maps. See How it decides.
--maps-dir <dir>Coverage maps kept outside the repository, one folder per commit: record saves there, affected, test and audit restore the newest one within --max-map-age. For CI systems other than GitHub Actions.
--drift-fallback <all|name>When the changes since an older map include a build file, configuration or a global using: run the affected test projects completely (all, the default) or decide them by name (name).
--non-code-files <readers|project>What a changed file in a project folder that is not code (README.md, a JSON file) runs: readers (the default) runs only the test classes the coverage map saw read it, when the build does not use the file; project runs its project and every project depending on it completely. See --non-code-files.
--not-build-inputs <patterns>Non-code files your build does not use (docs/**;*.yaml): like documentation files, they count as build inputs only on an exact sign, never on a guess. See --not-build-inputs.
-v, --verboseWrite debug logs to stderr: every decision a user might question, with its reason.
--log-level <level>trace, debug, information, warning (default), error or none.
--color <when>auto (default: a terminal or a GitHub Actions log; NO_COLOR turns it off), always or never. JSON is never coloured.
--theme <name>default, colorblind (blue and yellow instead of green and red) or mono. Also TESTDETTA_THEME.

Logs go to stderr; stdout carries the command's output and stays machine readable.

Exit codes

CodeMeaning
0Success.
1The analysis failed (td audit: it could not run or was cancelled; td test --shadow: it was cancelled before the tests ran).
2Invalid command line.
3Tests failed (td test, the full run of td test --shadow, td record); a miss (td audit).