Configuration reference¶
TestSeal configuration is strict. Unknown keys, rule IDs, severities, invalid
types, and malformed fingerprints return exit code 2.
File discovery¶
Without --config, TestSeal loads the first applicable source from the
repository root:
testseal.tomlwith a[testseal]table (or top-level TestSeal keys).pyproject.tomlwith a[tool.testseal]table.- Built-in defaults.
An explicit --config PATH takes precedence. Explicit files can use a
[testseal] table, [tool.testseal], or top-level TestSeal keys.
In testseal.toml, keep all policy inside the selected table. Misspelled tables
and keys placed beside it are errors; for example, rule overrides belong in
[testseal.rules.TS001], not a separate [rules.TS001] table. A discovered
pyproject.toml without [tool.testseal] still uses defaults.
Complete example¶
[testseal]
fail_on = "high"
include = ["*.py", "**/*.py", "*.snap", "**/*.snap"]
exclude = [".venv/**", "**/generated/**", "**/vendor/**"]
test_patterns = ["test_*.py", "*_test.py", "tests/**/*.py"]
source_roots = ["src", "packages"]
disabled_rules = ["TS008"]
ignore_fingerprints = ["2ac578e72a8fb4a68d1b96f1"]
[testseal.guarding_tests]
"src/billing/**/*.py" = ["tests/billing/**/*.py"]
[testseal.rules.TS006]
enabled = true
severity = "low"
Top-level keys¶
fail_on¶
Type: string
Values: "never", "low", "medium", "high"
Default: "never"
Sets the lowest severity that returns exit code 1. never keeps findings
advisory. CLI --fail-on overrides this value.
include¶
Type: array of strings
Default:
Only changed paths matching at least one include pattern are eligible. Include patterns apply before test classification.
exclude¶
Type: array of strings
Default:
Any matching path is excluded even if it also matches include. Add generated,
vendored, fixture, and tool-output paths here.
test_patterns¶
Type: array of strings
Default:
Eligible Python paths matching these patterns receive AST-based test analysis. Other eligible paths can still receive artifact or co-edit analysis.
source_roots¶
Type: array of strings
Default: ["src", "lib", "app"]
Identifies repository areas treated as source for co-edit context. Use repository-relative directory names or path prefixes that match the project layout.
guarding_tests¶
Type: table from source glob to a string or array of test globs
Default: empty table
Defines explicit source-to-test relationships for TS008:
[testseal.guarding_tests]
"src/payments/**/*.py" = [
"tests/payments/**/*.py",
"tests/integration/test_checkout.py",
]
The table does not run or select tests. It describes path relationships in the changed file set.
disabled_rules¶
Type: array of rule ID strings
Default: empty array
Disables rules across the scan:
Only TS001 through TS008 are accepted. A rule listed here remains disabled
even if its rule table sets enabled = true.
ignore_fingerprints¶
Type: array of strings
Default: empty array
Suppresses reviewed findings by deterministic fingerprint. Every entry must be exactly 24 hexadecimal characters. Values are normalized to lowercase.
Suppressed findings do not affect counts or failure thresholds. Their number is
reported in suppressed_count.
rules¶
Type: table keyed by rule ID
Default: empty table
Each rule table accepts only enabled and severity:
enabled¶
Type: boolean
Default: true
Enables or disables that rule.
severity¶
Type: string
Values: "low", "medium", "high"
Default: the rule's documented default
Overrides the emitted severity without changing match behavior or confidence.
Path matching¶
Paths are normalized to repository-relative forward-slash form. Configuration patterns follow Git-style expectations:
- relative patterns apply at any directory depth;
**/matches zero or more directories;tests/**/*.pymatchestests/test_api.pyand nested test files;- an exclude match takes precedence over an include match;
- matching is case-sensitive.
Use forward slashes in committed TOML on every operating system.
Standalone and pyproject forms¶
Invalid configuration¶
TestSeal returns exit code 2 for errors such as:
testseal: error: unknown configuration key: 'fail_level'
testseal: error: unknown rule id in disabled_rules: 'TS999'
testseal: error: invalid severity for rules.TS007
This behavior prevents a misspelled policy from silently falling back to a weaker default.