Pytest Plugin Injection

Relevant source files

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

• src/flext_tests/conftest_plugin.py
• src/flext_tests/_fixtures/markdown_validation.py
• pyproject.toml
• tests/unit/test_enforcement_plugin.py
• src/flext_tests/_validator/_markdown_parts/markdown_part_01.py
• src/flext_tests/_constants/_validator_parts/validator_part_02.py

Pytest Plugin Injection in the flext-tests infrastructure provides a standardized mechanism for loading shared test utilities, enforcement rules, and validation logic across the FLEXT ecosystem. The system utilizes pytest11 entry points and explicit plugin delegation to ensure that projects inheriting from flext-tests receive a consistent suite of testing tools, including automated markdown validation and runtime architectural enforcement.

The architecture is designed to prevent double-registration of CLI options while maintaining a single canonical owner for shared fixtures. It supports both "auto-activation" within a workspace and explicit opt-in through project-level conftest.py configurations.

Sources: src/flext_tests/conftest_plugin.py:1-20, pyproject.toml:50-55

Architecture and Entry Points

The injection system primarily operates through two distinct paths: explicit registration in conftest.py and automatic discovery via pytest11 entry points defined in the project metadata.

Plugin Registration Paths

Registration Method	Target Module	Purpose
Explicit (conftest.py)	flext_tests.conftest_plugin	Wires canonical fixture modules like markdown validation and settings.
Entry Point (pytest11)	flext_tests.conftest_plugin	Named flext_tests for automated discovery.
Entry Point (pytest11)	flext_tests._fixtures.enforcement	Named flext_tests_enforcement for runtime rule enforcement.

Sources: src/flext_tests/conftest_plugin.py:5-15, pyproject.toml:52-54

Hook Delegation Flow

The core conftest_plugin.py does not implement logic directly but delegates to specialized fixture modules. This ensures that lazy initialization sees a single owner for each symbol, avoiding conflicts.

The diagram shows how Pytest discovers plugins and how the conftest_plugin delegates responsibility to internal modules.
Sources: src/flext_tests/conftest_plugin.py:12-20, tests/unit/test_enforcement_plugin.py:1-10

Enforcement Dispatcher

The Enforcement Dispatcher is injected via the flext_tests_enforcement entry point. It monitors test execution for architectural violations, such as FlextMroViolation (Method Resolution Order) warnings.

• Mechanism: It uses the pytest_warning_recorded hook to capture runtime enforcement warnings.
• Modes:
  • Standard: Records warnings and prints a summary in the terminal via pytest_terminal_summary.
  • Strict: When --flext-enforce-strict is provided, warnings are promoted to test failures.
• Auto-activation: The dispatcher requires workspace markers (like AGENTS.md) to become active, preventing noise in non-FLEXT environments.

Sources: tests/unit/test_enforcement_plugin.py:1-10, tests/unit/test_enforcement_plugin.py:58-70

Markdown Validation Plugin

This component provides automatic validation of Python code blocks within .md files. It integrates into the Pytest collection phase to treat markdown files as test items.

Configuration Options

The plugin adds custom CLI options to the Pytest parser to control validation behavior.

Option	Action	Default	Description
--markdown-docs	store_true	False	Enables validation of Python code blocks in .md files.

Sources: src/flext_tests/_fixtures/markdown_validation.py:27-37, src/flext_tests/_constants/_validator_parts/validator_part_02.py:146

Validation Lifecycle

When --markdown-docs is enabled, the plugin hooks into pytest_collect_file.

1. Collection: Identifies .md files containing Python code blocks using the regex ^```python\s*$\n(.*?)^```\s*$.
2. Item Creation: Creates a MarkdownCodeBlockItem for each valid file.
3. Execution: Runs FlextValidatorMarkdown.markdown() which performs:
   • Syntax Check: Uses compile(code, ..., "exec") to detect invalid Python.
   • Rule Enforcement: Checks for forbidden imports (e.g., Any, Optional from typing), missing from __future__ import annotations, and forbidden object annotations.

The sequence diagram illustrates the markdown validation process from file collection to violation reporting.
Sources: src/flext_tests/_fixtures/markdown_validation.py:86-98, src/flext_tests/_validator/_markdown_parts/markdown_part_01.py:35-85

Violation Rules

The injection system enforces specific rules during validation, identified by unique IDs.

Rule ID	Name	Description	Source File
MD-001	Syntax Error	Detected via compile() failure.	markdown_part_01.py
MD-002	Forbidden Import	Blocks imports like Any, Optional, or Union from typing.	markdown_part_01.py
MD-003	Missing Future	Requires from __future__ import annotations if type hints are present.	markdown_part_01.py
MD-004	Forbidden Annotation	Blocks the use of object as a type annotation.	markdown_part_01.py
ENFORCE-022	MRO Violation	Runtime check for Method Resolution Order consistency.	test_enforcement_plugin.py

Sources: src/flext_tests/_validator/_markdown_parts/markdown_part_01.py:61-150, tests/unit/test_enforcement_plugin.py:46-55

Summary

Pytest Plugin Injection in flext-tests facilitates a robust, automated testing environment. By leveraging pytest11 entry points and modular fixture delegation, it provides seamless integration of architectural enforcement and documentation validation. This ensures that all projects within the ecosystem adhere to the same technical standards and maintain high-quality documentation through automated code block verification.