Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
The flext-tests project provides a comprehensive infrastructure for the FLEXT ecosystem, focusing on shared test utilities, builders, factories, and architectural validation. It serves as a central hub for maintaining code quality and consistency across multiple repositories by enforcing specific architectural rules and providing robust filesystem manipulation helpers.
The system is designed with a heavy emphasis on lazy loading for performance and strict Pydantic-based data modeling for parameters and results. It integrates closely with flext-core, flext-cli, and flext-infra to provide a unified testing experience.
Sources: README.md:1-12, pyproject.toml:23-45
Core Validation System
The validation system is a primary component of flext-tests, designed to scan codebase files (Markdown, Python, etc.) for violations of FLEXT engineering laws. It utilizes specialized scanners that identify illegal patterns such as forbidden imports, incorrect type annotations, or legacy testing practices.
Validation Flow
The following diagram illustrates how a file is processed by a validator, from initial read to violation reporting.
The validation process ensures that files are only scanned if they are not explicitly approved for a specific rule violation.
Sources: src/flext_tests/_validator/_markdown_parts/markdown_part_01.py:38-75, src/flext_tests/_validator/tests.py:164-184
Validator Rules and Violations
Violations are structured data models that capture the exact location and nature of a rule breach.
| Field | Type | Description |
|---|---|---|
file_path | Path | Path to the file where the violation occurred. |
line_number | int | 1-indexed line number of the violation. |
rule_id | str | Unique identifier for the validation rule (e.g., MD-001, TEST-001). |
severity | str | Severity level derived from constants. |
description | str | Human-readable explanation of the violation. |
code_snippet | str | The actual line of code causing the violation. |
Sources: src/flext_tests/_utilities/validator.py:16-43, src/flext_tests/_validator/tests.py:77-105
Filesystem Infrastructure
The filesystem infrastructure provides high-level abstractions for file creation, reading, and metadata extraction. It includes a FileInfo system that can detect formats, calculate hashes, and parse content statistics for various file types including JSON, YAML, and CSV.
File Metadata Extraction
The system builds a comprehensive FileInfo model by aggregating data from the OS filesystem and internal parsers.
The extraction logic supports optional deep parsing and model validation to ensure file contents match expected schemas.
Sources: src/flext_tests/_utilities/_files/_info.py:65-103, src/flext_tests/_models/_filesystem_parts/filesystem_part_01.py:20-72
Filesystem Models
The project uses specific models to define the parameters for every filesystem operation, ensuring strict type safety.
- FileInfo: Captures existence, size, line counts, encoding, SHA256, and permissions.
- ContentMeta: Contains format-specific metrics like
key_countfor dicts orrow_countfor CSVs. - CreateParams: Defines requirements for creating files, including indentation for JSON/YAML and delimiters for CSV.
Sources: src/flext_tests/_models/_filesystem_parts/filesystem_part_01.py:20-140
Implementation Modules
Markdown Validation
The Markdown validator identifies illegal Python code blocks within .md files. It checks for:
- MD-001: Syntax errors in code blocks.
- MD-002: Forbidden
typingimports (e.g.,Optional,Union) in favor of modern Python 3.10+ syntax. - MD-003: Missing
from __future__ import annotations. - MD-004: Use of the generic
objecttype annotation.
Sources: src/flext_tests/_validator/_markdown_parts/markdown_part_01.py:77-175
Test Enforcement
The test validator (FlextValidatorTests) prevents the use of legacy or problematic testing patterns:
- TEST-001: Detects
monkeypatchusage, encouraging dependency injection or higher-level abstractions. - TEST-002: Flags standard
unittest.mock.MockandMagicMockusage. - TEST-003: Identifies
@patchdecorators.
Sources: src/flext_tests/_validator/tests.py:68-150
Architecture Logic Summary
The flext-tests architecture is built on a "Scanner/Mixin" pattern. Scanners provide the logic for specific file types or rule sets, while Mixins (often gathered in _utilities) provide reusable logic for filesystem interaction and string manipulation.
flext-tests serves as the enforcement layer for the FLEXT ecosystem, providing both the tools to build complex test environments (via filesystem helpers) and the gatekeepers to ensure code remains compliant with modern Python standards and project-specific engineering laws.