Here's a cleaned-up version of your document in pretty Markdown that maintains all the key features while improving readability and formatting:

pytest-fixer Documentation

Overview

pytest-fixer is an AI-powered tool designed to automatically identify and fix failing pytest tests in Python projects. By combining OpenAI's GPT models with intelligent error analysis and Git-based change management, it provides a robust solution for testing automation.

Core Architecture

Component Structure

  1. PytestErrorFixer
  2. Orchestrates all components.

  3. Manages execution flow, state, initialization, and cleanup.

  4. TestRunner

  5. Discovers test files matching test_*.py.
  6. Executes individual tests or full test suites.

  7. Captures stdout, stderr, and results as standardized objects.

  8. ErrorProcessor

  9. Parses pytest output into structured data.
  10. Handles test failures, collection errors, and runtime issues.

  11. Extracts error context and details for fixing.

  12. DependencyMapper

  13. Analyzes imports and code references.
  14. Maps relationships between test and source files.

  15. Supports both relative and absolute imports.

  16. AIManager

  17. Manages OpenAI API interactions.
  18. Implements a temperature-based retry strategy.

  19. Constructs prompts and parses AI responses into actionable changes.

  20. StateManager

  21. Tracks execution progress and state.

  22. Handles checkpoints, recovery, and logs.

  23. ChangeHandler

  24. Applies, verifies, and reverts code changes.
  25. Manages logs and ensures smooth operations.

Component Interaction

graph TD
    TestRunner --> ErrorProcessor --> AIManager
    AIManager --> ChangeHandler
    ChangeHandler --> StateManager
    StateManager --> LogStore
    DependencyMapper --> PytestErrorFixer

Key Features

Test Processing

  • Automatic test discovery (excludes .venv).
  • Execution of individual test functions or files.
  • Dependency analysis and detailed error extraction.

AI Integration

  • OpenAI GPT model integration with retry mechanism:
    python initial_temperature = 0.4 temperature_increment = 0.1 max_retries = 3
  • Context-aware prompt construction, including:
  • Error details and stack traces.
  • Previous attempt history.
  • Code context and dependencies.
  • Test output and logs.

Interactive Modes

Operational modes for flexibility: - DISABLED: Fully automated.
- ON_FAILURE: Interactive on failures.
- ALWAYS: Always interactive.
- MANUAL: Triggered manually.

Interactive commands: - show: Display errors and changes.
- edit: Open changes in the default editor.
- apply: Apply and test changes.
- retry: Retry with higher temperature.
- prompt: Modify AI prompt.
- diff: Show Git differences.
- history: View change history.
- quit: Exit without changes.

State Management

  • Tracks session progress and checkpoints.
  • Logs state changes and error progression.

Git Integration

  • Creates isolated fix branches.
  • Handles branch lifecycle and change management.
  • Enables Git-based reversion and recovery.

Setup

Requirements

Python 3.8+
Git
OpenAI API Key
pytest

Installation

git clone https://github.com/your-repo/pytest-fixer.git
cd pytest-fixer
pip install -r requirements.txt

Configuration

Create a .env file:

OPENAI_API_KEY=your-api-key
MODEL_NAME=gpt-4o-mini
INITIAL_TEMPERATURE=0.4
TEMPERATURE_INCREMENT=0.1
MAX_RETRIES=3

Usage

python -m pytest_fixer.main /path/to/project [options]

Options:
  --initial-temperature FLOAT   Initial AI temperature (default: 0.4)
  --temperature-increment FLOAT Temperature increment (default: 0.1)
  --max-retries INT             Maximum fix attempts (default: 3)
  --model STRING                AI model (default: gpt-4o-mini)
  --debug                       Enable debug logging
  --manual-fix                  Enable manual fix mode

Error Handling

Error Propagation

  1. Component-level errors:
  2. Managed within components.
  3. Errors logged and propagated.

  4. State preserved when possible.

  5. System-level errors:

  6. Managed by PytestErrorFixer.
  7. Trigger session cleanup while preserving logs.

Recovery Mechanisms

  1. State Recovery:
  2. Checkpoint-based restoration.

  3. Log-based state reconstruction.

  4. Change Recovery:

  5. Git-based reversion.
  6. Preserves logs and session state.

Known Limitations

Technical

  • Assumes "main" branch in Git.
  • No parallel test execution.
  • Basic pytest plugin support.
  • OpenAI-specific AI integration.

Operational

  • Single-branch workflow.
  • Limited error pattern recognition.
  • No historical learning.

Best Practices

  1. Version Control:
  2. Use a clean working directory.
  3. Create dedicated fix branches.

  4. Review all changes before merging.

  5. Configuration:

  6. Use default temperatures initially.

  7. Enable debug mode for investigation.

  8. Monitoring:

  9. Track progress logs and state changes.

  10. Troubleshooting:

  11. Verify API keys, Git permissions, and pytest setup.

Support

For assistance: 1. Enable debug logging.
2. Check logs in ~/.pytest_fixer/logs.
3. Include the following in issues: - Error details.
- Logs.
- Steps to reproduce.
- Configuration details.

This version is streamlined for readability while keeping technical details intact. It uses headings, lists, code blocks, and diagrams for clarity and organization. Let me know if you'd like further tweaks!