Fixtures DSL Framework
Relevant source files
The following files were used as context for generating this wiki page:
The Fixtures DSL Framework provides a standardized, domain-specific language for loading and managing test fixtures within the FLEXT ecosystem. It is primarily implemented as a mixin that projects can incorporate into their test utility classes to expose flat, high-level loading "verbs" for data files.
This framework simplifies the process of interacting with filesystem-based test data by abstracting path resolution, file reading, and directory iteration into a consistent API. It is designed to work with structured fixture directories where files follow a specific naming convention linked to "groups" (often servers) and "kinds" (data types).
Sources: src/flext_tests/_utilities/fixtures_dsl.py:1-30
Core Architecture
The framework is centered around the FlextTestsFixturesDSLMixin class. This mixin requires consumers to define a _FIXTURES_ROOT path and allows for an optional _FILE_EXTENSION (defaulting to .ldif).
Path Resolution Logic
The framework uses a specific convention to locate fixture files on disk. For a given group and kind, the path is resolved as:
{_FIXTURES_ROOT}/{group}/{group}_{kind}_fixtures{_FILE_EXTENSION}.
The diagram above illustrates how the DSL maps logical identifiers to the physical filesystem structure.
Sources: src/flext_tests/_utilities/fixtures_dsl.py:33-54
Key Components and Methods
The DSL provides several class methods to query and retrieve fixture data.
Loading and Existence
| Method | Description |
|---|---|
path(group, kind) | Returns the Path object if the fixture exists; raises FileNotFoundError otherwise. |
load(group, kind) | Returns the UTF-8 encoded string content of the specified fixture. |
exists(group, kind) | Boolean check to verify if a fixture file exists at the expected location. |
Sources: src/flext_tests/_utilities/fixtures_dsl.py:56-72
Discovery Methods
The DSL allows for dynamic discovery of available fixtures within the root directory:
servers(): Scans the root directory and returns a sorted tuple of directory names (representing groups/servers).kinds(group): Scans a specific group directory and returns a sorted tuple of available fixture kinds by stripping the standard prefix and suffix.
Sources: src/flext_tests/_utilities/fixtures_dsl.py:74-98
Bulk Retrieval and Pytest Integration
For complex test setups or data-driven testing, the DSL provides methods to aggregate fixture data.
The diagram shows the data flow for bulk fixture retrieval and parametrization support.
for_group(group): Returns a mapping of{kind: content}for a specific group.for_kind(kind): Returns a mapping of{group: content}for all groups that possess that kind.all_fixtures(): Returns a full nested mapping:{group: {kind: content}}.pytest_params(kind): Generates a list of(server, content)tuples, suitable forpytest.mark.parametrize.all_pytest_params(): Generates a flat list of(server, kind, content)triples for exhaustive matrix testing.
Sources: src/flext_tests/_utilities/fixtures_dsl.py:100-134
Filesystem Integration
The Fixtures DSL operates alongside the broader FlextTestsFilesystemModels which provide metadata and creation parameters for test files.
Creation Parameters
When fixtures need to be generated dynamically rather than just loaded, the framework utilizes CreateParams.
| Field | Type | Default | Description |
|---|---|---|---|
content | FileContentPlain | N/A | The raw data to be written. |
name | NonEmptyStr | "test.txt" | Target filename. |
fmt | FileFormat | AUTO | Format override (JSON, YAML, CSV, etc.). |
enc | NonEmptyStr | "utf-8" | File encoding. |
Sources: src/flext_tests/_models/_filesystem_parts/filesystem_part_01.py:100-145
Content Serialization
The framework supports multiple output formats for fixtures, including binary, JSON, YAML, and CSV. It uses specific utility helpers to normalize content before writing to the filesystem.
The sequence diagram illustrates how the framework delegates formatted writing to CLI-level utilities.
Sources: src/flext_tests/_utilities/_files/_creation_parts/creation_part_02.py:19-50
Implementation Example
To use the framework, a project typically defines a Tests utility class inheriting from the mixin:
from pathlib import Path
from flext_tests._utilities.fixtures_dsl import FlextTestsFixturesDSLMixin
class ProjectTests(FlextTestsFixturesDSLMixin):
_FIXTURES_ROOT = Path("tests/fixtures")
_FILE_EXTENSION = ".ldif"
# Usage in tests
content = ProjectTests.load("server01", "config")
params = ProjectTests.pytest_params("users")
Sources: src/flext_tests/_utilities/fixtures_dsl.py:20-30
Summary
The Fixtures DSL Framework provides a robust, predictable interface for managing test data in FLEXT projects. By combining filesystem discovery, standardized path resolution, and deep integration with Pytest parametrization, it enables developers to maintain large sets of test fixtures with minimal boilerplate code. Its architecture ensures that data-driven tests remain decoupled from the physical layout of the test data on disk.