Crashtest

Crashtest is a small Python library that makes exception handling and inspection easier. It wraps a raised exception and its traceback in an Inspector that exposes the exception, its message, and a navigable collection of frames, each giving structured access to the file, line, function and local variables at that point in the stack.

It also defines a lightweight solution-provider contract, letting tools attach human-readable explanations and remedies to specific exception types. Crashtest is best known as the foundation for the rich error output in Poetry and Cleo.

What You Get

• An Inspector that wraps an exception and exposes its message, type and frames.
• A frame collection with structured access to file, line, function and local variables.
• A solution-provider contract for attaching explanations and fixes to exception types.
• A dependency-free foundation for building rich, readable error reporters.

Common Use Cases

• Rendering rich, context-aware tracebacks in CLI tools.
• Inspecting stack frames and locals programmatically for diagnostics.
• Attaching suggested fixes to known exception types via solution providers.

Under The Hood

Architecture

Crashtest is a tiny library: an Inspector wraps an exception and lazily builds a FrameCollection from its __traceback__, where each Frame wraps a native traceback frame and exposes filename, lineno, function and locals; a contracts/solution_providers package defines the interfaces for mapping exceptions to human-readable solutions.

Tech Stack

Pure Python with no runtime dependencies, packaged for modern Python versions; developed with pytest (tests/) and used as a building block by Poetry and Cleo for rich error rendering.

Code Quality

Small, focused and readable - a handful of modules under crashtest/ with a matching test suite covering the inspector, frames and solution-provider repository; the code is stable and low-churn, reflecting its role as a settled foundational dependency.

API Design

The API is minimal and predictable - construct an Inspector(exception) and iterate frames - which makes it easy to build custom error reporters, though it is deliberately a low-level primitive rather than a full traceback-formatting tool.