AgriTheory Test Utils — Documentation Index
Test Utils is a collection of development tools for Frappe apps: test fixtures, pre-commit hooks, GitHub Action templates, and static analysis. It is maintained by AgriTheory and published at github.com/agritheory/test_utils.
Tools
Pre-commit Hooks
pre_commit_hooks.md documents all available hooks. A summary:
| Hook | Purpose |
|---|---|
validate_copyright | Add/check copyright headers in .py, .js, .ts, .md |
clean_customized_doctypes | Remove null values from customization JSON files |
validate_javascript_dependencies | Detect package.json version mismatches across installed apps |
validate_python_dependencies | Detect pyproject.toml version mismatches across installed apps |
validate_customizations | Validate Custom Fields and Property Setters (details) |
update_pre_commit_config | Keep pre-commit config pinned to the latest test_utils revision |
mypy | Run mypy with a preset configuration |
track_overrides | Track changes to override methods across branches |
add_translations | Extract untranslated strings and translate them |
sql_docstring_formatter | Format SQL in Python docstrings via sqlglot |
sql_registry | Register SQL operations for tracking |
bylines | Add git-history-derived bylines to Markdown files |
validate_patches | Validate patches.txt ordering and file presence |
validate_frappe_project | Validate pyproject.toml structure for Frappe apps |
validate_doctype_python_types | Require Frappe auto-generated DocType controller types (or an opt-out comment) when hooks export is enabled (details) |
check_code_duplication | Detect copy-paste duplication in Python and JS/TS |
static_analysis | Full static analysis suite (see above) |
code_graph | Build/query/plot per-app code graph; --with graph (+ --with dev for plot) |
Customization Validation
validate_customizations.md covers the validate_customizations hook in depth, including why to avoid fixtures, how to organize customization files, and all validation checks (custom permissions, module attribution, system-generated fields, duplicate detection).
DocType Python types
validate_doctype_python_types.md covers Frappe’s exported controller types, opt-out comments, pre-commit and CLI usage, and how to test the hook against an existing app repo or bench checkout.
SQL Registry
sql_registry.md documents the SQL scanning, registration, and Query Builder rewriting tools.
Code Duplication
code_duplication.md documents the copy-paste duplication checker.
Partitions
partitions.md documents the create_partition utility for MariaDB table partitioning.
MariaDB performance analytics
mariadb_analytics.md documents Performance Schema snapshot tables, top-SQL / top-wait deltas, and one-shot enable for Frappe sites.
Static Analysis
static_analysis validates the internal consistency of a Frappe app's configuration and source code without importing any Python or running a bench. It catches broken references before they reach a server.
Code graph
The code_graph CLI (console script from the test_utils package, not a Frappe bench app) and test_utils.utils.graph build a DuckDB artifact per app: Python functions (cyclomatic complexity, nesting depth, @frappe.whitelist()), hooks.py path registrations, and JS/TS/Vue frappe.call / xcall sites with tree-sitter loop detection. Install optional deps with poetry install --with graph (adds duckdb and networkx). Subcommand code_graph plot writes PNG histograms and bar charts (needs --with dev for matplotlib). Subcommand code_graph export-view writes a standalone HTML file with an interactive force-directed graph (vis-network, similar in spirit to Obsidian’s graph view: pan, zoom, physics, hover tooltips). Orchestration, OAuth2 MCP-style endpoints, and weekly leaderboard reports are expected to live in ATERP.
Printer mocks
printers.md documents the IPP codec, raw/IPP mock servers, sync wrappers for pytest, and the mock-printer CLI for manual CUPS testing.
Test Fixtures
Test Utils ships reference fixture data for bootstrapping Frappe/ERPNext test environments:
- Companies and Chart of Accounts
- Customers, Suppliers, Employees, Tax Authorities
- Items, BOMs, Workstations, Operations
GitHub Actions
- Code Duplication reports copy-paste in Python, JavaScript, and TypeScript on pull requests, and fails when clone or percentage thresholds are exceeded.
- Changelog Generator writes a draft changelog comment from the pull request. Release integration covers using that comment as the release notes.
- Translate Docs translates changed English documentation and opens a pull request for each target language.
- Track Overrides compares annotated method overrides with upstream and comments when that upstream method has moved.
- Print Format Diff comments the diff of print format JSON on the pull request.
- Publish Docs is for AgriTheory apps only. When a push to the default branch changes markdown, it rebuilds the AgriTheory website so documentation is refetched and search is reindexed.