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 <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")