Internal Test Suite Setup
Relevant source files
The following files were used as context for generating this wiki page:
The Internal Test Suite Setup for the flext-tests project provides a robust infrastructure for shared test utilities, builders, and validation logic within the FLEXT ecosystem. Its primary purpose is to offer standardized testing patterns, including filesystem management, matcher assertions, and architectural validation, to ensure high quality and consistency across various FLEXT modules.
The suite integrates several testing frameworks such as pytest, hypothesis, and factory-boy, while enforcing strict architectural rules through custom validators. It operates as a set of shared utilities that can be leveraged by other projects to maintain a zero-debt baseline and verify slot registries.
Sources: README.md:9-13, pyproject.toml:23-44
Core Testing Architecture
The test suite architecture is built on a modular design using Pydantic-driven models and lazy-loaded utilities. It categorizes testing concerns into specific mixins and helper classes, allowing for granular testing of filesystem interactions, result assertions, and matcher logic.
Dependency and Plugin Registry
The system utilizes pytest entry points to register core plugins and enforcement fixtures. This ensures that any project including flext-tests automatically benefits from the standardized conftest and enforcement logic.
Sources: pyproject.toml:53-56
Utility Lazy Loading
The project employs a lazy-loading mechanism for its utilities to optimize performance during test collection. This is managed through flext_core.lazy, which maps internal mixins (files, matchers, make, result) to their respective public surfaces.
Sources: src/flext_tests/_utilities/init.py:122-171
Filesystem Management (tf)
The filesystem utility (tf) provides a managed lifecycle for temporary files and directories used during tests. It supports automatic cleanup via context managers and handles multiple formats including JSON, YAML, and CSV.
File Metadata Model
The system uses a FileInfo model to capture comprehensive details about the state of the filesystem during test execution.
| Field | Type | Description |
|---|---|---|
exists | bool | Indicates if the file is present. |
size | int | File size in bytes. |
lines | int | Line count for text-based files. |
fmt | str | Detected format (e.g., json, yaml, csv). |
sha256 | str | Hex-encoded digest for integrity checks. |
Sources: src/flext_tests/_models/_filesystem_parts/filesystem_part_01.py:19-54
Creation and Cleanup Flow
Files created through the tf manager are tracked in internal registries (created_files, created_dirs) to ensure they are unlinked during the teardown phase.
Validation and Enforcement
The internal test suite enforces specific architectural standards through a validator layer. This layer scans code for forbidden patterns such as direct monkeypatch usage, unittest.mock imports, and legacy typing annotations.
Test Scanner Rules
The FlextValidatorTests class identifies violations using regex-based patterns to maintain test purity.
| Rule ID | Name | Description |
|---|---|---|
TEST-001 | Monkeypatch | Detects monkeypatch in function signatures or calls. |
TEST-002 | Mock Usage | Flags forbidden use of Mock, MagicMock, or AsyncMock. |
TEST-003 | Patch Decorator | Identifies @patch decorators which should be replaced by FLEXT utilities. |
Sources: src/flext_tests/_validator/tests.py:100-165, src/flext_tests/_constants/_validator_parts/validator_part_02.py:126-140
Markdown Code Block Validation
The suite also validates Python code snippets within Markdown files to ensure they are syntactically correct and follow project typing standards, such as requiring from __future__ import annotations.
Sources: src/flext_tests/_validator/_markdown_parts/markdown_part_01.py:41-94
Matcher and Result Assertions (tm and u.Tests)
The test suite provides specialized matchers and result assertion helpers to simplify test logic and provide descriptive failure messages.
Result Assertion Patterns
The u.Tests utility provides methods to unwrap and assert the state of Result objects, commonly used throughout the FLEXT ecosystem.
assert_success(result, expected_value=None): Validates the result isOkand optionally matches the payload.assert_failure(result, match=None): Validates the result is aFailand optionally checks the error message.
Sources: tests/unit/test_utilities.py:34-75
Universal Matchers
The tm.that interface supports deep attribute and mapping validation. It allows for complex predicates such as checking keys, values, and method callability in a single call.
Conclusion
The Internal Test Suite Setup is a comprehensive framework that goes beyond simple unit testing. By combining managed filesystem utilities, architectural validators, and a rich set of matchers, it provides the necessary infrastructure to maintain the high standards of the FLEXT ecosystem. It ensures that tests are not only verifying functionality but also adhering to the structural and stylistic requirements defined by the project's governance.