FailExtract Documentation

Python Version License: Apache 2.0

FailExtract is a lightweight Python library for extracting and analyzing pytest test failures. It provides automatic failure context capture with minimal overhead and supports multiple output formats for different workflows.

Core Philosophy: Progressive enhancement with honest documentation. Start simple, grow sophisticated as needed.

Key Features

  • Zero Dependencies: Core functionality uses only Python standard library

  • Automatic Context Capture: Local variables, stack traces, and pytest fixtures

  • Multiple Output Formats: JSON, Markdown, XML, CSV (built-in) + YAML (optional)

  • Performance Awareness: <5% overhead in production, configurable for different environments

  • pytest Integration: Seamless integration with existing test suites

  • Memory Management: Built-in limits and monitoring for long-running test suites

Quick Start

Installation (30 seconds):

pip install failextract

First Use (2 minutes):

from failextract import extract_on_failure, FailureExtractor, OutputConfig

@extract_on_failure
def test_example():
    user_data = {"name": "John", "age": 25}
    assert user_data["name"] == "Jane", "Name mismatch"

# Run test (it will fail and be captured)
try:
    test_example()
except AssertionError:
    pass

# Generate report
extractor = FailureExtractor()
config = OutputConfig("failures.json")
extractor.save_report(config)

What just happened? FailExtract captured the failure context (local variables, exception details) and saved it as a JSON report. The user_data dictionary is now available for debugging.

Documentation Structure

This documentation follows the DiΓ‘taxis framework for optimal learning and reference:

πŸ“š Tutorials

πŸ› οΈ How-To Guides

πŸ’­ Discussions

πŸ“– Reference

Getting Started

New to FailExtract?

  1. Install: How to Install FailExtract (2 minutes)

  2. Learn: Getting Started with FailExtract (5 minutes)

  3. Explore: Working with Multiple Output Formats (10 minutes)

Have a specific problem?

Want to understand the design?

Need technical details?

Why FailExtract?

The Problem: Test failures often lack sufficient context for efficient debugging. Stack traces show what failed, but not the state that led to the failure.

The Solution: FailExtract automatically captures comprehensive failure context - local variables, fixture values, and execution environment - with minimal performance impact.

The Result: Faster debugging, better failure analysis, and improved test reliability through actionable failure reports.

Design Philosophy:

  • Progressive Enhancement - Start simple, add complexity only when needed

  • Honest Documentation - Document what actually works, not what we wish worked

  • Performance Awareness - Explicit trade-offs between detail and speed

  • Zero Dependencies - Core functionality works everywhere Python runs

Production Ready

FailExtract is designed for real-world usage:

βœ… Production-tested with 96% test coverage and comprehensive test suite
βœ… Performance-optimized with <5% overhead in production mode
βœ… Memory-managed with configurable limits for long-running test suites
βœ… Thread-safe singleton architecture for concurrent test execution
βœ… CI/CD ready with command-line interface and automation support

Community and Support

Get Help

Project Links

Contributing

Contributions welcome! See Development Journey: From Empty Module to Production Tool for the development philosophy and approach.

Meta

Indices and Tables