testing skill by lubusin

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

2) Write DocType tests

Create test_<doctype_name>.py alongside the DocType:

3) Write API tests

4) Test permissions

5) Use fixtures

Reference in tests:

6) Run UI tests (Cypress)

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

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

2) Write DocType tests

Create test_<doctype_name>.py alongside the DocType:

3) Write API tests

4) Test permissions

5) Use fixtures

Reference in tests:

6) Run UI tests (Cypress)

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

testing

Documentation

Documentation

Frappe Testing

When to use

Inputs required

Procedure

0) Setup test environment

1) Run tests

2) Write DocType tests

3) Write API tests

4) Test permissions

5) Use fixtures

6) Run UI tests (Cypress)

Verification

Failure modes / debugging

Escalation

References

Guardrails

Common Mistakes

Documentation

testing

Documentation

Frappe Testing

When to use

Inputs required

Procedure

0) Setup test environment

1) Run tests

2) Write DocType tests

3) Write API tests

4) Test permissions

5) Use fixtures

6) Run UI tests (Cypress)

Verification

Failure modes / debugging

Escalation

References

Guardrails

Common Mistakes