Docs
How to set up TestGuard, configure it, choose between warning and blocking, and handle a finding you think is wrong.
Getting started
- Install the TestGuard GitHub App on the repositories you want checked.
- Commit a
.testguard.ymlto the default branch to start in warn mode:version: 1 mode: warn min_score: 70 - Open or update a pull request that touches a test file, then read the
TestGuard / integritycheck run and the sticky comment it posts. - Once you trust a rule's findings, switch it to
action: blockin.testguard.yml.
Preview: the TestGuard GitHub App is not registered yet. To try the whole flow now, run the local demo: npm run demo -- --keep.
.testguard.yml reference
The active .testguard.yml is read from the pull request's base branch, so a pull request cannot loosen its own gate by editing the file; the base branch controls policy, and a change to .testguard.yml is itself still reviewed like any other change. Any key the file sets that this loader does not recognize is rejected.
version
Accepts: the literal 1. Default: not required.
A schema version for the file. Omit it, or set it to 1.
version: 1mode
Accepts: warn | block. Default: warn.
warn reports every finding without failing the check. block can fail the check (see Warn or block below).
mode: warnmin_score
Accepts: an integer 0 to 100. Default: 70.
The score a file must reach once mode is block or any rule's action is block.
min_score: 70paths.include
Accepts: a list of glob patterns. Default: the globs below.
Default globs
**/*.test.***/*.spec.***/__tests__/****/test_*.py**/*_test.py**/*_test.go**/tests/****/*Tests.cs**/*Test.cs**/*.Tests/**/*.cs**/*.Test/**/*.cs**/*Tests.fs**/*Test.fs**/*.Tests/**/*.fs**/*Tests.vb**/*Test.vb**/*.Tests/**/*.vb**/*.feature
Only a changed file whose path matches one of these globs (and no paths.exclude glob) is scanned as a test.
paths:
include:
- "**/*.test.*"paths.exclude
Accepts: a list of glob patterns. Default: the globs below.
Default globs
**/node_modules/****/vendor/****/dist/****/fixtures/****/__mocks__/**
A changed file matching one of these globs is never scanned, even if it also matches paths.include.
paths:
exclude:
- "**/dist/**"ignore_if_only_paths
Accepts: a list of glob patterns. Default: none (nothing is skipped).
When every file changed in the pull request matches one of these globs, TestGuard reports nothing for it.
ignore_if_only_paths:
- "**/*.md"rules.<rule-id>.action
Accepts: warn | block | off. Default: the policy mode (warn, or block when mode is block).
Overrides the action for one rule by its ID, for example TG-008.
rules:
TG-008:
action: blockrules.<rule-id>.severity
Accepts: critical | high | medium | low | info. Default: each rule's own severity.
Overrides how much a rule's finding deducts from a file's score, without changing whether it blocks.
rules:
TG-007:
severity: lowthresholds.TG-007.max_snapshot_files
Accepts: a positive integer. Default: 5.
Mass snapshot update (TG-007) fires when a pull request changes more snapshot files than this.
thresholds:
TG-007:
max_snapshot_files: 5thresholds.TG-007.max_snapshot_blocks
Accepts: a positive integer. Default: 25.
Mass snapshot update (TG-007) also fires when a pull request changes more snapshot blocks than this.
thresholds:
TG-007:
max_snapshot_blocks: 25thresholds.TG-009.max_mocked_modules
Accepts: a positive integer. Default: 5.
Over-mock (TG-009) fires when a test mocks more modules than this and every assertion in it runs on a mock.
thresholds:
TG-009:
max_mocked_modules: 5frameworks.<framework>
Accepts: auto | true | false. Default: auto for every framework (jest, vitest, pytest, go_test, xunit, nunit, mstest, expecto).
Overrides auto-detection for one test framework; set it to true to force it on, or false to force it off.
frameworks:
jest: trueallow_same_package_mocks
Accepts: true | false. Default: false.
When true, a test may mock the module it tests (circular / self-mock, TG-001) without being flagged.
allow_same_package_mocks: false
Warn or block
TestGuard starts in warn mode: every finding is reported, but the check never fails because of it.
A finding fails the check only when its rule's action is block. Once any rule's action is block, or mode is block, a file whose score is below min_score also fails the check.
A failing check blocks a merge only when branch protection on the repository requires that check to pass.
False positives and feedback
Report a false positive from the finding page with a reason of up to 500 characters.
An installation admin decides each report in the Feedback queue; an approved report suppresses that rule on that path in later scans.
Findings about .testguard.yml itself cannot be suppressed.
Languages and limits
TestGuard reads JavaScript/TypeScript, Python, Go and .NET (C#, F#, VB.NET) test files, but not every check has full coverage in every language.
FAQ
Does TestGuard run my tests?
No. It reads the pull request's diff and the changed files at base and head; it never runs or imports your code.
Does TestGuard see my CI results?
No. It reads CI configuration files (workflow YAML, package.json, pytest.ini and similar) only to spot a weakened test gate, such as continue-on-error or a dropped coverage threshold; it never reads whether a CI run passed or failed.
Can a pull request turn TestGuard off by editing .testguard.yml?
No. The policy comes from the base branch's .testguard.yml, and a pull request's own change to that file is itself reported by the CI disarm rule (TG-008).
What does a score mean?
100 means no weakening was found. Each rule with an active finding on a file lowers that file's score once, by the deduction for that rule's highest severity there: critical 25, high 15, medium 8, low 3, info 0. A score never goes below 0.
What does TestGuard cost?
See pricing for founding pricing. It is not live yet, and nothing can be bought through the app today.
Where is my data kept?
See security for what is stored and why. The public site is hosted on Fly.io (Fly.io, Inc.) in the United States (Ashburn, VA); GitHub sign-in and paid plans are not available yet.
How long does TestGuard keep my data?
Scans, audit events and webhook deliveries are deleted after the retention period the operator sets (30 to 90 days); TestGuard sets no default. Scans, jobs, feedback, suppressions, check-run and comment ids and memberships tied to an uninstalled installation or removed repository are deleted after the removal grace period the operator sets (7 to 90 days) once it is removed. Check-run and comment ids are deleted after the closed pull request period the operator sets (7 to 90 days) once the pull request closes. Users who belong to no existing installation are deleted after the inactive user period the operator sets (30 to 365 days) without a sign-in. Billing accounts and events of an uninstalled installation are kept 5 years after the last billing activity or the uninstall, whichever is later. See security for every table.