Integration Testing in Frappe Framework v15

Integration testing in Frappe Framework v15 verifies that multiple components—such as DocTypes, controllers, database operations, permissions, and workflows—work together correctly.
Unlike unit testing, which validates isolated methods, integration testing evaluates complete business flows within a Frappe Site using the official test runner.

What is Integration Testing in Frappe?

Integration testing in Frappe means testing end-to-end interactions between multiple modules or components.
It ensures:

• Linked DocTypes behave correctly
• Database transactions function as expected
• Permission rules apply properly
• Workflow transitions execute correctly
• REST API endpoints return valid responses

Integration tests run using FrappeTestCase and the bench run-tests command in v15.

When Should You Use Integration Testing?

Use integration testing when validating:

• Sales Order → Invoice workflows
• Stock entry impacts
• Custom business processes
• Permission-controlled access
• Hook-based logic execution

Integration testing is critical in ERPNext customization projects.

Technical Prerequisites

Before writing integration tests in Frappe v15:

• Frappe Framework v15 installed
• Bench environment configured
• App installed on a test site
• Database migrated (bench migrate)

Tests execute in an isolated test database environment.

How to Write an Integration Test in Frappe v15?

Step 1: Import Required Utilities

import frappe
from frappe.tests.utils import FrappeTestCase

Step 2: Create a Test Class

class TestSalesFlow(FrappeTestCase):

Step 3: Simulate Business Flow

class TestSalesFlow(FrappeTestCase):
def test_document_linking(self):
customer = frappe.get_doc({
"doctype": "Customer",
"customer_name": "Integration Test Customer"
}).insert()
sales_order = frappe.get_doc({
"doctype": "Sales Order",
"customer": customer.name
}).insert()
self.assertEqual(sales_order.customer, customer.name)

What This Test Verifies

• Customer record creation
• Sales Order linking
• Database insertion integrity
• Field value correctness

This validates interaction between two DocTypes.

How to Test Workflow Transitions?

You can simulate workflow state changes.

def test_workflow_transition(self):
doc = frappe.get_doc({
"doctype": "ToDo",
"description": "Workflow Test"
}).insert()
doc.status = "Closed"
doc.save()
self.assertEqual(doc.status, "Closed")

Integration tests confirm state consistency across operations.

Testing Permissions in Integration Tests

Frappe allows permission simulation.

def test_permission_control(self):
frappe.set_user("Administrator")
doc = frappe.get_doc("ToDo", {"description": "Test"})
self.assertTrue(doc)

This validates access control mechanisms.

How to Run Integration Tests in Frappe v15?

Run All Tests

bench 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”

Run Specific Test Module

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

What Happens During Integration Test Execution?

When running:

bench run-tests

Frappe:

1. Prepares a test database
2. Applies migrations
3. Executes test cases via Python unittest
4. Rolls back transactions
5. Reports test results

Production data remains unaffected.

Integration Testing vs Unit Testing in Frappe

Both are supported via FrappeTestCase.

Best Practices for Integration Testing

Simulate Real Business Flows

Test complete document lifecycles.

Use Clean Test Data

Avoid reusing test records.

Validate Relationships

Always assert linked DocTypes.

Test Permission Scenarios

Switch users using frappe.set_user().

Run Tests Before Deployment

Execute full test suite before production push.

Common Issues & Troubleshooting

Test Fails Due to Missing Dependencies?

• Ensure required DocTypes exist
• Verify fixtures are loaded
• Confirm app installation

Workflow Not Triggering?

• Check Workflow configuration
• Confirm status transitions exist
• Validate Hook implementations

Database Errors During Tests?

Run:

bench migrate

Ensure MariaDB service is running and site configuration is correct.

Advanced Integration Testing Concepts

Testing Hooks

If you use hooks.py, integration tests should verify:

• doc_events
• Scheduled tasks
• Permission overrides

Example:

def test_doc_event_trigger(self):
doc = frappe.get_doc({
"doctype": "ToDo",
"description": "Hook Test"
}).insert()
self.assertTrue(doc)

Testing REST API Endpoints

For API testing:

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

This confirms controller and database interaction.

Industry Relevance

Integration testing is critical for:

• ERPNext Sales workflows
• Inventory management validation
• Finance & accounting compliance
• Manufacturing process automation

Enterprise ERP deployments require integration validation before production release.

Target Audience

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

Conclusion

Integration testing in Frappe Framework v15 validates complete ERP workflows, DocType interactions, permissions, and hook-based logic. By leveraging FrappeTestCase and bench run-tests, developers ensure reliable and production-ready ERPNext applications.
Adopt integration testing as a mandatory practice in ERPNext customization and enterprise implementations.