Unit Testing & Smoke Tests

Relevant source files

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

• tests/unit/test_smoke.py
• tests/unit/README.md
• tests/README.md
• pyproject.toml
• src/README.md
• tests/__init__.py

The testing strategy for the FLEXT API library focuses on fast, isolated validation of core components through unit tests and functional verification via smoke tests. These tests ensure that the service classes, HTTP client operations, and data models function correctly in isolation before moving to integration or end-to-end cycles.

The test suite is organized into a hierarchical structure that separates logic validation from external service interaction. Unit tests specifically target the internal logic of the FlextApiClient, application factories, and query builders using mocks to maintain high execution speeds and isolation.

Sources: tests/README.md:1-25, tests/unit/README.md:1-15

Testing Architecture

The project employs a multi-layered testing architecture. While unit tests focus on isolated modules, smoke tests serve as functional checks to validate that key facades, constants, and models are usable at runtime.

Test Directory Structure

The repository organizes tests based on their scope and dependencies:

Directory	Type	Focus
tests/unit/	Unit	Fast isolated tests with mocks for core components.
tests/integration/	Integration	Tests with real external services (DB, Cache).
tests/e2e/	End-to-End	Complete workflow validation and real-world scenarios.
tests/benchmarks/	Performance	Execution time and memory usage profiling.

Sources: tests/README.md:11-37, tests/unit/README.md:18-32

Component Flow and Validation

The unit testing framework validates the transition of data between core services and builders.

The diagram shows how unit tests interact with core services while smoke tests provide an additional layer of validation for the resulting data models.
Sources: tests/unit/README.md:18-30, tests/unit/test_smoke.py:1-10

Unit Testing Standards

Unit tests in the FLEXT API project must adhere to strict performance and structural standards to ensure maintainability and CI/CD efficiency.

• Speed: Execution must be under 100ms per test.
• Isolation: Tests must be isolated using proper mocking of external dependencies.
• Pattern: Implementation follows the AAA (Arrange, Act, Assert) pattern.
• Naming: Clear and descriptive naming conventions are required for test discovery.

Sources: tests/unit/README.md:52-57

Execution Commands

Tests are typically executed using make commands or pytest directly:

# Fastest execution without coverage
make test-unit-fast

# Specific core component test
pytest tests/unit/test_api_core.py -v

# Filter tests by markers
pytest tests/unit/ -m "not slow"

Sources: tests/unit/README.md:34-48

Smoke Tests Functional Verification

Smoke tests specifically validate that key facades and constants are not just present, but functional at runtime. This includes checking enum resolution, boundary conditions for HTTP statuses, and model validation logic.

Core Validations in test_smoke.py

The TestsFlextApiSmoke class verifies several critical runtime behaviors:

1. Enum Mapping: Ensures c.Api.Method and c.Api.ContentType resolve to correct string/MIME values (e.g., GET, application/json).
2. Immutability: Validates that collections like SAFE_METHODS are immutable.
3. Boundary Logic: Checks that HTTP status bounds (100-599) and success ranges (200-300) are correctly defined.
4. Model Defaults: Verifies that HttpRequest models correctly fill defaults (e.g., defaulting to "GET" if no method is provided).

Sources: tests/unit/test_smoke.py:22-75

Data Serialization Roundtrip

Smoke tests also verify the serialization utility layer, ensuring that payload packing and unpacking maintain data integrity.

Configuration & Tooling

The testing environment is configured via pyproject.toml, which defines markers, coverage thresholds, and dependency groups.

Pytest Configuration

The project defines specific markers to categorize tests, allowing developers to target specific environments or behaviors:

• unit: Isolated logic tests.
• integration: Tests requiring external services.
• docker: Tests requiring a Docker environment.
• slow: Long-running tests excluded from fast cycles.

Sources: pyproject.toml:343-353

Coverage Requirements

The project enforces a coverage floor via tool.coverage.

• Minimum Threshold: fail_under = 25 (Note: This is the baseline configured in managed sections).
• Exclusions: if TYPE_CHECKING: blocks and specific generated providers are omitted from reports.

Sources: pyproject.toml:130-138

Summary

Unit and smoke testing form the foundation of the FLEXT API quality gate system. By combining fast, mocked unit tests for core logic with functional smoke tests for runtime constants and Pydantic models, the project ensures a stable public API surface. The use of standard patterns (AAA) and comprehensive make-based tooling allows for high developer velocity and reliable CI/CD integration.

Sources: tests/README.md:65-67, src/README.md:50-52