Data Models
Relevant source files
The following files were used as context for generating this wiki page:
- src/flext_tests/models.py
- src/flext_tests/_models/_filesystem_parts/filesystem_part_01.py
- src/flext_tests/_models/_filesystem_parts/filesystem_part_02.py
- src/flext_tests/_models/docker.py
- src/flext_tests/_models/make.py
- src/flext_tests/_models/_matchers_parts/matchers_part_03.py
- src/flext_tests/_validator/models.py
The flext-tests project employs a centralized model architecture centered around the FlextTestsModels class. This class acts as a consolidated namespace, extending base infrastructure models with test-specific definitions for filesystem operations, Docker container management, Make command orchestration, and architectural validation. These models are primarily built using Pydantic, ensuring type safety and runtime validation for test utilities and factories within the FLEXT ecosystem.
Sources: src/flext_tests/models.py:1-44, src/flext_tests/_models/_filesystem_parts/filesystem_part_01.py:10-15
Model Architecture and Hierarchy
The data model layer is structured using a mixin-based approach. The primary facade class FlextTestsModels (aliased as m) inherits from multiple domain-specific mixins. This structure allows for a clean separation of concerns while providing a unified API for accessing models related to different testing subsystems.
The diagram above illustrates the inheritance structure where FlextTestsModels aggregates functionality from specialized mixins.
Sources: src/flext_tests/models.py:24-41
Filesystem Models
Filesystem models handle metadata extraction, file creation parameters, and validation state for files and directories used during testing.
File Metadata and Content
The FileInfo model provides a comprehensive view of a file's state on disk, including its size, encoding, and detected format. It can optionally include ContentMeta which stores statistics for parsed structured data like JSON, YAML, or CSV.
| Field | Type | Description |
|---|---|---|
exists | bool | True when the file exists. |
path | Path | None | Absolute path to the file. |
size | int | File size in bytes. |
lines | int | Line count for text files. |
fmt | str | Detected format label (e.g., json, csv). |
content_meta | ContentMeta | None | Statistics for parsed files. |
Sources: src/flext_tests/_models/_filesystem_parts/filesystem_part_01.py:18-68
Operation Parameters
Specific models define the contract for filesystem operations such as reading, comparing, and asserting file states.
The flowchart shows how parameter models serve as input for various filesystem utility functions.
Sources: src/flext_tests/_models/_filesystem_parts/filesystem_part_02.py:16-150
Docker and Infrastructure Models
These models define configurations for managed Docker containers and test user identities used in integration tests.
Container Configuration
The ContainerConfig model is used by the public DSL to resolve Docker targets, including compose file paths and readiness checks.
- container_name: Optional name for inspection.
- compose_file: Path to the resolved
docker-compose.yml. - service: The specific service name to manage.
- startup_timeout: Maximum wait time (default 30s) for readiness.
Sources: src/flext_tests/_models/docker.py:16-43
Runtime Container Information
The ContainerInfo model captures the state of an active container.
| Field | Description |
|---|---|
status | Runtime lifecycle status (using ContainerStatus enum). |
ports | Mapping of internal to external ports. |
image | Source image tag. |
container_id | Docker-assigned identifier. |
Sources: src/flext_tests/_models/docker.py:45-66
Make Framework Models
The Make models support a registry-driven framework for discovering and executing workspace commands defined in script headers.
This relationship diagram shows how the command registry organizes metadata parsed from workspace scripts.
Sources: src/flext_tests/_models/make.py:15-117
- MakeCommand: Represents a canonical verb (e.g.,
test,check) with associated metadata likesummary,description, andexample. - MakeParam: Defines environment-backed parameters, specifying if they are
requiredand their allowedchoices. - MakeMutationCondition: Predicates that determine if a command will mutate the workspace state based on environment variables.
Sources: src/flext_tests/_models/make.py:18-87
Validation and Matcher Models
Architectural validation and deep-matching utilities use specialized models to report violations and manage test scopes.
Architecture Validation
The ScannerMixin and ScanCommon models provide the scaffolding for architectural validators. They aggregate Violation objects into a ScanResult.
- Violation: Captures specific rule breaches (e.g., forbidden imports in Markdown or layer violations).
- ScanResult: Summarizes the outcome of a scan, including the number of files scanned and the list of violations found.
Sources: src/flext_tests/_validator/models.py:27-84
Matcher and Scope State
The TestScope and ScopeParams models manage the runtime state for tests, including settings, container mappings, and context values.
class TestScope(m.ArbitraryTypesModel):
"""Scope container for test configuration and runtime state."""
settings: Annotated[t.MappingKV[str, t.Tests.TestobjectSerializable], ...]
container: Annotated[t.MappingKV[str, t.Tests.TestobjectSerializable], ...]
context: Annotated[t.MappingKV[str, t.Tests.TestobjectSerializable], ...]
Sources: src/flext_tests/_models/_matchers_parts/matchers_part_03.py:101-114
Summary
Data models in flext-tests provide a strongly-typed foundation for the entire test infrastructure. By utilizing Pydantic models for everything from filesystem metadata to Docker configurations and workspace command registries, the project ensures that test utilities operate on validated, predictable data structures. This central model layer facilitates complex operations like deep-match comparisons, batch file creation, and automated architectural scanning across the FLEXT ecosystem.