Testing Strategy#

FairDM follows a test-first development approach where tests are written before implementation code. This ensures code is designed for testability, encourages comprehensive coverage, and maintains high quality standards.

Overview#

This testing strategy provides contributors with:

  • 5-minute quickstart: Get writing tests immediately with practical examples

  • Clear test taxonomy: Three distinct test layers (unit, integration, contract) with well-defined boundaries

  • Consistent organization: Standardized directory structure and naming conventions

  • Reusable fixtures: Factory-boy factories and pytest fixtures for efficient test setup

  • Quality focus: Emphasis on meaningful, maintainable, and reliable tests over coverage percentages

Quick Start#

New to FairDM testing?

Start with the 5-Minute Quickstart for a hands-on introduction. It covers:

  • Choosing the right test layer

  • Writing your first test

  • Running tests with pytest

  • Using factories for test data

Get Started →

Quick Navigation#

Test Layers

Learn about unit, integration, and contract test layers and when to use each.

Test Layers
Test Quality

Understand what makes tests meaningful, maintainable, and reliable.

Test Quality
Test Organization

Follow the standard directory structure and naming conventions.

Test Organization
Fixtures & Factories

Use pytest fixtures and factory-boy factories for test data.

Fixtures & Factories
Database Strategy

Understand transaction rollback and session-level database management.

Database Strategy
Coverage

Use coverage.py as a diagnostic tool to identify untested code paths.

Test Coverage
Running Tests

Run tests locally with pytest and review coverage reports.

Running Tests

Testing Philosophy#

FairDM’s testing approach is guided by these principles from the FairDM Constitution:

Principle V: Test-First Quality & Sustainability

Test-first development is NON-NEGOTIABLE for FairDM. All new features and bug fixes MUST follow the Red → Green → Refactor cycle:

  1. Red: Write a failing test that defines desired behavior

  2. Green: Write minimal code to make the test pass

  3. Refactor: Improve code quality while maintaining green tests

Test quality is more important than coverage percentages. Tests must be:

  • Meaningful: Test real behavior, not implementation details

  • Maintainable: Clear intent, minimal duplication, easy to update

  • Reliable: Deterministic, isolated, fast execution

5-Minute Quickstart#

New to FairDM testing? Follow these steps:

  1. Choose your test layer (decision tree)

    • Testing isolated logic? → Unit test

    • Testing database interactions? → Integration test

    • Testing API contracts? → Contract test

  2. Place your test file (organization rules)

    tests/{layer}/{app_name}/test_{module}.py

  3. Name your test (naming convention)

    def test_<behavior>__<condition>__<expected>():
    ...

  4. Use fixtures (fixture guide)

    from fairdm.factories import ProjectFactory

def test_project_creation__with_valid_data__creates_project():
    project = ProjectFactory()
    assert project.title

  5. Run your tests (running guide)

    poetry run pytest tests/unit/

Next Steps#

See also

Testing Standards#

FairDM testing follows formal conventions to ensure consistency:

  • Test Naming: Follow pytest conventions with descriptive names (see Test Organization)

  • Test Structure: Organize by type (unit, integration, functional) and module

  • Fixtures: Use factory-boy patterns documented in Fixtures Guide

These standards are binding - all tests must follow these conventions to ensure discoverability, maintainability, and consistent contributor experience.