pytest-why 0.1.0__py3-none-any.whl

pytest_why/__init__.py

@@ -0,0 +1,3 @@
+"""pytest-why: concise, deterministic explanations for pytest failures."""
+
+__version__ = "0.1.0"

pytest_why/classifier.py

@@ -0,0 +1,130 @@
+"""Deterministic pytest failure classification."""
+
+from typing import Any, Dict, Optional
+
+
+BROWSER_AUTOMATION_HINT = (
+    "Browser automation is involved. Verify selectors, waits, page load timing, "
+    "and whether the element is visible before interaction."
+)
+
+
+def _contains_any(text: str, needles: tuple[str, ...]) -> bool:
+    lowered = text.lower()
+    return any(needle.lower() in lowered for needle in needles)
+
+
+def _with_browser_hint(hint: str, longreprtext: str) -> str:
+    browser_terms = (
+        "selenium",
+        "webdriver",
+        "NoSuchElementException",
+        "StaleElementReferenceException",
+        "playwright",
+        "locator",
+        "page.",
+    )
+    if _contains_any(longreprtext, browser_terms):
+        return f"{hint} {BROWSER_AUTOMATION_HINT}"
+    return hint
+
+
+def classify_failure(
+    nodeid: str,
+    phase: str,
+    longreprtext: str,
+    duration: Optional[float] = None,
+) -> Dict[str, Any]:
+    """Classify a pytest failure and return its explanation fields."""
+    text = longreprtext or ""
+
+    is_fixture_failure = phase == "setup" and (
+        "ScopeMismatch" in text
+        or "recursive dependency involving fixture" in text
+        or "recursive fixture dependency" in text
+        or ("fixture" in text.lower() and "not found" in text.lower())
+    )
+
+    if is_fixture_failure:
+        result = {
+            "type": "fixture_error",
+            "title": "Fixture error",
+            "explanation": (
+                "Pytest could not prepare the test because a fixture is missing, "
+                "has an incompatible scope, or depends on itself."
+            ),
+            "hint": (
+                "Check the fixture name, where it is defined, its scope, and its "
+                "dependency chain."
+            ),
+        }
+    elif _contains_any(
+        text,
+        ("ImportError", "ModuleNotFoundError", "cannot import name", "No module named"),
+    ):
+        result = {
+            "type": "import_error",
+            "title": "Import error",
+            "explanation": (
+                "Python could not import a module or symbol required while collecting "
+                "or running this test."
+            ),
+            "hint": (
+                "Verify the package is installed, the import path is correct, and the "
+                "symbol exists without a circular import."
+            ),
+        }
+    elif _contains_any(
+        text,
+        ("Timeout", "TimeoutError", "timed out", "pytest-timeout", "Failed: Timeout"),
+    ):
+        result = {
+            "type": "timeout",
+            "title": "Timeout",
+            "explanation": (
+                "The test exceeded a time limit or waited too long for an operation "
+                "to complete."
+            ),
+            "hint": (
+                "Find the blocked operation, replace fixed sleeps with bounded waits, "
+                "and confirm external dependencies respond."
+            ),
+        }
+    elif _contains_any(
+        text,
+        (
+            "AssertionError",
+            "E       assert",
+            "Differing items",
+            "Left contains",
+            "Right contains",
+        ),
+    ):
+        result = {
+            "type": "assertion_mismatch",
+            "title": "Assertion mismatch",
+            "explanation": (
+                "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."
+            ),
+        }
+    else:
+        result = {
+            "type": "unknown_failure",
+            "title": "Unknown failure",
+            "explanation": (
+                "The failure does not match a known pytest-why pattern, so the "
+                "traceback remains the best source of detail."
+            ),
+            "hint": (
+                "Start at the last application frame in the traceback and inspect the "
+                "inputs and state immediately before the exception."
+            ),
+        }
+
+    result["hint"] = _with_browser_hint(result["hint"], text)
+    return result

pytest_why/plugin.py

@@ -0,0 +1,76 @@
+"""Pytest hooks for pytest-why."""
+
+from pathlib import Path
+from typing import Any, Dict, List
+
+import pytest
+
+from .classifier import classify_failure
+from .reporter import write_html_report, write_markdown_report
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    group = parser.getgroup("pytest-why")
+    group.addoption(
+        "--why",
+        action="store_true",
+        default=False,
+        help="Explain failures and write pytest-why Markdown and HTML reports.",
+    )
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    if config.getoption("--why"):
+        config.pluginmanager.register(WhyPlugin(), "pytest-why-runtime")
+
+
+class WhyPlugin:
+    def __init__(self) -> None:
+        self.failures: List[Dict[str, Any]] = []
+
+    def _record_failure(self, report: Any, phase: str) -> None:
+        if not report.failed:
+            return
+
+        duration = getattr(report, "duration", None)
+        classification = classify_failure(
+            nodeid=report.nodeid,
+            phase=phase,
+            longreprtext=report.longreprtext,
+            duration=duration,
+        )
+        self.failures.append(
+            {
+                "nodeid": report.nodeid,
+                "phase": phase,
+                "duration": duration,
+                "longreprtext": report.longreprtext,
+                **classification,
+            }
+        )
+
+    def pytest_runtest_logreport(self, report: pytest.TestReport) -> None:
+        self._record_failure(report, report.when)
+
+    def pytest_collectreport(self, report: pytest.CollectReport) -> None:
+        self._record_failure(report, "collect")
+
+    def pytest_terminal_summary(
+        self,
+        terminalreporter: pytest.TerminalReporter,
+        exitstatus: int,
+        config: pytest.Config,
+    ) -> None:
+        terminalreporter.section("pytest-why: failure explanations")
+        terminalreporter.write_line(f"Total failures: {len(self.failures)}")
+        for failure in self.failures:
+            terminalreporter.write_line(
+                f"{failure['title']}: {failure['nodeid']} ({failure['phase']})"
+            )
+            terminalreporter.write_line(f"  Why: {failure['explanation']}")
+            terminalreporter.write_line(f"  Hint: {failure['hint']}")
+
+        report_dir = Path.cwd()
+        write_markdown_report(self.failures, report_dir / "pytest-why-report.md")
+        write_html_report(self.failures, report_dir / "pytest-why-report.html")
+        terminalreporter.write_line("Reports: pytest-why-report.md, pytest-why-report.html")

pytest_why/reporter.py

@@ -0,0 +1,147 @@
+"""Markdown and HTML report writers."""
+
+from html import escape
+from pathlib import Path
+from typing import Any, Iterable, Mapping, Union
+
+
+Failure = Mapping[str, Any]
+PathLike = Union[str, Path]
+
+
+def _duration(failure: Failure) -> str:
+    duration = failure.get("duration")
+    if duration is None:
+        return "n/a"
+    return f"{float(duration):.3f}s"
+
+
+def _backtick_fence(content: str) -> str:
+    longest_run = 0
+    current_run = 0
+    for character in content:
+        if character == "`":
+            current_run += 1
+            longest_run = max(longest_run, current_run)
+        else:
+            current_run = 0
+    return "`" * max(3, longest_run + 1)
+
+
+def write_markdown_report(
+    failures: Iterable[Failure],
+    path: PathLike = "pytest-why-report.md",
+) -> None:
+    """Write a human-readable Markdown failure report."""
+    items = list(failures)
+    lines = [
+        "# pytest-why failure explanations",
+        "",
+        f"**Total failures:** {len(items)}",
+        "",
+    ]
+
+    for index, failure in enumerate(items, start=1):
+        traceback = str(failure.get("longreprtext", "")).rstrip()
+        fence = _backtick_fence(traceback)
+        lines.extend(
+            [
+                f"## {index}. `{failure['nodeid']}`",
+                "",
+                f"- **Phase:** `{failure['phase']}`",
+                f"- **Type:** `{failure['type']}` - {failure['title']}",
+                f"- **Duration:** {_duration(failure)}",
+                "",
+                f"**Why:** {failure['explanation']}",
+                "",
+                f"**Hint:** {failure['hint']}",
+                "",
+                "<details>",
+                "<summary>Raw traceback</summary>",
+                "",
+                f"{fence}text",
+                traceback,
+                fence,
+                "",
+                "</details>",
+                "",
+            ]
+        )
+
+    Path(path).write_text("\n".join(lines), encoding="utf-8")
+
+
+def write_html_report(
+    failures: Iterable[Failure],
+    path: PathLike = "pytest-why-report.html",
+) -> None:
+    """Write a standalone HTML failure report."""
+    items = list(failures)
+    cards = []
+    for failure in items:
+        cards.append(
+            """
+            <article class="card">
+              <h2>{nodeid}</h2>
+              <div class="meta">
+                <span>Phase: <code>{phase}</code></span>
+                <span>Type: <code>{type}</code> - {title}</span>
+                <span>Duration: {duration}</span>
+              </div>
+              <h3>Why</h3>
+              <p>{explanation}</p>
+              <h3>Hint</h3>
+              <p>{hint}</p>
+              <details>
+                <summary>Raw traceback</summary>
+                <pre>{traceback}</pre>
+              </details>
+            </article>
+            """.format(
+                nodeid=escape(str(failure["nodeid"])),
+                phase=escape(str(failure["phase"])),
+                type=escape(str(failure["type"])),
+                title=escape(str(failure["title"])),
+                duration=escape(_duration(failure)),
+                explanation=escape(str(failure["explanation"])),
+                hint=escape(str(failure["hint"])),
+                traceback=escape(str(failure.get("longreprtext", ""))),
+            )
+        )
+
+    document = """<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>pytest-why failure explanations</title>
+  <style>
+    :root {{ color-scheme: light dark; }}
+    body {{ font-family: system-ui, sans-serif; max-width: 960px; margin: 0 auto;
+            padding: 2rem; line-height: 1.5; background: #f6f7f9; color: #18202a; }}
+    header {{ margin-bottom: 1.5rem; }}
+    .card {{ background: white; border: 1px solid #d9dee5; border-radius: 10px;
+             padding: 1.25rem; margin: 1rem 0; box-shadow: 0 2px 8px #0000000d; }}
+    .card h2 {{ overflow-wrap: anywhere; margin-top: 0; }}
+    .meta {{ display: flex; flex-wrap: wrap; gap: .5rem 1.5rem; color: #4b5563; }}
+    code, pre {{ font-family: ui-monospace, SFMono-Regular, Consolas, monospace; }}
+    pre {{ overflow: auto; padding: 1rem; border-radius: 6px; background: #111827;
+           color: #e5e7eb; white-space: pre-wrap; }}
+    summary {{ cursor: pointer; font-weight: 600; }}
+    @media (prefers-color-scheme: dark) {{
+      body {{ background: #111827; color: #e5e7eb; }}
+      .card {{ background: #1f2937; border-color: #374151; }}
+      .meta {{ color: #cbd5e1; }}
+    }}
+  </style>
+</head>
+<body>
+  <header>
+    <h1>pytest-why: failure explanations</h1>
+    <p><strong>Total failures:</strong> {count}</p>
+  </header>
+  <main>{cards}</main>
+</body>
+</html>
+""".format(count=len(items), cards="".join(cards))
+    Path(path).write_text(document, encoding="utf-8")

pytest_why-0.1.0.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: pytest-why
+Version: 0.1.0
+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.
+
+## Viral demo
+
+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.
+
+The MVP is deterministic and local. No LLM or network connection is required.
+
+**Stop doomscrolling tracebacks. Run pytest --why.**

pytest_why-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pytest_why/__init__.py,sha256=nTl0qlGDZO5YClO-pUfZCXNUPI2FN-4nwQzS9qDcRGg,98
+pytest_why/classifier.py,sha256=owIQGXM8mg8uYPMR4GxzEb0qU8e4m-sy9FQfpehtWC8,4212
+pytest_why/plugin.py,sha256=X-VaWHQEASfHcaQDcGY3aOJc87pKL6bq7IOfhnTQMcY,2547
+pytest_why/reporter.py,sha256=a-nTYF9fRHtQA_un60Z7vmNPQ69C7J4FvQxaBlU4Tis,4844
+pytest_why-0.1.0.dist-info/licenses/LICENSE,sha256=XmPzRh-kKDeQQez3kovjZKId7D2OYf5gZwtxolmjHF0,1080
+pytest_why-0.1.0.dist-info/METADATA,sha256=GTqTROj0AaVYGF9rKuCvo5Bo7IQSrmPGlRsmIU3Cheg,3242
+pytest_why-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pytest_why-0.1.0.dist-info/entry_points.txt,sha256=t4CtYc-h5dGN-9iRyf81NL-sPSyY7Xj84Y8yEO-wMqw,35
+pytest_why-0.1.0.dist-info/top_level.txt,sha256=n6uxzE_N4YpeRE8ovmIOZFIamBeIQpXEvca5G8FCYA4,11
+pytest_why-0.1.0.dist-info/RECORD,,

pytest_why-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pytest_why-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+why = pytest_why.plugin

pytest_why-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pytest-why contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pytest_why-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pytest_why