Pytest Reporter

Relevant source files

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

• reporters/pytest/tdd_guard_pytest/pytest_reporter.py
• reporters/pytest/pyproject.toml
• reporters/pytest/tests/test_pytest_reporter.py
• reporters/pytest/tests/test_project_root.py
• reporters/test/reporters.integration.test.ts
• reporters/test/factories/pytest.ts
• README.md

Introduction

The Pytest Reporter is a dedicated plugin for the pytest framework within the TDD Guard ecosystem. Its primary purpose is to capture test execution results and export them into a structured JSON format that TDD Guard's core validation logic can analyze. By monitoring the test lifecycle, it identifies passing tests, assertion failures, and collection errors (such as import issues), ensuring that the AI-driven TDD enforcement has accurate data regarding the current state of the codebase.

Sources: reporters/pytest/pyproject.toml, README.md, reporters/pytest/tdd_guard_pytest/pytest_reporter.py

Architecture and Core Logic

The reporter is implemented as a standard pytest plugin (tdd-guard-pytest) that hooks into pytest's internal reporting system. It maintains an internal state of test results throughout the session and flushes them to a persistent file upon completion.

Key Components

• TDDGuardPytestPlugin: The core class managing the lifecycle of test collection and reporting.
• Result Capture: Utilizes pytest hooks to intercept reports during the call phase and the collection phase.
• Storage Management: Handles the creation of the .claude/tdd-guard/data/ directory and writes the test.json artifact.

Sources: reporters/pytest/tdd_guard_pytest/pytest_reporter.py:9-15, reporters/pytest/tests/test_pytest_reporter.py:14-20

Data Flow Diagram

The following diagram illustrates how test results flow from pytest execution into the TDD Guard storage.

The flow ensures that results are accumulated in memory and only serialized once the entire test suite has finished executing.

Sources: reporters/pytest/tdd_guard_pytest/pytest_reporter.py:22-75, reporters/pytest/tests/test_pytest_reporter.py:76-110

Hook Implementations

Test Result Logging

The reporter implements pytest_runtest_logreport to capture the outcome of individual test cases. It specifically filters for the call phase to avoid duplicate reporting from setup or teardown.

• State Mapping: Maps pytest results to TDD Guard states: passed or failed.
• Error Capturing: For failed tests, it extracts the longrepr (representation of the failure) as the error message.

Sources: reporters/pytest/tdd_guard_pytest/pytest_reporter.py:22-35, reporters/pytest/tests/test_pytest_reporter.py:41-55

Collection Errors

The pytest_collectreport hook captures errors that occur before tests even run, such as ImportError or SyntaxError. This is critical for TDD Guard to identify when a test file cannot be loaded because a required implementation file is missing.

Sources: reporters/pytest/tdd_guard_pytest/pytest_reporter.py:37-47, reporters/pytest/tests/test_pytest_reporter.py:65-74

Configuration and Project Root

The reporter supports a configurable project root to ensure results are saved correctly in monorepos or when tests are run from subdirectories.

Option	Description	Default
tdd_guard_project_root	Absolute path to the project root where results should be saved.	Current Working Directory

Sources: reporters/pytest/pyproject.toml:44-46, reporters/pytest/tests/test_project_root.py:112-130

Project Root Resolution Logic

The reporter validates the tdd_guard_project_root configuration. If the provided path is relative or if the current working directory is not a descendant of the configured root, it falls back to the default behavior.

Sources: reporters/pytest/tests/test_project_root.py:35-55

Data Model

The output generated by the reporter is a JSON object structured for consumption by the TDD Guard core.

Output Structure Example

{
  "testModules": [
    {
      "moduleId": "test_calculator.py",
      "tests": [
        {
          "name": "test_add",
          "fullName": "test_calculator.py::test_add",
          "state": "failed",
          "errors": [
            {
              "message": "AssertionError: assert 5 == 6"
            }
          ]
        }
      ]
    }
  ]
}

Sources: reporters/pytest/tests/test_pytest_reporter.py:112-134, test/utils/factories/scenarios/languages/python.ts:8-135

Integration with TDD Guard

As a reporter, it is registered via the pytest11 entry point in the package configuration, allowing pytest to discover and load it automatically when the package is installed.

[project.entry-points."pytest11"]
tdd-guard = "tdd_guard_pytest.pytest_reporter"

Sources: reporters/pytest/pyproject.toml:41-42

Summary

The Pytest Reporter serves as the bridge between the Python testing ecosystem and TDD Guard. By hooking into pytest_runtest_logreport and pytest_collectreport, it provides the fine-grained failure data (including NameErrors and AssertionErrors) required to enforce TDD cycles. Its ability to respect a configured project_root makes it robust for various project structures, ensuring the test.json artifact is always accessible to the Claude Code hooks.