Erste Version

This commit is contained in:
wittmannzl103469 committed 2026-11-04 21:01:26 +01:00
commit 782b1850a3
1641 files changed
+512713

No files matched your search

@@ -0,0 +1,258 @@
# mypy: allow-untyped-defs
"""Support for presenting detailed information in failing assertions."""
from __future__ import annotations
from collections.abc import Generator
import sys
from typing import Any
from typing import Protocol
from typing import TYPE_CHECKING
from _pytest.assertion import rewrite
from _pytest.assertion import truncate
from _pytest.assertion import util
from _pytest.assertion._typing import _AssertionTextDiffStyle
from _pytest.assertion._typing import NO_TRUNCATION_BUDGET
from _pytest.assertion._typing import TruncationBudget
from _pytest.assertion.rewrite import assertstate_key
from _pytest.config import Config
from _pytest.config import hookimpl
from _pytest.config.argparsing import Parser
from _pytest.nodes import Item
if TYPE_CHECKING:
from _pytest.main import Session
def pytest_addoption(parser: Parser) -> None:
group = parser.getgroup("debugconfig")
group.addoption(
"--assert",
action="store",
dest="assertmode",
choices=("rewrite", "plain"),
default="rewrite",
metavar="MODE",
help=(
"Control assertion debugging tools.\n"
"'plain' performs no assertion debugging.\n"
"'rewrite' (the default) rewrites assert statements in test modules"
" on import to provide assert expression information."
),
)
parser.addini(
"enable_assertion_pass_hook",
type="bool",
default=False,
help="Enables the pytest_assertion_pass hook. "
"Make sure to delete any previously generated pyc cache files.",
)
# ``int | str`` (not plain ``int``) for backward compatibility: INI files
# and ``-o`` overrides provide the value as a string.
parser.addini(
"truncation_limit_lines",
type=int | str,
default=None,
help="Set threshold of LINES after which truncation will take effect",
)
parser.addini(
"truncation_limit_chars",
type=int | str,
default=None,
help=("Set threshold of CHARS after which truncation will take effect"),
)
parser.addini(
"assertion_text_diff_style",
type=_AssertionTextDiffStyle,
default="ndiff",
help="Choose how pytest renders diffs for string equality assertions",
)
Config._add_verbosity_ini(
parser,
Config.VERBOSITY_ASSERTIONS,
help=(
"Specify a verbosity level for assertions, overriding the main level. "
"Higher levels will provide more detailed explanation when an assertion fails."
),
)
def pytest_configure(config: Config) -> None:
# Eagerly validate the value; it is only read lazily when an assertion fails.
config.getini("assertion_text_diff_style")
def register_assert_rewrite(*names: str) -> None:
"""Register one or more module names to be rewritten on import.
This function will make sure that this module or all modules inside
the package will get their assert statements rewritten.
Thus you should make sure to call this before the module is
actually imported, usually in your __init__.py if you are a plugin
using a package.
:param names: The module names to register.
"""
for name in names:
if not isinstance(name, str):
msg = "expected module names as *args, got {0} instead" # type: ignore[unreachable]
raise TypeError(msg.format(repr(names)))
rewrite_hook: RewriteHook
for hook in sys.meta_path:
if isinstance(hook, rewrite.AssertionRewritingHook):
rewrite_hook = hook
break
else:
rewrite_hook = DummyRewriteHook()
rewrite_hook.mark_rewrite(*names)
class RewriteHook(Protocol):
def mark_rewrite(self, *names: str) -> None: ...
class DummyRewriteHook:
"""A no-op import hook for when rewriting is disabled."""
def mark_rewrite(self, *names: str) -> None:
pass
class AssertionState:
"""State for the assertion plugin."""
def __init__(self, config: Config, mode) -> None:
self.mode = mode
self.trace = config.trace.root.get("assertion")
self.hook: rewrite.AssertionRewritingHook | None = None
def install_importhook(config: Config) -> rewrite.AssertionRewritingHook:
"""Try to install the rewrite hook, raise SystemError if it fails."""
config.stash[assertstate_key] = AssertionState(config, "rewrite")
config.stash[assertstate_key].hook = hook = rewrite.AssertionRewritingHook(config)
sys.meta_path.insert(0, hook)
config.stash[assertstate_key].trace("installed rewrite import hook")
def undo() -> None:
hook = config.stash[assertstate_key].hook
if hook is not None and hook in sys.meta_path:
sys.meta_path.remove(hook)
config.add_cleanup(undo)
return hook
def pytest_collection(session: Session) -> None:
# This hook is only called when test modules are collected
# so for example not in the managing process of pytest-xdist
# (which does not collect test modules).
assertstate = session.config.stash.get(assertstate_key, None)
if assertstate:
if assertstate.hook is not None:
assertstate.hook.set_session(session)
@hookimpl(wrapper=True, tryfirst=True)
def pytest_runtest_protocol(item: Item) -> Generator[None, object, object]:
"""Setup the pytest_assertrepr_compare and pytest_assertion_pass hooks.
The rewrite module will use util._reprcompare if it exists to use custom
reporting via the pytest_assertrepr_compare hook. This sets up this custom
comparison for the test.
"""
ihook = item.ihook
def callbinrepr(op, left: object, right: object) -> str | None:
"""Call the pytest_assertrepr_compare hook and prepare the result.
This uses the first result from the hook and then ensures the
following:
* Overly verbose explanations are truncated unless configured otherwise
(eg. if running in verbose mode).
* Embedded newlines are escaped to help util.format_explanation()
later.
* If the rewrite mode is used embedded %-characters are replaced
to protect later % formatting.
The result can be formatted by util.format_explanation() for
pretty printing.
"""
hook_result = ihook.pytest_assertrepr_compare(
config=item.config, op=op, left=left, right=right
)
for new_expl in hook_result:
if new_expl:
new_expl = truncate.materialize_with_truncation(new_expl, item.config)
# A truthy-but-empty iterable materialises to [], so re-check.
if new_expl:
new_expl = [line.replace("\n", "\\n") for line in new_expl]
res = "\n~".join(new_expl)
if item.config.getvalue("assertmode") == "rewrite":
res = res.replace("%", "%%")
return res
return None
saved_assert_hooks = util._reprcompare, util._assertion_pass
util._reprcompare = callbinrepr
util._config = item.config
if ihook.pytest_assertion_pass.get_hookimpls():
def call_assertion_pass_hook(lineno: int, orig: str, expl: str) -> None:
ihook.pytest_assertion_pass(item=item, lineno=lineno, orig=orig, expl=expl)
util._assertion_pass = call_assertion_pass_hook
try:
return (yield)
finally:
util._reprcompare, util._assertion_pass = saved_assert_hooks
util._config = None
def pytest_sessionfinish(session: Session) -> None:
assertstate = session.config.stash.get(assertstate_key, None)
if assertstate:
if assertstate.hook is not None:
assertstate.hook.set_session(None)
def pytest_assertrepr_compare(
config: Config, op: str, left: Any, right: Any
) -> list[str] | None:
if config.pluginmanager.has_plugin("terminalreporter"):
highlighter = config.get_terminal_writer()._highlight
else:
# Keep it plaintext when not using terminalrepoterer (#14377).
highlighter = util.dummy_highlighter
# When truncation is going to clip the explanation downstream, cap the
# comparison helpers' formatting at what the truncator will actually pull
# (the raw limits plus the footer slack) so no effort is spent formatting
# lines/chars that would be dropped anyway.
should_truncate, base_budget = truncate._get_truncation_parameters(config)
if should_truncate:
truncation_budget = TruncationBudget(
max_lines=base_budget.max_lines + truncate.TRUNCATION_FOOTER_LINES + 1
if base_budget.max_lines > 0
else 0,
max_chars=base_budget.max_chars + truncate.TRUNCATION_FOOTER_CHARS
if base_budget.max_chars > 0
else 0,
)
else:
truncation_budget = NO_TRUNCATION_BUDGET
lines = util.assertrepr_compare(
op=op,
left=left,
right=right,
verbose=config.get_verbosity(Config.VERBOSITY_ASSERTIONS),
highlighter=highlighter,
assertion_text_diff_style=config.getini("assertion_text_diff_style"),
truncation_budget=truncation_budget,
)
return truncate.materialize_with_truncation(lines, config) or None
@@ -0,0 +1,139 @@
from __future__ import annotations
from collections.abc import Iterator
import dataclasses
import pprint
from _pytest.assertion._compare_mapping import _compare_eq_mapping
from _pytest.assertion._compare_sequence import _compare_eq_iterable
from _pytest.assertion._compare_sequence import _compare_eq_sequence
from _pytest.assertion._compare_set import _compare_eq_set
from _pytest.assertion._guards import has_default_eq
from _pytest.assertion._guards import isattrs
from _pytest.assertion._guards import isdatacls
from _pytest.assertion._guards import isiterable
from _pytest.assertion._guards import ismapping
from _pytest.assertion._guards import isnamedtuple
from _pytest.assertion._guards import issequence
from _pytest.assertion._guards import isset
from _pytest.assertion._guards import istext
from _pytest.assertion._typing import _AssertionTextDiffStyle
from _pytest.assertion._typing import _HighlightFunc
from _pytest.assertion._typing import NO_TRUNCATION_BUDGET
from _pytest.assertion._typing import TruncationBudget
from _pytest.assertion.compare_text import _compare_eq_text
def _compare_eq_any(
left: object,
right: object,
highlighter: _HighlightFunc,
verbose: int,
assertion_text_diff_style: _AssertionTextDiffStyle,
truncation_budget: TruncationBudget = NO_TRUNCATION_BUDGET,
) -> Iterator[str]:
"""Yield the per-line explanation for ``left == right`` (without summary).
Yields nothing when no specialised explanation applies, so consumers
can stream the output and bail out early (e.g. for truncation) without
materialising the entire diff first.
"""
if istext(left) and istext(right):
yield from _compare_eq_text(
left,
right,
highlighter,
verbose,
assertion_text_diff_style,
truncation_budget,
)
else:
from _pytest.approx import Approx
# Although the common order should be obtained == approx(...), allow both ways.
if isinstance(right, Approx):
yield from right._repr_compare(left)
elif isinstance(left, Approx):
yield from left._repr_compare(right)
elif type(left) is type(right) and (
isdatacls(left) or isattrs(left) or isnamedtuple(left)
):
# Note: unlike dataclasses/attrs, namedtuples compare only the
# field values, not the type or field names. But this branch
# intentionally only handles the same-type case, which was often
# used in older code bases before dataclasses/attrs were available.
yield from _compare_eq_cls(
left,
right,
highlighter,
verbose,
assertion_text_diff_style,
)
elif issequence(left) and issequence(right):
yield from _compare_eq_sequence(left, right, highlighter, verbose)
elif isset(left) and isset(right):
yield from _compare_eq_set(left, right, highlighter, verbose)
elif ismapping(left) and ismapping(right):
yield from _compare_eq_mapping(
left, right, highlighter, verbose, truncation_budget
)
if isiterable(left) and isiterable(right):
yield from _compare_eq_iterable(
left, right, highlighter, verbose, truncation_budget
)
def _compare_eq_cls(
left: object,
right: object,
highlighter: _HighlightFunc,
verbose: int,
assertion_text_diff_style: _AssertionTextDiffStyle,
) -> Iterator[str]:
if not has_default_eq(left):
return
if isdatacls(left):
all_fields = dataclasses.fields(left)
fields_to_check = [info.name for info in all_fields if info.compare]
elif isattrs(left):
all_fields = left.__attrs_attrs__ # type: ignore[attr-defined]
fields_to_check = [field.name for field in all_fields if getattr(field, "eq")]
elif isnamedtuple(left):
fields_to_check = left._fields # type: ignore[attr-defined]
else:
assert False
indent = " "
same = []
diff = []
for field in fields_to_check:
if getattr(left, field) == getattr(right, field):
same.append(field)
else:
diff.append(field)
if same or diff:
yield ""
if same and verbose < 2:
yield f"Omitting {len(same)} identical items, use -vv to show"
elif same:
yield "Matching attributes:"
yield from highlighter(pprint.pformat(same)).splitlines()
if diff:
yield "Differing attributes:"
yield from highlighter(pprint.pformat(diff)).splitlines()
for field in diff:
field_left = getattr(left, field)
field_right = getattr(right, field)
yield ""
yield f"Drill down into differing attribute {field}:"
yield f"{indent}{field}: {highlighter(repr(field_left))} != {highlighter(repr(field_right))}"
for line in _compare_eq_any(
field_left,
field_right,
highlighter,
verbose,
assertion_text_diff_style,
):
yield indent + line
@@ -0,0 +1,76 @@
from __future__ import annotations
from collections.abc import Collection
from collections.abc import Iterator
from collections.abc import Mapping
import heapq
import pprint
from _pytest._io.pprint import _safe_key
from _pytest._io.saferepr import saferepr
from _pytest.assertion._typing import _HighlightFunc
from _pytest.assertion._typing import NO_TRUNCATION_BUDGET
from _pytest.assertion._typing import TruncationBudget
def _compare_eq_mapping(
left: Mapping[object, object],
right: Mapping[object, object],
highlighter: _HighlightFunc,
verbose: int = 0,
truncation_budget: TruncationBudget = NO_TRUNCATION_BUDGET,
) -> Iterator[str]:
# Use the key views rather than ``set(left)``/``set(right)``: their set
# operations resolve membership through the mappings themselves, so a
# mapping with its own key equivalence (case-insensitive keys, for
# example) is compared the way it compares itself.
keys_left = left.keys()
keys_right = right.keys()
common = keys_left & keys_right
same = {k: left[k] for k in common if left[k] == right[k]}
if same and verbose < 2:
yield f"Omitting {len(same)} identical items, use -vv to show"
elif same:
yield "Common items:"
yield from highlighter(pprint.pformat(same)).splitlines()
diff = {k for k in common if left[k] != right[k]}
if diff:
yield "Differing items:"
for k in diff:
yield (
highlighter(saferepr({k: left[k]}))
+ " != "
+ highlighter(saferepr({k: right[k]}))
)
extra_left = keys_left - keys_right
len_extra_left = len(extra_left)
if len_extra_left:
yield f"Left contains {len_extra_left} more item{'' if len_extra_left == 1 else 's'}:"
yield from _format_extra_items(left, extra_left, highlighter, truncation_budget)
extra_right = keys_right - keys_left
len_extra_right = len(extra_right)
if len_extra_right:
yield f"Right contains {len_extra_right} more item{'' if len_extra_right == 1 else 's'}:"
yield from _format_extra_items(
right, extra_right, highlighter, truncation_budget
)
def _format_extra_items(
mapping: Mapping[object, object],
keys: Collection[object],
highlighter: _HighlightFunc,
truncation_budget: TruncationBudget,
) -> Iterator[str]:
"""Render the "X contains N more items" subdict."""
max_lines = truncation_budget.max_lines
if max_lines == 0 or len(keys) <= max_lines:
# If no need to truncate, let pprint handle it.
yield from highlighter(
pprint.pformat({k: mapping[k] for k in keys})
).splitlines()
else:
# To avoid spending effort on formatting entries that would be truncated,
# only format the needed entries, keeping the sorting that pprint would use.
for k in heapq.nsmallest(max_lines, keys, key=_safe_key):
yield highlighter(saferepr({k: mapping[k]}))
@@ -0,0 +1,96 @@
from __future__ import annotations
from collections.abc import Iterable
from collections.abc import Iterator
from collections.abc import Sequence
from _pytest._io.pprint import PrettyPrinter
from _pytest._io.saferepr import saferepr
from _pytest.assertion._typing import _HighlightFunc
from _pytest.assertion._typing import NO_TRUNCATION_BUDGET
from _pytest.assertion._typing import TruncationBudget
from _pytest.compat import running_on_ci
def _compare_eq_iterable(
left: Iterable[object],
right: Iterable[object],
highlighter: _HighlightFunc,
verbose: int = 0,
truncation_budget: TruncationBudget = NO_TRUNCATION_BUDGET,
) -> Iterator[str]:
if verbose <= 0 and not running_on_ci():
yield "Use -v to get more diff"
return
# dynamic import to speedup pytest
import difflib
pp = PrettyPrinter()
# ``pformat_lines`` spells an unbounded dimension ``None``; the budget spells it ``0``.
max_lines = truncation_budget.max_lines or None
max_chars = truncation_budget.max_chars or None
left_formatting = pp.pformat_lines(left, max_lines=max_lines, max_chars=max_chars)
right_formatting = pp.pformat_lines(right, max_lines=max_lines, max_chars=max_chars)
yield ""
yield "Full diff: (-: missing in left side, +: extra in left side)"
# "right" is the expected base against which we compare "left",
# see https://github.com/pytest-dev/pytest/issues/3333
# Highlight each ndiff line individually so the streaming truncator can
# stop pulling from ``difflib.ndiff`` once its budget is full; the diff
# lexer is line-oriented, so per-line highlighting is equivalent.
for line in difflib.ndiff(right_formatting, left_formatting):
yield highlighter(line.rstrip(), lexer="diff")
def _compare_eq_sequence(
left: Sequence[object],
right: Sequence[object],
highlighter: _HighlightFunc,
verbose: int = 0,
) -> Iterator[str]:
comparing_bytes = isinstance(left, bytes) and isinstance(right, bytes)
len_left = len(left)
len_right = len(right)
for i in range(min(len_left, len_right)):
if left[i] != right[i]:
if comparing_bytes:
# when comparing bytes, we want to see their ascii representation
# instead of their numeric values (#5260)
# using a slice gives us the ascii representation:
# >>> s = b'foo'
# >>> s[0]
# 102
# >>> s[0:1]
# b'f'
left_value: object = left[i : i + 1]
right_value: object = right[i : i + 1]
else:
left_value = left[i]
right_value = right[i]
yield (
f"At index {i} diff:"
f" {highlighter(repr(left_value))} != {highlighter(repr(right_value))}"
)
break
if comparing_bytes:
# when comparing bytes, it doesn't help to show the "sides contain one or more
# items" longer explanation, so skip it
return
len_diff = len_left - len_right
if len_diff:
if len_diff > 0:
dir_with_more = "Left"
extra = saferepr(left[len_right])
else:
len_diff = 0 - len_diff
dir_with_more = "Right"
extra = saferepr(right[len_left])
if len_diff == 1:
yield f"{dir_with_more} contains one more item: {highlighter(extra)}"
else:
yield f"{dir_with_more} contains {len_diff} more items, first extra item: {highlighter(extra)}"
@@ -0,0 +1,101 @@
from __future__ import annotations
from collections.abc import Callable
from collections.abc import Iterator
from collections.abc import Set as AbstractSet
from typing import TypeAlias
from _pytest._io.saferepr import saferepr
from _pytest.assertion._typing import _HighlightFunc
def _set_one_sided_diff(
posn: str,
set1: AbstractSet[object],
set2: AbstractSet[object],
highlighter: _HighlightFunc,
) -> Iterator[str]:
diff = set1 - set2
if diff:
yield f"Extra items in the {posn} set:"
for item in diff:
yield highlighter(saferepr(item))
def _compare_eq_set(
left: AbstractSet[object],
right: AbstractSet[object],
highlighter: _HighlightFunc,
verbose: int = 0,
) -> Iterator[str]:
yield from _set_one_sided_diff("left", left, right, highlighter)
yield from _set_one_sided_diff("right", right, left, highlighter)
def _compare_gte_set(
left: AbstractSet[object],
right: AbstractSet[object],
highlighter: _HighlightFunc,
verbose: int = 0,
) -> Iterator[str]:
yield from _set_one_sided_diff("right", right, left, highlighter)
def _compare_lte_set(
left: AbstractSet[object],
right: AbstractSet[object],
highlighter: _HighlightFunc,
verbose: int = 0,
) -> Iterator[str]:
yield from _set_one_sided_diff("left", left, right, highlighter)
def _compare_gt_set(
left: AbstractSet[object],
right: AbstractSet[object],
highlighter: _HighlightFunc,
verbose: int = 0,
) -> Iterator[str]:
if left == right:
yield "Both sets are equal"
else:
yield from _set_one_sided_diff("right", right, left, highlighter)
def _compare_lt_set(
left: AbstractSet[object],
right: AbstractSet[object],
highlighter: _HighlightFunc,
verbose: int = 0,
) -> Iterator[str]:
if left == right:
yield "Both sets are equal"
else:
yield from _set_one_sided_diff("left", left, right, highlighter)
SetComparisonFunction: TypeAlias = Callable[
[AbstractSet[object], AbstractSet[object], _HighlightFunc, int],
Iterator[str],
]
def _both_sets_are_equal(
left: AbstractSet[object],
right: AbstractSet[object],
highlighter: _HighlightFunc,
verbose: int = 0,
) -> Iterator[str]:
yield "Both sets are equal"
SET_COMPARISON_FUNCTIONS: dict[str, SetComparisonFunction] = {
# == can't be done here without a prior refactor because there's an additional
# explanation for iterable in _compare_eq_any
# "==": _compare_eq_set,
"!=": _both_sets_are_equal,
">=": _compare_gte_set,
"<=": _compare_lte_set,
">": _compare_gt_set,
"<": _compare_lt_set,
}
@@ -0,0 +1,61 @@
from __future__ import annotations
import collections.abc
from collections.abc import Mapping
from collections.abc import Set as AbstractSet
import dataclasses
from typing import TypeGuard
def issequence(x: object) -> TypeGuard[collections.abc.Sequence[object]]:
return isinstance(x, collections.abc.Sequence) and not isinstance(x, str)
def istext(x: object) -> TypeGuard[str]:
return isinstance(x, str)
def ismapping(x: object) -> TypeGuard[Mapping[object, object]]:
return isinstance(x, Mapping)
def isset(x: object) -> TypeGuard[AbstractSet[object]]:
return isinstance(x, AbstractSet)
def isnamedtuple(obj: object) -> bool:
return isinstance(obj, tuple) and getattr(obj, "_fields", None) is not None
isdatacls = dataclasses.is_dataclass
def isattrs(obj: object) -> bool:
return getattr(obj, "__attrs_attrs__", None) is not None
def isiterable(obj: object) -> TypeGuard[collections.abc.Iterable[object]]:
try:
iter(obj) # type: ignore[call-overload]
return not istext(obj)
except Exception:
return False
def has_default_eq(obj: object) -> bool:
"""Check if an instance of an object contains the default eq
First, we check if the object's __eq__ attribute has __code__,
if so, we check the equally of the method code filename (__code__.co_filename)
to the default one generated by the dataclass and attr module
for dataclasses the default co_filename is <string>, for attrs class, the __eq__ should contain "attrs eq generated"
"""
# inspired from https://github.com/willmcgugan/rich/blob/07d51ffc1aee6f16bd2e5a25b4e82850fb9ed778/rich/pretty.py#L68
if hasattr(obj.__eq__, "__code__") and hasattr(obj.__eq__.__code__, "co_filename"):
code_filename = obj.__eq__.__code__.co_filename
if isattrs(obj):
return "attrs generated " in code_filename
return code_filename == "<string>" # data class
return True
@@ -0,0 +1,35 @@
from __future__ import annotations
from dataclasses import dataclass
from typing import ClassVar
from typing import Literal
from typing import Protocol
_AssertionTextDiffStyle = Literal["ndiff", "block"]
@dataclass(frozen=True, kw_only=True, slots=True)
class TruncationBudget:
"""Per-explanation budget for truncating assertion output.
``max_lines`` / ``max_chars`` mirror the ``truncation_limit_lines`` /
``truncation_limit_chars`` ini values: a positive limit bounds that
dimension; ``0`` leaves it unbounded (the limit is disabled).
"""
#: Default limits applied when the corresponding ini option is left unset.
DEFAULT_MAX_LINES: ClassVar[int] = 8
DEFAULT_MAX_CHARS: ClassVar[int] = DEFAULT_MAX_LINES * 80
max_lines: int = DEFAULT_MAX_LINES
max_chars: int = DEFAULT_MAX_CHARS
# Reusable "no cap" budget, used as a default argument (B008).
NO_TRUNCATION_BUDGET = TruncationBudget(max_lines=0, max_chars=0)
class _HighlightFunc(Protocol): # noqa: PYI046
def __call__(self, source: str, lexer: Literal["diff", "python"] = "python") -> str:
"""Apply highlighting to the given source."""
@@ -0,0 +1,134 @@
from __future__ import annotations
from collections.abc import Iterator
from _pytest._io.saferepr import saferepr
from _pytest.assertion._typing import _AssertionTextDiffStyle
from _pytest.assertion._typing import _HighlightFunc
from _pytest.assertion._typing import NO_TRUNCATION_BUDGET
from _pytest.assertion._typing import TruncationBudget
from _pytest.assertion.highlight import dummy_highlighter
from _pytest.compat import assert_never
def _compare_eq_text(
left: str,
right: str,
highlighter: _HighlightFunc,
verbose: int,
assertion_text_diff_style: _AssertionTextDiffStyle,
truncation_budget: TruncationBudget = NO_TRUNCATION_BUDGET,
) -> Iterator[str]:
match assertion_text_diff_style:
case "block":
yield from _diff_text_block(left, right)
case "ndiff":
yield from _diff_text(left, right, highlighter, verbose, truncation_budget)
case unreachable:
assert_never(unreachable)
def _diff_text_block(left: str, right: str) -> Iterator[str]:
yield "Left:"
yield from _format_text_block_lines(left)
yield ""
yield "Right:"
yield from _format_text_block_lines(right)
def _format_text_block_lines(text: str) -> Iterator[str]:
for line in text.split("\n"):
yield f" {line}"
def _diff_text(
left: str,
right: str,
highlighter: _HighlightFunc,
verbose: int = 0,
truncation_budget: TruncationBudget = NO_TRUNCATION_BUDGET,
) -> Iterator[str]:
"""Yield the explanation for the diff between text.
Unless --verbose is used this will skip leading and trailing
characters which are identical to keep the diff minimal.
When a truncation budget is set, the inputs to ``ndiff`` are capped
first, so the truncated head may differ from the head of the
unbounded diff.
"""
from difflib import ndiff
if verbose < 1:
i = 0 # just in case left or right has zero length
for i in range(min(len(left), len(right))):
if left[i] != right[i]:
break
if i > 42:
i -= 10 # Provide some context
yield f"Skipping {i} identical leading characters in diff, use -v to show"
left = left[i:]
right = right[i:]
if len(left) == len(right):
for i in range(1, len(left) + 1):
if left[-i] != right[-i]:
break
if i > 42:
i -= 10 # Provide some context
yield (
f"Skipping {i} identical trailing "
"characters in diff, use -v to show"
)
left = left[:-i]
right = right[:-i]
keepends = True
if left.isspace() or right.isspace():
left = repr(str(left))
right = repr(str(right))
yield "Strings contain only whitespace, escaping them using repr()"
left_lines = _cap_ndiff_input(left, keepends, truncation_budget)
right_lines = _cap_ndiff_input(right, keepends, truncation_budget)
# "right" is the expected base against which we compare "left",
# see https://github.com/pytest-dev/pytest/issues/3333
yield from highlighter(
"\n".join(line.strip("\n") for line in ndiff(right_lines, left_lines)),
lexer="diff",
).splitlines()
def _cap_ndiff_input(text: str, keepends: bool, budget: TruncationBudget) -> list[str]:
"""Cap an ``ndiff`` input to the truncation budget, as split lines.
A char slice first (bounds a few huge lines, whose intraline diff is
O(len^2)), then a line slice (bounds many lines). A ``0`` limit leaves
that dimension unbounded.
"""
if budget.max_chars > 0:
text = text[: budget.max_chars]
lines = text.splitlines(keepends)
if budget.max_lines > 0:
lines = lines[: budget.max_lines]
return lines
def _notin_text(
term: str,
text: str,
verbose: int = 0,
truncation_budget: TruncationBudget = NO_TRUNCATION_BUDGET,
) -> Iterator[str]:
index = text.find(term)
head = text[:index]
tail = text[index + len(term) :]
correct_text = head + tail
diff = _diff_text(text, correct_text, dummy_highlighter, verbose, truncation_budget)
yield f"{saferepr(term, maxsize=42)} is contained here:"
for line in diff:
if line.startswith("Skipping"):
continue
if line.startswith("- "):
continue
if line.startswith("+ "):
yield " " + line[2:]
else:
yield line
@@ -0,0 +1,11 @@
from __future__ import annotations
from typing import Literal
def dummy_highlighter(source: str, lexer: Literal["diff", "python"] = "python") -> str:
"""Dummy highlighter that returns the text unprocessed.
Needed for _notin_text, as the diff gets post-processed to only show the "+" part.
"""
return source
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,159 @@
"""Utilities for truncating assertion output.
Current default behaviour is to truncate assertion explanations at
terminal lines, unless running with an assertions verbosity level of at least 2 or running on CI.
"""
from __future__ import annotations
from collections.abc import Iterable
from _pytest.assertion._typing import NO_TRUNCATION_BUDGET
from _pytest.assertion._typing import TruncationBudget
from _pytest.compat import running_on_ci
from _pytest.config import Config
USAGE_MSG = "use '-vv' to show"
TRUNCATION_MSG = f"...Full output truncated, {USAGE_MSG}"
# Truncating appends a footer: ``...`` on the last kept line, a blank line,
# then ``TRUNCATION_MSG``. A body may exceed the raw budget by the footer's
# cost before truncating, so a body that nearly fits is not cut just to
# make room for the footer.
TRUNCATION_FOOTER_LINES = 2 # blank separator + message line
TRUNCATION_FOOTER_CHARS = len("...") + len(TRUNCATION_MSG)
def materialize_with_truncation(lines: Iterable[str], config: Config) -> list[str]:
"""Materialise a streaming explanation, applying truncation lazily.
Pulls from ``lines`` only until the truncation threshold is reached;
the rest of the iterator is dropped without being consumed.
"""
should_truncate, budget = _get_truncation_parameters(config)
if not should_truncate:
return list(lines)
tolerable_max_chars = budget.max_chars + TRUNCATION_FOOTER_CHARS
# Pull one line past the point where ``_truncate_explanation`` keeps the
# body whole (``max_lines + TRUNCATION_FOOTER_LINES``) so it can detect the
# overflow, without us materialising more than we need.
line_cap = (
budget.max_lines + TRUNCATION_FOOTER_LINES + 1 if budget.max_lines > 0 else None
)
buffered: list[str] = []
char_count = 0
for line in lines:
buffered.append(line)
char_count += len(line)
if line_cap is not None and len(buffered) >= line_cap:
break
if budget.max_chars > 0 and char_count > tolerable_max_chars:
break
else:
# Iterator exhausted within limits — nothing to truncate.
return buffered
return _truncate_explanation(buffered, budget)
def _get_truncation_parameters(config: Config) -> tuple[bool, TruncationBudget]:
"""Return the truncation parameters from the given config, as (should truncate, budget)."""
# We do not need to truncate if one of these conditions is met:
# 1. Verbosity level is 2 or more;
# 2. Test is being run in CI environment;
# 3. Both truncation_limit_lines and truncation_limit_chars
# are set to 0 explicitly.
verbose = config.get_verbosity(Config.VERBOSITY_ASSERTIONS)
if verbose >= 2 or running_on_ci():
return False, NO_TRUNCATION_BUDGET
budget = _budget_from_config(config)
should_truncate = budget.max_lines > 0 or budget.max_chars > 0
return should_truncate, budget
def _budget_from_config(config: Config) -> TruncationBudget:
"""Build a budget from the ``truncation_limit_*`` ini options.
``getini`` returns ``None`` when an option is unset, which falls back to
the default limit.
"""
max_lines = config.getini("truncation_limit_lines")
max_chars = config.getini("truncation_limit_chars")
return TruncationBudget(
max_lines=(
TruncationBudget.DEFAULT_MAX_LINES if max_lines is None else int(max_lines)
),
max_chars=(
TruncationBudget.DEFAULT_MAX_CHARS if max_chars is None else int(max_chars)
),
)
def _truncate_explanation(
input_lines: list[str],
budget: TruncationBudget,
) -> list[str]:
"""Truncate given list of strings that makes up the assertion explanation.
Truncates to either ``budget.max_lines`` or ``budget.max_chars`` -
whichever the input reaches first, taking the truncation explanation into
account. The remaining lines will be replaced by a usage message.
If max_chars=0, no truncation by character count is performed.
If max_lines=0, no truncation by line count is performed.
When this function is launched we know max_lines > 0 or max_chars > 0
because _get_truncation_parameters was called first.
"""
# ``max_chars`` bounds the body only; the footer slack is added on top
# (see ``TRUNCATION_FOOTER_CHARS``).
tolerable_max_chars = budget.max_chars + TRUNCATION_FOOTER_CHARS
if (
budget.max_lines == 0
or len(input_lines) <= budget.max_lines + TRUNCATION_FOOTER_LINES
):
if (
budget.max_chars == 0
or sum(len(s) for s in input_lines) <= tolerable_max_chars
):
return input_lines
truncated_explanation = input_lines
else:
# Truncate first to max_lines, and then truncate to max_chars if necessary
truncated_explanation = input_lines[: budget.max_lines]
# We reevaluate the need to truncate chars following removal of some lines
if (
budget.max_chars > 0
and sum(len(e) for e in truncated_explanation) > tolerable_max_chars
):
truncated_explanation = _truncate_by_char_count(
truncated_explanation, budget.max_chars
)
# Something was truncated, adding '...' at the end to show that
truncated_explanation[-1] += "..."
return [
*truncated_explanation,
"",
TRUNCATION_MSG,
]
def _truncate_by_char_count(input_lines: list[str], max_chars: int) -> list[str]:
# Find point at which input length exceeds total allowed length
iterated_char_count = 0
for iterated_index, input_line in enumerate(input_lines):
if iterated_char_count + len(input_line) > max_chars:
break
iterated_char_count += len(input_line)
# Create truncated explanation with modified final line
truncated_result = input_lines[:iterated_index]
final_line = input_lines[iterated_index]
if final_line:
final_line_truncate_point = max_chars - iterated_char_count
final_line = final_line[:final_line_truncate_point]
truncated_result.append(final_line)
return truncated_result
@@ -0,0 +1,191 @@
# mypy: allow-untyped-defs
"""Utilities for assertion debugging."""
from __future__ import annotations
from collections.abc import Callable
from collections.abc import Iterator
from collections.abc import Sequence
from collections.abc import Set as AbstractSet
from unicodedata import normalize
from _pytest import outcomes
import _pytest._code
from _pytest._io.saferepr import saferepr
from _pytest._io.saferepr import saferepr_unlimited
from _pytest.assertion._compare_any import _compare_eq_any
from _pytest.assertion._compare_set import SET_COMPARISON_FUNCTIONS
from _pytest.assertion._typing import _AssertionTextDiffStyle
from _pytest.assertion._typing import _HighlightFunc
from _pytest.assertion._typing import NO_TRUNCATION_BUDGET
from _pytest.assertion._typing import TruncationBudget
from _pytest.assertion.compare_text import _notin_text
from _pytest.assertion.highlight import dummy_highlighter as dummy_highlighter
from _pytest.config import Config
# The _reprcompare attribute on the util module is used by the new assertion
# interpretation code and assertion rewriter to detect this plugin was
# loaded and in turn call the hooks defined here as part of the
# DebugInterpreter.
_reprcompare: Callable[[str, object, object], str | None] | None = None
# Works similarly as _reprcompare attribute. Is populated with the hook call
# when pytest_runtest_setup is called.
_assertion_pass: Callable[[int, str, str], None] | None = None
# Config object which is assigned during pytest_runtest_protocol.
_config: Config | None = None
def format_explanation(explanation: str) -> str:
r"""Format an explanation.
Normally all embedded newlines are escaped, however there are
three exceptions: \n{, \n} and \n~. The first two are intended
cover nested explanations, see function and attribute explanations
for examples (.visit_Call(), visit_Attribute()). The last one is
for when one explanation needs to span multiple lines, e.g. when
displaying diffs.
"""
lines = _split_explanation(explanation)
result = _format_lines(lines)
return "\n".join(result)
def _split_explanation(explanation: str) -> list[str]:
r"""Return a list of individual lines in the explanation.
This will return a list of lines split on '\n{', '\n}' and '\n~'.
Any other newlines will be escaped and appear in the line as the
literal '\n' characters.
"""
raw_lines = (explanation or "").split("\n")
lines = [raw_lines[0]]
for values in raw_lines[1:]:
if values and values[0] in ["{", "}", "~", ">"]:
lines.append(values)
else:
lines[-1] += "\\n" + values
return lines
def _format_lines(lines: Sequence[str]) -> list[str]:
"""Format the individual lines.
This will replace the '{', '}' and '~' characters of our mini formatting
language with the proper 'where ...', 'and ...' and ' + ...' text, taking
care of indentation along the way.
Return a list of formatted lines.
"""
result = list(lines[:1])
stack = [0]
stackcnt = [0]
for line in lines[1:]:
if line.startswith("{"):
if stackcnt[-1]:
s = "and "
else:
s = "where "
stack.append(len(result))
stackcnt[-1] += 1
stackcnt.append(0)
result.append(" +" + " " * (len(stack) - 1) + s + line[1:])
elif line.startswith("}"):
stack.pop()
stackcnt.pop()
result[stack[-1]] += line[1:]
else:
assert line[0] in ["~", ">"]
stack[-1] += 1
indent = len(stack) if line.startswith("~") else len(stack) - 1
result.append(" " * indent + line[1:])
assert len(stack) == 1
return result
def assertrepr_compare(
op: str,
left: object,
right: object,
*,
verbose: int,
highlighter: _HighlightFunc,
assertion_text_diff_style: _AssertionTextDiffStyle,
truncation_budget: TruncationBudget = NO_TRUNCATION_BUDGET,
) -> Iterator[str]:
"""Yield specialised explanations for some operators/operands.
The first line yielded is always the summary (``left op right``);
subsequent lines are the detailed explanation. Yields nothing when no
specialised explanation applies, which lets consumers map an empty
iterator to "no explanation" without materialising anything.
The iterator is lazy on purpose: a streaming consumer can stop pulling
lines as soon as it has enough to show, so an enormous diff doesn't
have to be built in full just to be thrown away.
"""
# Strings which normalize equal are often hard to distinguish when printed; use ascii() to make this easier.
# See issue #3246.
use_ascii = (
isinstance(left, str)
and isinstance(right, str)
and normalize("NFD", left) == normalize("NFD", right)
)
if verbose > 1:
left_repr = saferepr_unlimited(left, use_ascii=use_ascii)
right_repr = saferepr_unlimited(right, use_ascii=use_ascii)
else:
# XXX: "15 chars indentation" is wrong
# ("E AssertionError: assert "); should use term width.
maxsize = (
80 - 15 - len(op) - 2
) // 2 # 15 chars indentation, 1 space around op
left_repr = saferepr(left, maxsize=maxsize, use_ascii=use_ascii)
right_repr = saferepr(right, maxsize=maxsize, use_ascii=use_ascii)
summary = f"{left_repr} {op} {right_repr}"
try:
match (left, op, right):
case (_, "==", _):
source = _compare_eq_any(
left,
right,
highlighter,
verbose,
assertion_text_diff_style,
truncation_budget,
)
case (str(), "not in", str()):
source = _notin_text(left, right, verbose, truncation_budget)
case (AbstractSet(), "!=" | ">=" | "<=" | ">" | "<", AbstractSet()):
source = SET_COMPARISON_FUNCTIONS[op](left, right, highlighter, verbose)
case _:
source = iter(())
# Only yield the summary if there is a detailed explanation.
# Make sure there's a separating empty line after the summary.
summary_yielded = False
for line in source:
if not summary_yielded:
yield summary
if line != "":
yield ""
summary_yielded = True
yield line
except outcomes.Exit:
raise
except Exception:
repr_crash = _pytest._code.ExceptionInfo.from_current()._getreprcrash()
if not summary_yielded:
yield summary
yield ""
summary_yielded = True
yield (
f"(pytest_assertion plugin: representation of details failed: {repr_crash}."
)
yield " Probably an object has a faulty __repr__.)"