Automated Testing in Frappe Framework v15

Automated testing in Frappe Framework v15 ensures application stability, data integrity, and reliable customizations. Frappe provides a built-in test runner integrated with Bench to execute unit and integration tests across apps and DocTypes.
This guide explains how automated testing works in Frappe v15, how to write tests, and how to execute them using official commands.

What is Automated Testing in Frappe?

Automated testing in Frappe is a built-in mechanism for validating application logic, DocTypes, and business workflows using Python-based test cases.
Frappe uses:

• Python’s unittest framework
• A test database environment
• Bench command-line utilities

Tests are executed using the bench run-tests command.

Why Use Automated Testing in Frappe v15?

Automated testing ensures:

• Safe ERPNext customizations
• Stable app upgrades
• Accurate DocType validations
• Verified business logic execution
• Reduced regression issues

It is essential for production-ready ERPNext implementations.

How to Run Tests in Frappe v15

Step 1: Navigate to Bench Directory

cd frappe-bench

Step 2: Run All Tests

bench run-tests

This command runs tests for all installed apps on the current site.

Run Tests for a Specific App

bench --site your-site-name run-tests --app your_app_name

This runs tests only for the specified app.

Run Tests for a Specific DocType

bench --site your-site-name run-tests --doctype "DocType Name"

This executes test cases related to a specific DocType.

Run a Specific Test File

bench --site your-site-name run-tests --module path.to.test_module

This allows granular test execution.

Where Are Tests Stored in Frappe?

Tests are typically located inside the app structure:

your_app/
your_module/
doctype/
your_doctype/
test_your_doctype.py

Test files follow the naming convention:

test_*.py

Frappe automatically detects these during test execution.

How to Write a Test Case in Frappe v15

Frappe test cases inherit from:

import frappe
from frappe.tests.utils import FrappeTestCase

Basic Example

import frappe
from frappe.tests.utils import FrappeTestCase
class TestToDo(FrappeTestCase):
def test_todo_creation(self):
doc = frappe.get_doc({
"doctype": "ToDo",
"description": "Test ToDo"
})
doc.insert()
self.assertEqual(doc.description, "Test ToDo")

What Happens Here?

• A test document is created.
• It is inserted into the test database.
• Assertions validate expected behavior.

Test Execution Environment in Frappe

Frappe uses a separate test database during execution.

Key behaviors:

• Database is automatically prepared.
• Test records are isolated.
• Data is rolled back after test execution.

This ensures production data safety.

Testing DocType Validations

You can test:

• Mandatory fields
• Validation logic
• Workflow state transitions
• Custom scripts

Example validation test:

def test_mandatory_field(self):
doc = frappe.get_doc({
"doctype": "ToDo"
})

with self.assertRaises(frappe.ValidationError):
doc.insert()

How Does Frappe Handle Test Data?

Frappe provides utilities for:

• Creating test records
• Loading test fixtures
• Using JSON test records

Fixtures are stored in:

your_app/fixtures/

You can export fixtures using:

bench export-fixtures

Integration Testing in Frappe v15

Integration tests validate:

• API endpoints
• Business flows
• Linked DocTypes
• Permission rules

Example:

response = frappe.get_doc("ToDo", doc.name)
self.assertTrue(response)

Integration tests ensure complete process validation.

Best Practices for Automated Testing

1. Keep Tests Independent

Each test should run without relying on another test.

2. Use Minimal Data

Avoid unnecessary record creation.

3. Test Business Logic

Focus on workflows, calculations, and validations.

4. Run Tests Before Deployment

Always execute:

bench run-tests

before production deployment.

Advanced Testing Options

Run Tests with Coverage

bench run-tests --coverage

This generates code coverage reports.

Verbose Output

bench run-tests --verbose

Useful for debugging failures.

Common Issues & Troubleshooting

Tests Not Running?

• Ensure app is installed on the site.
• Confirm test file follows test_*.py naming convention.
• Verify Python syntax is correct.

Database Errors During Testing?

• Run migrations:

bench migrate

• Ensure MariaDB is running.
• Check site configuration.

Technical Overview

Industry Relevance

Automated testing is critical for:

• ERPNext customization projects
• Manufacturing ERP workflows
• Finance & accounting validation
• Workflow-heavy enterprise systems

It ensures long-term scalability and maintainability.

Target Audience

• ERPNext Developers
• Frappe App Developers
• System Implementers
• DevOps Engineers
• QA Engineers

Cross References

• Frappe Hooks Documentation
• Frappe REST API Guide
• ERPNext Customization Guide
• Bench Command Reference

Conclusion

Automated testing in Frappe Framework v15 provides a reliable, structured way to validate application logic and ERP customizations. By leveraging bench run-tests, structured test cases, and database isolation, developers can confidently deploy stable and scalable solutions.
Implement automated testing early in your ERPNext development lifecycle to ensure long-term success.