Matcher Results & Scopes

Relevant source files

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

• src/flext_tests/_utilities/_matchers/_result_parts/result_part_01.py
• src/flext_tests/_utilities/_matchers/_result_parts/result_part_03.py
• src/flext_tests/_models/_matchers_parts/matchers_part_01.py
• src/flext_tests/_models/_matchers_parts/matchers_part_03.py
• src/flext_tests/_utilities/_matchers/_scope.py
• src/flext_tests/_utilities/matchers.py
• src/flext_tests/_typings/matchers.py

The Matcher Results & Scopes system provides a unified infrastructure for asserting the state of results and managing temporary test environments within the FLEXT ecosystem. It offers a declarative API for validating successful values, error payloads, and structural consistency, while also providing a "Scope" mechanism for temporary configurations including settings, containers, and environment variables.

The primary entry point for these utilities is the tm (test matchers) alias, which aggregates specialized mixins for results, containment, type guarding, and scope management.

Sources: src/flext_tests/_utilities/matchers.py:11-44, README.md:1-50

Result Matcher Architecture

The result matching system is designed to handle p.Result objects, which encapsulate either a successful value or a failure state. The architecture separates the validation of "OK" (successful) results from "FAIL" (error) results, using Pydantic-backed parameter models to ensure type safety in test definitions.

Successful Result Validation (tm.ok)

The tm.ok() method asserts that a result is successful and then applies a series of optional validations against the returned value. It supports scalar checks, type checks, and structural deep matching.

This flow ensures that developers can concisely assert both the presence of a value and its internal structure in a single call.
Sources: src/flext_tests/_utilities/_matchers/_result_parts/result_part_03.py:38-95, src/flext_tests/_models/_matchers_parts/matchers_part_01.py:14-72

Failure Result Validation (tm.fail)

The tm.fail() method asserts that a result has failed and validates the associated error content. It checks the error message text, specific error codes, and structured error data.

Key Data Models

The system relies on specific models to define validation parameters and runtime state.

Assertion Parameters

Model	Purpose	Key Fields
OkParams	Constraints for successful results	eq, is_, gt, has, len, deep, path, paths, items
FailParams	Constraints for failed results	has, lacks, starts, code, code_has, data
DeepMatchResult	Output for recursive comparisons	path, expected, actual, matched, reason

Sources: src/flext_tests/_models/_matchers_parts/matchers_part_01.py:14-106, src/flext_tests/_models/_matchers_parts/matchers_part_03.py:44-55

Test Scope Parameters

The ScopeParams model defines the configuration for a temporary test execution environment.

class ScopeParams(m.Value):
    settings: Mapping[str, TestobjectSerializable] | None = None
    container: Mapping[str, TestobjectSerializable] | None = None
    context: Mapping[str, TestobjectSerializable] | None = None
    cleanup: CleanupSpec | None = None
    env: EnvironmentSpec | None = None
    cwd: Path | str | None = None

Sources: src/flext_tests/_models/_matchers_parts/matchers_part_03.py:18-42

Test Scopes and Runtime State

The tm.scope() utility provides a context manager for initializing and cleaning up test-specific state. This is critical for integration tests that require temporary environment variables, modified working directories, or specific dependency injections.

Scope Lifecycle

1. Initialization: The scope is created using ScopeParams.
2. Environment Setup: Temporary environment variables are set, and the working directory is changed if specified.
3. Execution: The test code runs within the with block.
4. Cleanup: When the block exits, environment variables are restored, the directory is reverted, and registered cleanup functions are executed.

Implementation Details

Path and Item Rules

The system supports declarative rules for complex structures. apply_path_rules allows asserting nested values via dot notation, while apply_item_rules supports selectors like "first", "last", "all", or specific indices.

# Example of Path Rule Implementation
def apply_path_rules(cls, subject, rules):
    for path, rule in rules.items():
        value = cls._extract_path_value(subject, path)
        cls._apply_rule(value, rule)

Sources: src/flext_tests/_utilities/_matchers/_that_parts/that_part_05.py:92-111, src/flext_tests/_utilities/_matchers/_that_parts/that_part_05.py:113-146

Failure Constraints

Error validation is rigorous, checking not just the presence of a message but also error code patterns.

Field	Check Type	Description
code	Equality	Ensures result.error_code matches exactly.
code_has	Substring	Ensures the error code contains specific segments.
data	Dictionary	Validates key-value pairs within the result.error_data mapping.

Sources: src/flext_tests/_utilities/_matchers/_result_parts/result_part_01.py:92-140

Conclusion

The Matcher Results & Scopes system centralizes assertion logic, reducing boilerplate in test suites. By combining Pydantic validation for parameters with flexible structural matching (paths, items, deep matching) and robust environment scoping, it provides a stable foundation for testing complex asynchronous and data-driven systems in the FLEXT ecosystem.