Frappe Testing

Write and run tests for Frappe applications using the built-in testing framework.

When to use

• Writing unit tests for DocType controllers
• Writing integration tests for workflows and APIs
• Running existing test suites
• Debugging test failures
• Setting up CI pipelines for Frappe apps

Inputs required

• App name to test
• Site name for test execution
• Specific module/DocType to test (optional)
• Test environment (dev site, dedicated test site)

Procedure

0) Setup test environment

# Install dev dependencies
bench setup requirements --dev

# Ensure site is ready
bench --site <site> migrate

1) Run tests

# Run all tests for an app
bench --site <site> run-tests --app my_app

# Run tests for specific module
bench --site <site> run-tests --module my_app.my_module.tests

# Run tests for specific DocType
bench --site <site> run-tests --doctype "My DocType"

# Verbose output
bench --site <site> run-tests --app my_app -v

# Run single test file
bench --site <site> run-tests --module my_app.doctype.sample_doc.test_sample_doc

2) Write DocType tests

Create test_<doctype_name>.py alongside the DocType:

# my_app/doctype/sample_doc/test_sample_doc.py
import frappe
from frappe.tests.utils import FrappeTestCase

class TestSampleDoc(FrappeTestCase):
    def setUp(self):
        # Create test data
        self.doc = frappe.get_doc({
            "doctype": "Sample Doc",
            "title": "Test Document"
        }).insert()
    
    def tearDown(self):
        # Cleanup
        frappe.delete_doc("Sample Doc", self.doc.name, force=True)
    
    def test_creation(self):
        self.assertEqual(self.doc.title, "Test Document")
    
    def test_validation(self):
        doc = frappe.get_doc({
            "doctype": "Sample Doc",
            "title": ""  # Invalid - required field
        })
        self.assertRaises(frappe.ValidationError, doc.insert)
    
    def test_workflow(self):
        self.doc.status = "Approved"
        self.doc.save()
        self.assertEqual(self.doc.status, "Approved")

3) Write API tests

# my_app/tests/test_api.py
import frappe
from frappe.tests.utils import FrappeTestCase

class TestAPI(FrappeTestCase):
    def test_whitelist_method(self):
        from my_app.api import process_order
        
        # Create test order
        order = frappe.get_doc({
            "doctype": "Sales Order",
            "customer": "_Test Customer"
        }).insert()
        
        # Test the API
        result = process_order(order.name, "approve")
        
        self.assertEqual(result["status"], "success")
        
        # Cleanup
        frappe.delete_doc("Sales Order", order.name, force=True)
    
    def test_permission_denied(self):
        # Test as restricted user
        frappe.set_user("guest@example.com")
        
        from my_app.api import sensitive_action
        self.assertRaises(frappe.PermissionError, sensitive_action, "doc-001")
        
        # Reset user
        frappe.set_user("Administrator")

4) Test permissions

def test_role_permissions(self):
    # Create user with specific role
    user = frappe.get_doc({
        "doctype": "User",
        "email": "test_user@example.com",
        "roles": [{"role": "Sales User"}]
    }).insert()
    
    frappe.set_user("test_user@example.com")
    
    # Test permission
    self.assertTrue(frappe.has_permission("Sales Order", "read"))
    self.assertFalse(frappe.has_permission("Sales Order", "delete"))
    
    # Cleanup
    frappe.set_user("Administrator")
    frappe.delete_doc("User", user.name, force=True)

5) Use fixtures

# my_app/doctype/sample_doc/test_records.json
[
    {
        "doctype": "Sample Doc",
        "title": "Test Record 1"
    },
    {
        "doctype": "Sample Doc",
        "title": "Test Record 2"
    }
]

Reference in tests:

class TestSampleDoc(FrappeTestCase):
    def test_fixture_loaded(self):
        doc = frappe.get_doc("Sample Doc", "Test Record 1")
        self.assertIsNotNone(doc)

6) Run UI tests (Cypress)

# Run UI tests for an app
bench --site <site> run-ui-tests my_app

# Headless mode
bench --site <site> run-ui-tests my_app --headless

Verification

• All tests pass: bench --site <site> run-tests --app my_app
• No test pollution (tests are isolated)
• Tests run in < 5 minutes for fast feedback
• CI pipeline runs tests on each commit

Failure modes / debugging

• Test not found: Ensure filename starts with test_ and class/method names follow conventions
• Database errors: Tests may not be isolated—check for missing cleanup
• Permission errors in tests: Use frappe.set_user("Administrator") in setup
• Slow tests: Avoid unnecessary fixtures, mock external services

Escalation

• For complex fixtures, see references/fixtures.md
• For UI testing patterns, see references/cypress.md
• For CI setup, see references/ci-testing.md

References

• references/test-patterns.md - Common test patterns
• references/fixtures.md - Test data management
• references/cypress.md - UI testing

Guardrails

• Use test fixtures: Load test data via fixtures, not manual creation in each test
• Clean up test data: Delete created records in tearDown() or use frappe.db.rollback()
• Mock external services: Never call real APIs in tests; mock HTTP calls
• Isolate tests: Each test should be independent; no reliance on test execution order
• Set user context explicitly: Use frappe.set_user() to test as specific users

Common Mistakes

Mistake	Why It Fails	Fix
Not using FrappeTestCase	Missing test setup/teardown	Extend frappe.tests.utils.FrappeTestCase
Missing db rollback	Test pollution, flaky tests	Use frappe.db.rollback() in tearDown or transactions
Flaky async tests	Intermittent failures	Use frappe.tests.utils.run_until() or proper async handling
Testing implementation not behavior	Brittle tests	Test outcomes, not internal method calls
Hardcoded test data	Conflicts with existing data	Use unique names like _Test Record {uuid}
Skipping permission tests	Security holes	Test with different user roles, not just Administrator