Testing

Gitleaks is tested at three layers: rule-level fixtures, package-level Go tests, and end-to-end behavior tests.

Rule-level fixture validation

Every rule defined under cmd/generate/config/rules/*.go calls a local validate(r, tps, fps) helper that runs the rule's regex against true-positive and false-positive sample inputs. If a true positive doesn't match or a false positive does, config generation itself fails. This means rule bugs never reach the embedded config/gitleaks.toml.

The helpers generateSampleSecret, secrets.NewSecret, and alphaNumericExtended in cmd/generate/config/utils/ produce realistic random secrets so rules are tested against more than a single fixed string.

Package tests

Package	Test file	What it covers
detect	detect/detect_test.go (~2.7k lines)	The full scan pipeline. Drives Detector.DetectString/DetectContext against representative fragments and asserts on findings.
detect	detect/baseline_test.go	Baseline filtering of previously seen findings
detect	detect/location_test.go	Line/column resolution from byte offsets
detect	detect/reader_test.go	Streaming detector usage
detect	detect/utils_test.go	Entropy, link generation
detect/codec	detect/codec/decoder_test.go	Base64/hex/percent decoding
config	config/config_test.go	Viper translation, extend/inherit
config	config/allowlist_test.go	Match conditions, regex/path/commit/stopword combinations
report	per-format _test.go	JSON, CSV, JUnit, SARIF, template output
sources	sources/git_test.go, sources/common_test.go	Git command parsing, archive identification

Running tests

# Full suite, race detector on
make test

# Stop at first failure, faster iteration
make failfast

# Coverage report
make test-cover

The Makefile target also runs make config/gitleaks.toml and go fmt ./... first, so you'll never run tests against a stale generated config.

CI

.github/workflows/test.yml runs the matrix [ubuntu-latest, windows-latest] with Go 1.25. It uses gotestsum for nicer output and runs go generate ./... && git diff --exit-code to guard against forgotten config regeneration.

Writing a new test

For a rule, the path of least resistance is a sample-secret-based fixture inside the rule's *.go file (the tps and fps slices). The validator runs at generation time and gives you immediate feedback.

For engine-level changes (allowlist semantics, decoder behavior, etc.), add a table entry to the appropriate _test.go. The detect/detect_test.go file is dense; mimic the surrounding style — most tests build a config.Config, instantiate a Detector, call DetectString, and assert.ElementsMatch on findings.

For changes that span multiple packages, consider whether an integration test through Detector.DetectSource plus a sources.File from an in-memory bytes.Buffer is more appropriate than mocking each layer.