Unit Testing Strategy

Relevant source files

The following files were used as context for generating this wiki page:

• tests/unit/README.md
• tests/unit/test_factory.py
• tests/unit/test_init.py
• tests/README.md
• pyproject.toml

The Unit Testing Strategy for the FLEXT Observability project focuses on fast, isolated validation of individual components. These tests ensure that domain entities, service logic, and factory patterns function correctly without relying on external dependencies such as databases, networks, or file systems. The primary goal is to maintain 95%+ coverage across all modules while enforcing enterprise-grade quality standards.

Unit tests are characterized by their execution speed—typically finishing in under one second per test—and their heavy use of mocking for external interactions. This isolation allows developers to focus exclusively on business logic and domain validation within the FLEXT ecosystem's layered architecture.

Sources: tests/unit/README.md:14-20, tests/README.md:27-28, tests/README.md:126-129

Core Objectives and Scope

The unit testing layer is designed to validate the smallest testable parts of the application in total isolation. This includes checking the internal state and return values of functions, classes, and methods.

Key Focus Areas

• Domain Entity Validation: Ensuring that entities like FlextMetric or FlextTrace adhere to business rules and constraints.
• Service Layer Logic: Testing the coordination and business logic within services like FlextMetricsService using mocked dependencies.
• Factory Patterns: Validating the creation logic for observability entities via the FlextObservabilityMasterFactory.
• Railway-Oriented Programming (ROP): Verifying that operations correctly return Result[T] types for both success and failure paths.

Sources: tests/unit/README.md:24-30, tests/README.md:140-145

Test Organization and Structure

The project is transitioning toward a structured tests/unit/ directory. Currently, many unit tests reside in the root tests/ directory but are targeted for migration to specific files organized by concern.

Planned File	Focus Area
test_entities_unit.py	Domain entity validation and behavior
test_services_unit.py	Service layer business logic
test_factory_unit.py	Factory pattern and entity creation validation
test_validation_unit.py	Specific domain validation rule testing
test_utilities_unit.py	Utility function and helper testing

Sources: tests/unit/README.md:34-45, tests/README.md:44-50

Testing Patterns

Railway-Oriented Validation

The project utilizes ROP patterns where functions return success or failure results instead of throwing exceptions. Unit tests must validate both branches of this logic.

The diagram above illustrates how unit tests verify the two possible outcomes of a standard FLEXT operation.
Sources: tests/README.md:88-109

Factory Pattern Testing

The FlextObservabilityMasterFactory is a central component that creates validated observability entities. Tests for this factory ensure that even without heavy mocking, the factory correctly handles input and container integration.

def test_metric_creation_real_functionality(self) -> None:
    """Test metric creation with actual factory functionality."""
    factory = FlextObservability.FlextObservabilityMasterFactory()
    metric_result = factory.create_metric("test_metric", 42.5, "gauge")
    tm.that(metric_result.success, eq=True)
    tm.that(metric_result.value.name, eq=True)

Sources: tests/unit/test_factory.py:28-34

Tooling and Configuration

The unit testing strategy is supported by a robust set of tools defined in the project configuration.

Technical Stack

• Framework: pytest (version 8.4+) is the primary test runner.
• Mocking: pytest-mock (version 3.14+) is used for isolating components.
• Coverage: pytest-cov (version 6.2+) tracks progress toward the 95% coverage requirement.
• Type Checking: mypy and pyright ensure type safety within test files.

Sources: pyproject.toml:98-125, pyproject.toml:500-530

Execution Commands

Developers can execute unit tests using specific pytest markers or path targets:

# Run all unit tests
pytest tests/unit/ -v

# Run with coverage report
pytest tests/unit/ --cov=src/flext_observability --cov-report=term-missing

# Run excluding integration tests
pytest tests/ -m "not integration" -v

Sources: tests/unit/README.md:73-81, tests/README.md:118-122

Quality Standards

The strategy mandates specific quality gates that must be passed for all unit tests.

Coverage and Validation Requirements

1. Minimum Coverage: 95% overall, with 100% for critical path observability functions.
2. Strict Typing: Tests must follow MyPy strict mode and include complete type annotations.
3. Independence: Tests must be isolated and capable of running in any order (supported by pytest-randomly).
4. Error Handling: Every test must include scenarios for invalid input and failure paths.

Sources: tests/README.md:140-155, pyproject.toml:210-230

Conclusion

The Unit Testing Strategy for FLEXT Observability provides a foundation for high-confidence development by enforcing isolation, fast feedback loops, and strict adherence to Railway-Oriented Programming. By leveraging standardized patterns and a comprehensive suite of tools, the project ensures that core domain logic remains stable and reliable throughout the development lifecycle.

Sources: tests/unit/README.md:24-30, tests/README.md:175-180