Skip to content

Non test cause

non_test_cause

Name the cause of a pytest red that no test failure explains.

A run that collects tests, reports zero failed and zero errors yet exits non-zero has a cause the counters cannot name: a coverage threshold, a usage error, an empty collection, an interruption, an internal error, or a plugin blowing up at session teardown. This module classifies that cause from the exit code and the captured output alone -- no I/O, no clock, no randomness -- so a report can explain the red without re-running pytest by hand.

NonTestCause

Bases: BaseModel

Machine-readable cause of a red no test failure accounts for.

Source code in packages/axm-audit/src/axm_audit/core/non_test_cause.py
Python
74
75
76
77
78
79
80
81
82
83
84
class NonTestCause(BaseModel):  # type: ignore[explicit-any]
    """Machine-readable cause of a red no test failure accounts for."""

    code: NonTestCauseCode
    """Stable identifier of the cause, safe to branch on."""

    summary: str
    """One-line human explanation, quoting the decisive figure when there is one."""

    excerpt: str
    """Bounded head of the captured subprocess output backing the verdict."""
code instance-attribute

Stable identifier of the cause, safe to branch on.

excerpt instance-attribute

Bounded head of the captured subprocess output backing the verdict.

summary instance-attribute

One-line human explanation, quoting the decisive figure when there is one.

classify_non_test_cause(*, return_code, failed, errors, stdout, stderr)

Name the non-test cause of a pytest exit, or None when there is none.

Returns None for a green exit and for a red the test counters already explain (failed or errors non-zero) -- there is nothing left to diagnose. Otherwise the exit code is dispatched first (it is authoritative when pytest sets it), then the captured output is pattern-matched for the ambiguous exit 1. Classification is fail-open: an unrecognised output is reported as unknown carrying its excerpt, never raised and never silently dropped.

Source code in packages/axm-audit/src/axm_audit/core/non_test_cause.py
Python
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
def classify_non_test_cause(
    *,
    return_code: int,
    failed: int,
    errors: int,
    stdout: str,
    stderr: str,
) -> NonTestCause | None:
    """Name the non-test cause of a pytest exit, or ``None`` when there is none.

    Returns ``None`` for a green exit and for a red the test counters already
    explain (``failed`` or ``errors`` non-zero) -- there is nothing left to
    diagnose. Otherwise the exit code is dispatched first (it is authoritative
    when pytest sets it), then the captured output is pattern-matched for the
    ambiguous exit 1. Classification is fail-open: an unrecognised output is
    reported as ``unknown`` carrying its excerpt, never raised and never
    silently dropped.
    """
    if return_code == 0 or failed > 0 or errors > 0:
        return None

    captured = f"{stdout}\n{stderr}"
    known = _EXIT_CODE_CAUSES.get(return_code)
    if known is not None:
        code, summary = known
        return NonTestCause(
            code=code,
            summary=summary,
            excerpt=_truncate_excerpt(captured) or summary,
        )

    coverage = _coverage_cause(captured)
    if coverage is not None:
        return coverage

    teardown = _teardown_cause(captured)
    if teardown is not None:
        return teardown

    fallback = f"pytest exited with code {return_code} without any reported failure"
    return NonTestCause(
        code="unknown",
        summary=fallback,
        excerpt=_truncate_excerpt(captured) or fallback,
    )