Other CI systems
TestDetta works on any CI that runs .NET and git. Outside GitHub Actions, two commands and one folder do the job.
- On the default branch,
td record --maps-dir <maps>runs the whole suite once with coverage, and saves one coverage map per test project under<maps>/<commit>/. - On a pull or merge request,
td test --base origin/<target> --maps-dir <maps>restores the newest map at or before the merge base. It takes the nearest one within 50 first-parent commits (--max-map-age) and bridges the changes in between. Then it runs only the affected tests.
<maps> is an ordinary folder. Keep it wherever your CI can keep files between pipelines:
- a disk shared by the agents, common on-premises:
/srv/testdetta-maps/<repository>; - object storage (S3, Azure Blob, GCS, MinIO), synced before and after.
TestDetta itself never uses the network for maps.
What every setup needs
- Full git history. TestDetta compares with the merge base and walks history to find maps. Shallow clones cannot do either.
- The target branch fetched, so
origin/<target>exists. Fetch it with an explicit refspec,+refs/heads/<target>:refs/remotes/origin/<target>. CI clones often limit the remote's refspecs to the pipeline's own branch (GitLab's and Bitbucket's do), and thengit fetch origin <target>alone updates onlyFETCH_HEAD, andorigin/<target>stays missing. - Exit codes:
0success,1the analysis failed,2invalid command line,3tests failed. - Clean-up: maps of old commits are only needed for 50 commits. Delete older folders with a scheduled job or a storage lifecycle rule.
Installing
dotnet tool install --global TestDetta --version 0.5.2
export PATH="$PATH:$HOME/.dotnet/tools"
TestDetta runs on the .NET 10 SDK; your tests also need the SDK and runtimes they use today. Pin the version, as the GitHub Action pins its package. A global tool lands in ~/.dotnet/tools, which hosted runners and the .NET SDK container images do not put on PATH, so every example below adds it. Installing a version that is already there does nothing, so persistent agents can run the same lines.
GitLab CI
default:
image: mcr.microsoft.com/dotnet/sdk:10.0 # td runs on .NET 10; use an image that also has your tests' runtimes
before_script:
- dotnet tool install --global TestDetta --version 0.5.2
- export PATH="$PATH:$HOME/.dotnet/tools"
variables:
GIT_DEPTH: "0" # full history
TESTDETTA_MAPS: /srv/testdetta-maps/$CI_PROJECT_PATH # a disk the runners share; or sync with object storage
record-coverage:
stage: test
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
script:
- td record --maps-dir "$TESTDETTA_MAPS"
affected-tests:
stage: test
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
script:
- git fetch --no-tags origin "+refs/heads/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME:refs/remotes/origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
- td test --base "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" --maps-dir "$TESTDETTA_MAPS" --summary-file testdetta-summary.md
artifacts:
when: always
paths: [testdetta-summary.md]
Jenkins
A declarative multibranch pipeline:
pipeline {
agent any
environment {
TESTDETTA_MAPS = "/srv/testdetta-maps/${env.JOB_NAME.split('/')[0]}"
}
options { skipDefaultCheckout() }
stages {
stage('Checkout') {
steps {
checkout scmGit(branches: scm.branches, userRemoteConfigs: scm.userRemoteConfigs,
extensions: [cloneOption(shallow: false, depth: 0, noTags: true, reference: '')])
}
}
stage('Record coverage') {
when { branch 'main' }
steps {
sh '''
dotnet tool install --global TestDetta --version 0.5.2
export PATH="$PATH:$HOME/.dotnet/tools"
td record --maps-dir "$TESTDETTA_MAPS"
'''
}
}
stage('Affected tests') {
when { changeRequest() }
steps {
withCredentials([gitUsernamePassword(credentialsId: 'git-credentials')]) { // the credential your checkout uses
sh 'git fetch --no-tags origin "+refs/heads/$CHANGE_TARGET:refs/remotes/origin/$CHANGE_TARGET"'
}
sh '''
dotnet tool install --global TestDetta --version 0.5.2
export PATH="$PATH:$HOME/.dotnet/tools"
td test --base "origin/$CHANGE_TARGET" --maps-dir "$TESTDETTA_MAPS"
'''
}
}
}
}
The agent needs the .NET 10 SDK. The checkout's credentials are not kept for later steps, so on a private repository the git fetch runs inside withCredentials with the gitUsernamePassword binding of the Git plugin; name the credential your checkout uses.
Azure DevOps Pipelines
trigger: [main]
pr: [main]
variables:
TESTDETTA_MAPS: /srv/testdetta-maps/$(Build.Repository.Name) # a share the agents mount; or sync with object storage
steps:
- checkout: self
fetchDepth: 0
persistCredentials: true # lets the git fetch below reach a private repository
- task: UseDotNet@2
inputs:
version: 10.0.x # td runs on .NET 10; add the SDK your tests use, as in your own pipeline
- script: |
dotnet tool install --global TestDetta --version 0.5.2
echo "##vso[task.prependpath]$HOME/.dotnet/tools"
- script: td record --maps-dir "$(TESTDETTA_MAPS)"
condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
- script: |
target="${SYSTEM_PULLREQUEST_TARGETBRANCH#refs/heads/}"
git fetch --no-tags origin "+refs/heads/$target:refs/remotes/origin/$target"
td test --base "origin/$target" --maps-dir "$(TESTDETTA_MAPS)" --summary-file "$(Agent.TempDirectory)/testdetta.md"
echo "##vso[task.uploadsummary]$(Agent.TempDirectory)/testdetta.md"
condition: and(succeeded(), eq(variables['Build.Reason'], 'PullRequest'))
TESTDETTA_MAPS points to a share on self-hosted agents. On Microsoft-hosted agents, sync it with Azure Blob storage (see Object storage).
Windows agents and PowerShell
The examples above use a POSIX shell. On Windows agents (Azure DevOps, Jenkins, TeamCity or a pipeline of your own), use dist/ci/testdetta.ps1: copy it into your repository, for example as build/testdetta.ps1. It installs the pinned version into a folder of its own, fetches the full history when the clone is shallow (Azure DevOps clones shallowly by default), finds the pull request's target branch in the Azure DevOps, Jenkins, GitLab or Bitbucket environment and fetches it, and passes everything after -- to dotnet test. It works with Windows PowerShell 5.1 and PowerShell 7.
.\build\testdetta.ps1 -Mode record -MapsDir \\fileserver\testdetta-maps\shop -- -c Release # default branch
.\build\testdetta.ps1 -Mode shadow -MapsDir \\fileserver\testdetta-maps\shop -- -c Release # pull requests, while you evaluate
.\build\testdetta.ps1 -Mode test -MapsDir \\fileserver\testdetta-maps\shop -- -c Release # pull requests, afterwards
Ready-made pipelines: Azure DevOps on a Microsoft-hosted Windows agent, with the maps in a pipeline cache, and a Jenkins multibranch pipeline on a Windows agent, with the maps on a share. Both start pull requests in shadow mode: every test runs as today, and the report says what the selection would have left out.
Bitbucket Pipelines
image: mcr.microsoft.com/dotnet/sdk:10.0 # td runs on .NET 10; use an image that also has your tests' runtimes
clone:
depth: full
pipelines:
branches:
main:
- step:
script:
- dotnet tool install --global TestDetta --version 0.5.2
- export PATH="$PATH:$HOME/.dotnet/tools"
- td record --maps-dir maps
- ./sync-maps.sh upload maps # see "Object storage"
pull-requests:
'**':
- step:
script:
- dotnet tool install --global TestDetta --version 0.5.2
- export PATH="$PATH:$HOME/.dotnet/tools"
- git fetch --no-tags origin "+refs/heads/$BITBUCKET_PR_DESTINATION_BRANCH:refs/remotes/origin/$BITBUCKET_PR_DESTINATION_BRANCH"
- ./sync-maps.sh download maps "origin/$BITBUCKET_PR_DESTINATION_BRANCH"
- td test --base "origin/$BITBUCKET_PR_DESTINATION_BRANCH" --maps-dir maps
sync-maps.sh needs its storage tool, such as the AWS CLI, in the step's image.
Object storage instead of a shared disk
On hosted runners there is no shared disk. Upload the new folder after recording. Before testing, download only the folders that can be used: the merge base and up to 50 first-parent commits before it. Download them newest first, and stop at the first one that exists. An example for S3; any tool with cp and ls works the same way:
#!/usr/bin/env bash
# sync-maps.sh upload <maps> | after td record on the default branch
# sync-maps.sh download <maps> <base> | before td test on a pull request
set -euo pipefail
remote="s3://my-bucket/testdetta-maps/my-repository"
case "$1" in
upload)
aws s3 cp --recursive "$2/$(git rev-parse HEAD)" "$remote/$(git rev-parse HEAD)" ;;
download)
for sha in $(git rev-list --first-parent -n 51 "$(git merge-base "$3" HEAD)"); do
if aws s3 ls "$remote/$sha/" > /dev/null 2>&1; then
aws s3 cp --recursive "$remote/$sha" "$2/$sha"
break
fi
done ;;
esac
When there is no map
The first pull requests after setting up, or ones far behind, find no map within reach. TestDetta then selects by name only, which is safe but selects more, and says so in its log. Selection becomes precise once td record has run on the default branch. Set up the record job first: its first run on the default branch writes the first map, and pull or merge requests whose merge base is older than that map select by name until they merge or rebase onto the target branch.
Maps of an earlier format, such as those TestDetta 0.1.x recorded, are ignored with the warning "record the maps again" until the default branch records again; see Limitations.