Metadata-Version: 2.4
Name: pytest-why
Version: 0.1.1
Summary: A pytest plugin that explains failing tests like a senior engineer.
Author: pytest-why contributors
License-Expression: MIT
Project-URL: Homepage, https://www.dhirajdas.dev
Project-URL: Repository, https://github.com/godhiraj-code/pytest-why
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pytest>=7
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# pytest-why

> A pytest plugin that explains failing tests like a senior engineer.

`pytest-why` turns common pytest failures into concise explanations and practical
next steps. It runs locally, adds no noise to normal test runs, and creates
shareable Markdown and HTML reports when you ask for them.

## Install

```bash
python -m pip install pytest-why
```

For local development:

```bash
python -m pip install -e .[dev]
```

## Usage

Run pytest with one extra flag:

```bash
python -m pytest --why
```

Without `--why`, the plugin does nothing and creates no report files.

## Example

Given:

```python
def test_math():
    assert 2 + 2 == 5
```

Run:

```bash
pytest --why
```

Sample output:

```text
================ pytest-why: failure explanations ================
Total failures: 1
Assertion mismatch: test_math.py::test_math (call)
  Why: The code ran, but the observed value or state did not match what the test expected.
  Hint: Compare the expected and actual values near the final assertion, then trace where they first diverge.
Reports: pytest-why-report.md, pytest-why-report.html
```

## Reports

Each `--why` run writes:

- `pytest-why-report.md` for pull requests, issue trackers, and terminals
- `pytest-why-report.html` for a styled, standalone browser view

Both reports include the failing test, pytest phase, classification, duration,
explanation, hint, and the complete raw traceback.

## Supported classifications

- **Assertion mismatch**: expected and actual values differ
- **Import error**: a module or symbol could not be imported
- **Fixture error**: missing fixtures, scope mismatches, or recursive dependencies
- **Timeout**: a test or operation exceeded its time limit
- **Unknown failure**: deterministic fallback with traceback-first guidance

Selenium and Playwright tracebacks also receive a focused browser automation
hint covering selectors, waits, page timing, and element visibility.

**Stop doomscrolling tracebacks. Run pytest --why.**
