Fluent Matchers API

Relevant source files

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

• src/flext_tests/_utilities/matchers.py
• src/flext_tests/_utilities/_matchers/_that_parts/that_part_04.py
• src/flext_tests/_utilities/_matchers/_that_parts/that_part_05.py
• 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_03.py
• src/flext_tests/_typings/matchers.py

The Fluent Matchers API provides a unified, declarative assertion framework for the FLEXT ecosystem. It is designed to simplify complex test validations through a single entry point, typically aliased as tm, allowing developers to perform deep comparisons, sequence validations, and result-based assertions with minimal boilerplate.

The API spans scalar values, collections, nested object attributes, and the Result type pattern. By utilizing declarative "Match Rules," the system can resolve complex validation logic from simple dictionary or keyword argument specifications.

Sources: src/flext_tests/_utilities/matchers.py:1-25, src/flext_tests/_utilities/_matchers/_that_parts/that_part_05.py:1-20

Core Architecture and Entry Points

The API is organized into a centralized utility class, FlextTestsMatchersUtilities, which aggregates various mixins to provide a comprehensive assertion surface. The primary interface for developers is the tm alias, which points to the internal Tests.Matchers container.

The architecture separates the assertion logic (mixins) from the data models used to parameterize them.
Sources: src/flext_tests/_utilities/matchers.py:27-51, src/flext_tests/_utilities/_matchers/_that_parts/that_part_05.py:100-150

Primary Assertion Methods

The following table summarizes the main entry points available via tm:

Method	Purpose	Key Parameters
tm.that()	Universal matcher for any object.	eq, ne, is_, matches, paths, items
tm.ok()	Asserts a Result is success and validates payload.	path, deep, where, plus that params
tm.fail()	Asserts a Result is failure and validates error.	code, code_has, data, has, lacks
tm.check()	Starts a chained assertion sequence.	result

Sources: src/flext_tests/_utilities/_matchers/_result_parts/result_part_01.py:33-40, src/flext_tests/_utilities/_matchers/_result_parts/result_part_03.py:46-70

Universal Matcher (tm.that)

The that method is the core generalist matcher. It supports scalar comparisons, regex matching, type checking, and deep structure validation.

Declarative Rules

A "Match Rule" allows developers to pass complex constraints as data. The system resolves these rules by converting different input types into specific keyword arguments for the underlying matcher.

• Mapping: Interpreted as a set of matcher parameters (e.g., {"gte": 10, "lt": 20}).
• Type/Tuple of Types: Interpreted as an identity check (is_).
• Callable: Interpreted as a predicate function (where).
• Other: Interpreted as an equality check (eq).

Sources: src/flext_tests/_utilities/_matchers/_that_parts/that_part_05.py:21-50, src/flext_tests/_typings/matchers.py:61-75

Structured Data Validation

The API provides specialized logic for navigating and validating complex data structures:

1. Path Rules (paths): Validates values at dotted-string paths (e.g., user.profile.id) within a dictionary or Pydantic model.
2. Item Rules (items): Validates elements in a sequence using indices or special selectors like "first", "last", and "*" (all items).
3. Attribute Rules (attrs_match): Validates object attributes, including nested attributes via dot-notation.

Sources: src/flext_tests/_utilities/_matchers/_that_parts/that_part_05.py:87-190

Result Matchers (tm.ok and tm.fail)

Specialized matchers exist for the Result[T] pattern, facilitating fluent validation of operations that can succeed or fail.

Success Validation (tm.ok)

The ok method performs a multi-stage validation:

1. Extraction: Optionally extracts a sub-payload via the path parameter.
2. Constraint Checks: Applies standard tm.that constraints (length, equality, etc.).
3. Deep Matching: Uses the deep parameter to perform structural validation against a DeepSpec.
4. Composition: Can apply paths, items, and attrs_match rules to the successful result payload.

Failure Validation (tm.fail)

The fail method ensures an operation failed as expected and allows inspection of the error details:

• Error Code: Matches the error_code exactly or via containment (code_has).
• Error Text: Validates the textual error message using has, lacks, starts, or regex match.
• Error Data: Performs key-value equality checks on the error_data dictionary.

Sources: src/flext_tests/_utilities/_matchers/_result_parts/result_part_01.py:42-160

Data Models and Types

The behavior of matchers is governed by Pydantic models that enforce parameter types and provide default values.

Parameter Models

• ThatParams: Defines valid constraints for general matching (e.g., eq, ne, gt, len, matches).
• OkParams: Inherits from ThatParams, adding result-specific fields like path, deep, and attrs_match.
• FailParams: Focuses on failure metadata like code and error_data.

Sources: src/flext_tests/_utilities/_matchers/_that_parts/that_part_05.py:25-45, src/flext_tests/_utilities/_matchers/_result_parts/result_part_03.py:72-80

Deep Match Results

For structural comparisons, the system produces a DeepMatchResult to track the exact location and reason for discrepancies.

Field	Description
path	Dotted path where the match occurred.
expected	The value or predicate that was expected.
actual	The actual value found at the path.
matched	Boolean indicating success.
reason	Technical description of the failure.

Sources: src/flext_tests/_models/_matchers_parts/matchers_part_03.py:56-71

Conclusion

The Fluent Matchers API provides a robust and type-safe infrastructure for testing within the FLEXT ecosystem. By combining declarative rules with deep structure navigation and specialized result handling, it enables highly expressive assertions that are both readable and maintainable. Its core strength lies in the tm namespace, which abstracts away the complexity of path extraction and multi-stage validation into a consistent developer experience.