Troubleshooting¶
Command not found¶
Confirm which interpreter received the package:
If python -m testseal works but testseal does not, the interpreter's scripts
directory is missing from PATH. Use an isolated tool installation with
uv tool install testseal or pipx install testseal to manage that path.
Python version is unsupported¶
TestSeal requires Python 3.11 or newer:
The GitHub Action can select a specific executable with python-command, but
the executable must already exist on the runner.
Not a Git repository¶
Working-tree, staged, and revision modes must run inside a Git worktree. Change
to the repository root or scan a saved patch with --diff.
Unknown or missing revision¶
Fetch the base revision before scanning:
In GitHub Actions, use fetch-depth: 0. The Action cannot derive content that
is absent from the checkout.
Configuration file not found¶
An explicit --config path must exist. Without the option, TestSeal discovers
testseal.toml and then pyproject.toml from the repository root.
Print the current directory and inspect the path:
Unknown configuration key¶
Configuration is fail-closed. Check spelling and table placement against the configuration reference. Common mistakes are:
- using
[tool.testseal]intestseal.tomlwhen[testseal]is clearer; - placing rule tables outside the TestSeal table;
- using a rule ID other than
TS001throughTS008; - providing a string where an array is required;
- using a fingerprint that is not exactly 24 hexadecimal characters.
No changed files¶
Check the selected input:
git status --short
git diff --name-only
git diff --cached --name-only
git diff --name-only origin/main...HEAD
Then check include, exclude, test_patterns, and positional paths. Only
eligible changes contribute to files_scanned.
Expected finding is missing¶
- Confirm the file matches
includeandtest_patterns. - Confirm the rule is enabled.
- Check whether its fingerprint is suppressed.
- Use a Git-backed mode instead of a partial patch.
- Compare the syntax with the rule's supported forms.
- Reduce the case to a minimal before and after example.
TestSeal intentionally does not infer custom matcher APIs, dynamic aliases, or domain-specific semantics.
Unexpected finding¶
Read the rule's intentional non-findings and limits. If the transformation is correct but justified, use a reviewed fingerprint suppression. If the matcher misclassifies documented syntax, open a false-positive report with a minimal fixture.
Parse warning¶
The running Python interpreter could not parse a changed test version. Causes include invalid syntax, syntax newer than the interpreter, or incomplete unified-diff context.
- Run TestSeal with a Python version that supports the target syntax.
- Prefer Git-backed scanning so complete files can be loaded.
- Fix invalid source before relying on the integrity result.
Advisory scans report warnings. Blocking scans return exit code 2 so partial
analysis cannot pass silently.
GitHub Action installation failed¶
The Action installs the Python project bundled with the pinned Action release. Check that:
actions/setup-pythonran first;python-commandnames that interpreter;- the Action reference points to a complete TestSeal release;
install: falseis used only when a matching TestSeal is already installed.
Do not replace the Action package with source copied from an incomplete archive.
Getting help¶
Open a support issue with the version, command, configuration, operating system, relevant Git state, and minimal changed source. Do not include secrets or proprietary code.