"""Utilities for assertion debugging"""
import collections.abc
import itertools
import os
import pprint
import re
from typing import AbstractSet
from typing import Any
from typing import Callable
from typing import Iterable
from typing import List
from typing import Mapping
from typing import Optional
from typing import Sequence
from typing import Tuple
import _pytest._code
from _pytest import outcomes
from _pytest._io.saferepr import _pformat_dispatch
from _pytest._io.saferepr import safeformat
from _pytest._io.saferepr import saferepr
from _pytest.compat import ATTRS_EQ_FIELD
# 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 = None # type: Optional[Callable[[str, object, object], Optional[str]]]
# Works similarly as _reprcompare attribute. Is populated with the hook call
# when pytest_runtest_setup is called.
_assertion_pass = None # type: Optional[Callable[[int, str, str], None]]
[docs]def _split_explanation(explanation: str) -> List[str]:
"""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
[docs]def issequence(x: Any) -> bool:
return isinstance(x, collections.abc.Sequence) and not isinstance(x, str)
[docs]def istext(x: Any) -> bool:
return isinstance(x, str)
[docs]def isdict(x: Any) -> bool:
return isinstance(x, dict)
[docs]def isset(x: Any) -> bool:
return isinstance(x, (set, frozenset))
[docs]def isdatacls(obj: Any) -> bool:
return getattr(obj, "__dataclass_fields__", None) is not None
[docs]def isattrs(obj: Any) -> bool:
return getattr(obj, "__attrs_attrs__", None) is not None
[docs]def isiterable(obj: Any) -> bool:
try:
iter(obj)
return not istext(obj)
except TypeError:
return False
[docs]def _gets_full_diff(op: str, left: Any, right: Any, verbose: int) -> bool:
# via _compare_eq_iterable
return verbose > 0 and op == "==" and isiterable(left) and isiterable(right)
[docs]def assertrepr_compare(config, op: str, left: Any, right: Any) -> Optional[List[str]]:
"""Return specialised explanations for some operators/operands"""
verbose = config.getoption("verbose")
explanation = None
try:
if op == "==":
if istext(left) and istext(right):
explanation = _diff_text(left, right, verbose)
else:
if issequence(left) and issequence(right):
explanation = _compare_eq_sequence(left, right, verbose)
elif isset(left) and isset(right):
explanation = _compare_eq_set(left, right, verbose)
elif isdict(left) and isdict(right):
explanation = _compare_eq_dict(left, right, verbose)
elif type(left) == type(right) and (isdatacls(left) or isattrs(left)):
type_fn = (isdatacls, isattrs)
explanation = _compare_eq_cls(left, right, verbose, type_fn)
elif verbose > 0:
explanation = _compare_eq_verbose(left, right)
if isiterable(left) and isiterable(right):
expl = _compare_eq_iterable(left, right, verbose)
if explanation is not None:
explanation.extend(expl)
else:
explanation = expl
elif op == "not in":
if istext(left) and istext(right):
explanation = _notin_text(left, right, verbose)
except outcomes.Exit:
raise
except Exception:
explanation = [
"(pytest_assertion plugin: representation of details failed: {}.".format(
_pytest._code.ExceptionInfo.from_current()._getreprcrash()
),
" Probably an object has a faulty __repr__.)",
]
if not explanation:
return None
# Summary.
has_full_diff = "Full diff:" in explanation
if verbose > 1 and not has_full_diff:
left_repr = safeformat(left)
right_repr = safeformat(right)
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)
right_repr = saferepr(right, maxsize=maxsize)
summary = "{} {} {}".format(left_repr, op, right_repr)
return [summary] + explanation
[docs]def _diff_text(left: str, right: str, verbose: int = 0) -> List[str]:
"""Return 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.
"""
from difflib import ndiff
from wcwidth import wcwidth
explanation = [] # type: List[str]
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
explanation = [
"Skipping %s identical leading characters in diff, use -v to show" % i
]
left = left[i:]
right = right[i:]
if len(left) == len(right):
for i in range(len(left)):
if left[-i] != right[-i]:
break
if i > 42:
i -= 10 # Provide some context
explanation += [
"Skipping {} identical trailing "
"characters in diff, use -v to show".format(i)
]
left = left[:-i]
right = right[:-i]
if left.isspace() or right.isspace():
left = repr(str(left))
right = repr(str(right))
explanation += ["Strings contain only whitespace, escaping them using repr()"]
left_split = len(left) and re.split("(\r?\n)", left) or []
left_lines = left_split[::2]
right_split = len(right) and re.split("(\r?\n)", right) or []
right_lines = right_split[::2]
if any(
wcwidth(ch) <= 0
for ch in [ch for lines in left_lines + right_lines for ch in lines]
):
left_lines = [repr(x) for x in left.splitlines(True)]
right_lines = [repr(x) for x in right.splitlines(True)]
explanation += [
"NOTE: Strings contain non-printable characters. Escaping them using repr()."
]
else:
max_split = min(len(left_lines), len(right_lines))
if (len(left_lines) and left_lines[-1] == "") or (
len(right_lines) and right_lines[-1] == ""
):
# Escape with trailing newline.
max_split += 1
left_ends = left_split[1:max_split:2]
right_ends = right_split[1:max_split:2]
if left_ends != right_ends:
explanation += [
"NOTE: Strings contain different line-endings. Escaping them using repr()."
]
for idx, (left_line, right_line, left_end, right_end) in enumerate(
itertools.zip_longest(
left_lines, right_lines, left_ends, right_ends, fillvalue=None
)
):
if left_end == right_end:
continue
if left_end is not None:
left_lines[idx] += repr(left_end)[1:-1]
if right_end is not None:
right_lines[idx] += repr(right_end)[1:-1]
# "right" is the expected base against which we compare "left",
# see https://github.com/pytest-dev/pytest/issues/3333
explanation += [line.strip("\n") for line in ndiff(right_lines, left_lines)]
return explanation
[docs]def _compare_eq_verbose(left: Any, right: Any) -> List[str]:
keepends = True
left_lines = repr(left).splitlines(keepends)
right_lines = repr(right).splitlines(keepends)
explanation = [] # type: List[str]
explanation += ["+" + line for line in left_lines]
explanation += ["-" + line for line in right_lines]
return explanation
[docs]def _surrounding_parens_on_own_lines(lines: List[str]) -> None:
"""Move opening/closing parenthesis/bracket to own lines."""
opening = lines[0][:1]
if opening in ["(", "[", "{"]:
lines[0] = " " + lines[0][1:]
lines[:] = [opening] + lines
closing = lines[-1][-1:]
if closing in [")", "]", "}"]:
lines[-1] = lines[-1][:-1] + ","
lines[:] = lines + [closing]
[docs]def _compare_eq_iterable(
left: Iterable[Any], right: Iterable[Any], verbose: int = 0
) -> List[str]:
if not verbose:
return ["Use -v to get the full diff"]
# dynamic import to speedup pytest
import difflib
from _pytest.terminal import get_terminal_width
width = get_terminal_width()
left_formatting = pprint.pformat(left, width=width).splitlines()
right_formatting = pprint.pformat(right, width=width).splitlines()
# Re-format for different output lengths.
lines_left = len(left_formatting)
lines_right = len(right_formatting)
if lines_left != lines_right:
left_formatting = _pformat_dispatch(left, width=width).splitlines()
right_formatting = _pformat_dispatch(right, width=width).splitlines()
if lines_left > 1 or lines_right > 1:
_surrounding_parens_on_own_lines(left_formatting)
_surrounding_parens_on_own_lines(right_formatting)
explanation = ["Full diff:"]
# "right" is the expected base against which we compare "left",
# see https://github.com/pytest-dev/pytest/issues/3333
explanation.extend(
line.rstrip() for line in difflib.ndiff(right_formatting, left_formatting)
)
return explanation
[docs]def _compare_eq_sequence(
left: Sequence[Any], right: Sequence[Any], verbose: int = 0
) -> List[str]:
comparing_bytes = isinstance(left, bytes) and isinstance(right, bytes)
explanation = [] # type: List[str]
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 = left[i : i + 1]
right_value = right[i : i + 1]
else:
left_value = left[i]
right_value = right[i]
left_repr = repr(left_value)
right_repr = repr(right_value)
if (
not _gets_full_diff("==", left, right, verbose)
and len(left_repr) > 10
and len(right_repr) > 10
):
explanation += [
"At index {} diff:".format(i),
"{} !=".format(left_repr),
"{}".format(right_repr),
]
else:
explanation += [
"At index {} diff: {} != {}".format(i, left_repr, right_repr)
]
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 explanation
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:
explanation += [
"{} contains one more item: {}".format(dir_with_more, extra)
]
else:
explanation += [
"%s contains %d more items, first extra item: %s"
% (dir_with_more, len_diff, extra)
]
return explanation
[docs]def _compare_eq_set(
left: AbstractSet[Any], right: AbstractSet[Any], verbose: int = 0
) -> List[str]:
explanation = []
diff_left = left - right
diff_right = right - left
if diff_left:
explanation.append("Extra items in the left set:")
for item in diff_left:
explanation.append(saferepr(item))
if diff_right:
explanation.append("Extra items in the right set:")
for item in diff_right:
explanation.append(saferepr(item))
return explanation
[docs]def _compare_eq_dict(
left: Mapping[Any, Any], right: Mapping[Any, Any], verbose: int = 0
) -> List[str]:
explanation = [] # type: List[str]
set_left = set(left)
set_right = set(right)
common = set_left.intersection(set_right)
same = {k: left[k] for k in common if left[k] == right[k]}
if same and verbose < 2:
explanation += ["Omitting %s identical items, use -vv to show" % len(same)]
elif same:
explanation += ["Common items:"]
explanation += pprint.pformat(same).splitlines()
diff = {k for k in common if left[k] != right[k]}
if diff:
explanation += ["Differing items:"]
for k in diff:
explanation += [saferepr({k: left[k]}) + " != " + saferepr({k: right[k]})]
extra_left = set_left - set_right
len_extra_left = len(extra_left)
if len_extra_left:
explanation.append(
"Left contains %d more item%s:"
% (len_extra_left, "" if len_extra_left == 1 else "s")
)
explanation.extend(
pprint.pformat({k: left[k] for k in extra_left}).splitlines()
)
extra_right = set_right - set_left
len_extra_right = len(extra_right)
if len_extra_right:
explanation.append(
"Right contains %d more item%s:"
% (len_extra_right, "" if len_extra_right == 1 else "s")
)
explanation.extend(
pprint.pformat({k: right[k] for k in extra_right}).splitlines()
)
return explanation
[docs]def _compare_eq_cls(
left: Any,
right: Any,
verbose: int,
type_fns: Tuple[Callable[[Any], bool], Callable[[Any], bool]],
) -> List[str]:
isdatacls, isattrs = type_fns
if isdatacls(left):
all_fields = left.__dataclass_fields__
fields_to_check = [field for field, info in all_fields.items() if info.compare]
elif isattrs(left):
all_fields = left.__attrs_attrs__
fields_to_check = [
field.name for field in all_fields if getattr(field, ATTRS_EQ_FIELD)
]
same = []
diff = []
for field in fields_to_check:
if getattr(left, field) == getattr(right, field):
same.append(field)
else:
diff.append(field)
explanation = []
if same and verbose < 2:
explanation.append("Omitting %s identical items, use -vv to show" % len(same))
elif same:
explanation += ["Matching attributes:"]
explanation += pprint.pformat(same).splitlines()
if diff:
explanation += ["Differing attributes:"]
for field in diff:
explanation += [
("%s: %r != %r") % (field, getattr(left, field), getattr(right, field))
]
return explanation
[docs]def _notin_text(term: str, text: str, verbose: int = 0) -> List[str]:
from wcwidth import wcwidth
index = text.find(term)
head = text[:index]
tail = text[index + len(term) :]
correct_text = head + tail
newdiff = ["%s is contained here:" % saferepr(term, maxsize=42)]
if any(
wcwidth(ch) <= 0
for ch in [ch for lines in [term, correct_text] for ch in lines]
):
newdiff = [
"NOTE: Strings contain non-printable characters. Escaping them using repr()."
] + newdiff
text = repr(text)
indent = " " * (index + 1)
marker = "+" * (len(repr(term)) - 2)
else:
indent = " " * index
marker = "+" * len(term)
newdiff += [
" " + text,
"? " + indent + marker,
]
return newdiff
[docs]def _running_on_ci():
return os.environ.get("CI", "").lower() == "true" or "BUILD_NUMBER" in os.environ