Unit Testing in Frappe Framework v15
Unit testing in Frappe Framework v15 verifies individual components such as DocTypes, methods, and validations in isolation. It ensures that business logic works correctly before deployment.
Frappe v15 provides built-in testing utilities based on Python’s unittest framework and integrates them with the Bench CLI.
What is Unit Testing in Frappe?
Unit testing in Frappe means testing small units of application logic independently.
A “unit” can be:
- A DocType validation
- A Python method
- A database operation
- A permission rule
- A workflow state transition
Frappe provides FrappeTestCase as the base class for writing tests.
Technical Prerequisites
Before writing unit tests in Frappe v15:
- Frappe Framework v15 installed
- Bench environment configured
- App installed on a site
- Developer mode enabled
Tests run inside a separate test database, not production.
Where Should Unit Tests Be Created?
Unit tests must follow this structure:
your_app/
your_module/
doctype/
your_doctype/
test_your_doctype.py
Naming Convention
- Test file must start with test_
- Test classes must inherit from FrappeTestCase
- Test methods must start with test_
Frappe automatically detects these files during execution.
How to Write a Unit Test in Frappe v15?
Step 1: Import Required Modules
import frappe
from frappe.tests.utils import FrappeTestCase
Step 2: Create a Test Class
class TestToDo(FrappeTestCase):
Step 3: Add Test Methods
class TestToDo(FrappeTestCase):
def test_todo_creation(self):
doc = frappe.get_doc({
"doctype": "ToDo",
"description": "Unit Test ToDo"
})
doc.insert()
self.assertEqual(doc.description, "Unit Test ToDo")
What This Does
- Creates a ToDo document
- Inserts it into the test database
- Verifies the inserted value using assertion
How to Test Validations in Frappe?
You can test mandatory fields and validation errors using assertRaises.
def test_mandatory_field(self):
doc = frappe.get_doc({
"doctype": "ToDo"
})
with self.assertRaises(frappe.ValidationError):
doc.insert()
This ensures validation logic works as expected.
How to Run Unit Tests in Frappe v15?
Run All Tests
bench run-tests
Run Tests for a Specific Site
bench --site your-site-name run-tests
Run Tests for a Specific App
bench --site your-site-name run-tests --app your_app_name
Run Tests for a Specific DocType
bench --site your-site-name run-tests --doctype "DocType Name"
What Happens During Test Execution?
When you execute:
bench run-tests
Frappe:
- Creates or prepares a test database
- Runs test cases using unittest
- Rolls back transactions after execution
- Reports failures and errors
This ensures production data safety.
How Does Frappe Handle Test Database?
Frappe automatically:
- Uses a test database (prefixed internally)
- Applies migrations before tests
- Cleans up test records
This isolation guarantees safe testing.
Testing Business Logic Methods
You can test custom Python methods defined in DocType controllers.
Example:
def test_custom_method(self):
doc = frappe.get_doc({
"doctype": "ToDo",
"description": "Check method"
})
doc.insert()
result = doc.some_custom_method()
self.assertTrue(result)
Unit tests should focus on:
- Calculations
- Field transformations
- Conditional logic
- Permission checks
Best Practices for Unit Testing in Frappe v15
Keep Tests Independent
Each test must run independently of others.
Use Minimal Data
Create only required fields.
Avoid External Dependencies
Do not depend on APIs or third-party systems.
Follow Naming Standards
Always use test_ prefix.
Run Tests Before Deployment
Always execute tests before production release.
Common Issues & Troubleshooting
Test Not Detected?
- Ensure file name starts with test_
- Confirm class inherits from FrappeTestCase
- Verify app is installed on the site
ValidationError Not Triggering?
- Confirm mandatory fields are defined in DocType
- Check validate() method implementation
Database Errors?
Run:
bench migrate
Ensure MariaDB service is running.
Industry Relevance
Unit testing is critical for:
- ERPNext customization projects
- Finance and accounting workflows
- Manufacturing validations
- CRM automation logic
Enterprise ERP deployments must use automated unit testing for stability.
Target Audience
- Frappe Developers
- ERPNext Developers
- QA Engineers
- DevOps Teams
- ERP Implementers
Frequently Asked Questions (FAQ)
What is the base class for unit testing in Frappe v15?
FrappeTestCase from frappe.tests.utils.
How do I run a single DocType test?
bench --site your-site-name run-tests --doctype "DocType Name"
Does unit testing affect production data?
No. Frappe uses an isolated test database.
Can I test custom DocType logic?
Yes. You can test controller methods, validations, and workflows.
Conclusion
Unit testing in Frappe Framework v15 is a structured way to validate DocTypes, methods, and business logic using FrappeTestCase and the bench run-tests command. By following official naming conventions and test isolation mechanisms, developers can build reliable and scalable ERPNext applications.
Implement unit testing as a core part of your ERPNext development lifecycle to ensure stability and maintainability.
