Getting started

  1. Install the TestGuard GitHub App on the repositories you want checked.
  2. Commit a .testguard.yml to the default branch to start in warn mode:
    version: 1
    mode: warn
    min_score: 70
  3. Open or update a pull request that touches a test file, then read the TestGuard / integrity check run and the sticky comment it posts.
  4. Once you trust a rule's findings, switch it to action: block in .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: 1

mode

Accepts: warn | block. Default: warn.

warn reports every finding without failing the check. block can fail the check (see Warn or block below).

mode: warn

min_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: 70

paths.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: block

rules.<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: low

thresholds.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: 5

thresholds.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: 25

thresholds.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: 5

frameworks.<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: true

allow_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.

See which checks work in each 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.