File Assertions & Comparisons

Relevant source files

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

• src/flext_tests/_utilities/_files/_assertions.py
• src/flext_tests/_utilities/_files/_comparison_parts/comparison_part_01.py
• src/flext_tests/_utilities/_files/_comparison_parts/comparison_part_02.py
• src/flext_tests/_models/_filesystem_parts/filesystem_part_01.py
• src/flext_tests/_models/_filesystem_parts/filesystem_part_02.py
• src/flext_tests/_utilities/_files/_info.py

The File Assertions & Comparisons module provides a robust set of utilities for validating filesystem states and comparing file data within the FLEXT ecosystem. It consolidates multiple validation checks—such as existence, type, permissions, and emptiness—into unified assertion interfaces, while offering sophisticated comparison modes for raw content, line-by-line matching, and deep structural analysis of serialized data.

This system is designed to provide high-level abstractions for test infrastructure, allowing developers to perform complex file validations with minimal boilerplate. It integrates tightly with the project's model layer to ensure type safety and consistent parameter validation across all filesystem operations.

Sources: src/flext_tests/_utilities/_files/_assertions.py, src/flext_tests/_utilities/_files/_comparison_parts/comparison_part_02.py

Unified File Assertions

The module provides a generalized assertion interface through the FlextTestsFilesAssertionsMixin. The primary method, assert_exists, consolidates various checks that were previously separate, such as file vs. directory checks, readability, and emptiness validations.

Assertion Logic Flow

The following diagram illustrates how the assert_exists method processes a path against multiple validation criteria:

The assertion process ensures that the path is not only present but also conforms to the expected structural and permission requirements defined in the parameters.
Sources: src/flext_tests/_utilities/_files/_assertions.py:17-64

Assertion Parameters

Assertions are configured using the AssertExistsParams model, which supports the following validations:

Parameter	Type	Description
is_file	bool | None	Asserts the path is a file when True.
is_dir	bool | None	Asserts the path is a directory when True.
not_empty	bool | None	Asserts the file has content or directory is not empty.
readable	bool | None	Asserts the current process has read permissions.
writable	bool | None	Asserts the current process has write permissions.

Sources: src/flext_tests/_models/_filesystem_parts/filesystem_part_02.py:118-135

File Comparison Engine

The comparison engine, implemented in FlextTestsFilesComparisonMixin, supports multiple modes for evaluating the equality of two files. It handles both flat files and structured data (JSON/YAML).

Comparison Modes

The system supports the following modes via CompareParams:

• CONTENT: Direct string comparison of the entire file.
• SIZE: Compares file sizes in bytes.
• HASH: Compares SHA-256 digests of both files.
• LINES: Performs a line-by-line comparison, allowing for normalization of whitespace or case.

Sources: src/flext_tests/_utilities/_files/_comparison_parts/comparison_part_02.py:53-73

Deep Structured Comparison

When deep=True is specified and the files are in JSON or YAML format, the engine attempts a structural comparison rather than a raw text match.

Structural comparison allows for ignoring specific keys (e.g., timestamps or dynamic IDs) that might otherwise cause a text-based comparison to fail.
Sources: src/flext_tests/_utilities/_files/_comparison_parts/comparison_part_02.py:101-140, src/flext_tests/_utilities/_files/_comparison_parts/comparison_part_01.py:31-64

Comparison Configuration

The CompareParams model defines how two files are evaluated:

Field	Type	Default	Description
mode	str	"content"	The primary metric for comparison (size, hash, lines, etc).
ignore_ws	bool	False	Strip whitespace before comparing.
ignore_case	bool	False	Perform case-insensitive comparison.
pattern	str | None	None	If provided, checks if this pattern exists in both files.
deep	bool	True	Enable structural parsing for JSON/YAML.
keys	StrSequence | None	None	Specific keys to include in structural comparison.
exclude_keys	StrSequence | None	None	Specific keys to ignore in structural comparison.

Sources: src/flext_tests/_models/_filesystem_parts/filesystem_part_02.py:54-91

File Information & Metadata Extraction

The FlextTestsFilesInfoMixin provides the info() method, which generates a comprehensive FileInfo model for a given path. This is used to gather diagnostic data about files during test execution.

Metadata Components

The FileInfo model includes:

• Physical Stats: Size, timestamps (created, modified), and Unix permissions.
• Text Analysis: Line counts, detected encoding, and the first line of the file.
• Format Detection: Identifies file types (JSON, YAML, CSV) and provides a fmt label.
• Content Metadata: If parse_content is enabled, it extracts format-specific stats like key_count (for dicts), item_count (for lists), or row_count (for CSVs).

Sources: src/flext_tests/_models/_filesystem_parts/filesystem_part_01.py:19-86, src/flext_tests/_utilities/_files/_info.py:35-85

Model Validation

The information helper can also perform Pydantic model validation on file contents. If a validate_model is provided, the ContentMeta will include:

• model_valid: Boolean indicating if the content matches the schema.
• model_name: The name of the model class used for validation.

Sources: src/flext_tests/_utilities/_files/_info.py:126-159

Technical Summary

The File Assertions & Comparisons module serves as a critical utility layer for the FLEXT test infrastructure. By leveraging Pydantic models for parameter validation and providing multiple levels of comparison (from raw bytes to filtered structured data), it ensures that filesystem-related tests are both expressive and accurate. The consolidation of assertions into a single assert_exists entry point simplifies the validation of complex file properties and access rights.