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:

HookPurpose
validate_copyrightAdd/check copyright headers in .py, .js, .ts, .md
clean_customized_doctypesRemove null values from customization JSON files
validate_javascript_dependenciesDetect package.json version mismatches across installed apps
validate_python_dependenciesDetect pyproject.toml version mismatches across installed apps
validate_customizationsValidate Custom Fields and Property Setters (details)
update_pre_commit_configKeep pre-commit config pinned to the latest test_utils revision
mypyRun mypy with a preset configuration
track_overridesTrack changes to override methods across branches
add_translationsExtract untranslated strings and translate them
sql_docstring_formatterFormat SQL in Python docstrings via sqlglot
sql_registryRegister SQL operations for tracking
bylinesAdd git-history-derived bylines to Markdown files
validate_patchesValidate patches.txt ordering and file presence
validate_frappe_projectValidate pyproject.toml structure for Frappe apps
validate_doctype_python_typesRequire Frappe auto-generated DocType controller types (or an opt-out comment) when hooks export is enabled (details)
check_code_duplicationDetect copy-paste duplication in Python and JS/TS
static_analysisFull static analysis suite (see above)
code_graphBuild/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.

Please contact us for corrections, additions, questions, or to request a topic.

© 2026 AgriTheory. All Rights Reserved.