Frappe Testing

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  migrate

1) Run tests

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

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

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

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

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

2) Write DocType tests

Create test_.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  run-ui-tests my_app

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

Verification

• [ ] All tests pass: bench --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](references/fixtures.md)
• For UI testing patterns, see [references/cypress.md](references/cypress.md)
• For CI setup, see [references/ci-testing.md](references/ci-testing.md)

References

• [references/test-patterns.md](references/test-patterns.md) - Common test patterns
• [references/fixtures.md](references/fixtures.md) - Test data management
• [references/cypress.md](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 |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lubusIN
• Source: lubusIN/frappe-skills
• License: MIT

Install and usage instructions live in the source repository linked above.