Codex/assertion text diff blocks

changelog/6757.feature.rst

@@ -0,0 +1,3 @@
+Added the :confval:`assertion_text_diff_style` configuration option, allowing
+string equality failures to be rendered as separate ``Left:`` and ``Right:``
+blocks instead of ``ndiff`` output.

doc/en/how-to/output.rst

@@ -363,6 +363,13 @@ This is done by setting a verbosity level in the configuration file for the spec
 ``pytest --no-header`` with a value of ``2`` would have the same output as the previous example, but each test inside
 the file is shown by a single character in the output.
 
+:confval:`assertion_text_diff_style`: Controls how pytest renders ``str == str`` failures.
+
+  * ``ndiff`` (the default) outputs the differences using inline diff markers.
+  * ``block`` prints string comparisons as separate ``Left:`` and ``Right:`` blocks, which can be easier to read when whitespace or indentation differences dominate.
+
+  Note that it is possible to set this option (as any other configuration option) directly in the command line using ``-o assertion_text_diff_style=block``.
+
 :confval:`verbosity_test_cases`: Controls how verbose the test execution output should be when pytest is executed.
 Running ``pytest --no-header`` with a value of ``2`` would have the same output as the first verbosity example, but each
 test inside the file gets its own line in the output.

doc/en/reference/reference.rst

@@ -2699,6 +2699,32 @@ passed multiple times. The expected format is ``name=value``. For example::
     A special value of ``"auto"`` can be used to explicitly use the global verbosity level.
 
 
+.. confval:: assertion_text_diff_style
+    :type: ``str``
+    :default: ``"ndiff"``
+
+    Set how pytest renders diffs for string equality assertions.
+
+    Supported values are:
+
+    * ``ndiff``: use the inline diff rendering markers.
+    * ``block``: render each string in separate ``Left:`` and ``Right:`` blocks.
+
+    .. tab:: toml
+
+        .. code-block:: toml
+
+            [pytest]
+            assertion_text_diff_style = "block"
+
+    .. tab:: ini
+
+        .. code-block:: ini
+
+            [pytest]
+            assertion_text_diff_style = block
+
+
 .. confval:: verbosity_subtests
     :type: ``str``
     :default: ``"auto"``

src/_pytest/assertion/__init__.py

@@ -57,6 +57,15 @@ def pytest_addoption(parser: Parser) -> None:
         default=None,
         help=("Set threshold of CHARS after which truncation will take effect"),
     )
+    parser.addini(
+        "assertion_text_diff_style",
+        default=util.ASSERTION_TEXT_DIFF_STYLE_NDIFF,
+        help=(
+            "Choose how pytest renders diffs for string equality assertions: "
+            f"{util.ASSERTION_TEXT_DIFF_STYLE_NDIFF} or "
+            f"{util.ASSERTION_TEXT_DIFF_STYLE_BLOCK}"
+        ),
+    )
 
     Config._add_verbosity_ini(
         parser,
@@ -68,6 +77,10 @@ def pytest_addoption(parser: Parser) -> None:
     )
 
 
+def pytest_configure(config: Config) -> None:
+    util.validate_assertion_text_diff_style(config)
+
+
 def register_assert_rewrite(*names: str) -> None:
     """Register one or more module names to be rewritten on import.
 
@@ -216,4 +229,5 @@ def pytest_assertrepr_compare(
         right=right,
         verbose=config.get_verbosity(Config.VERBOSITY_ASSERTIONS),
         highlighter=highlighter,
+        assertion_text_diff_style=util.get_assertion_text_diff_style(config),
     )

src/_pytest/assertion/util.py

@@ -23,6 +23,7 @@
 from _pytest._io.saferepr import saferepr_unlimited
 from _pytest.compat import running_on_ci
 from _pytest.config import Config
+from _pytest.config import UsageError
 
 
 # The _reprcompare attribute on the util module is used by the new assertion
@@ -38,6 +39,15 @@
 # Config object which is assigned during pytest_runtest_protocol.
 _config: Config | None = None
 
+ASSERTION_TEXT_DIFF_STYLE_INI = "assertion_text_diff_style"
+_AssertionTextDiffStyle = Literal["ndiff", "block"]
+ASSERTION_TEXT_DIFF_STYLE_NDIFF: Literal["ndiff"] = "ndiff"
+ASSERTION_TEXT_DIFF_STYLE_BLOCK: Literal["block"] = "block"
+ASSERTION_TEXT_DIFF_STYLE_CHOICES = (
+    ASSERTION_TEXT_DIFF_STYLE_NDIFF,
+    ASSERTION_TEXT_DIFF_STYLE_BLOCK,
+)
+
 
 class _HighlightFunc(Protocol):
     def __call__(self, source: str, lexer: Literal["diff", "python"] = "python") -> str:
@@ -52,6 +62,24 @@ def dummy_highlighter(source: str, lexer: Literal["diff", "python"] = "python")
     return source
 
 
+def get_assertion_text_diff_style(config: Config) -> _AssertionTextDiffStyle:
+    style = str(config.getini(ASSERTION_TEXT_DIFF_STYLE_INI))
+    match style:
+        case "ndiff" | "block":
+            return style
+        case _:
+            choices = ", ".join(
+                repr(choice) for choice in ASSERTION_TEXT_DIFF_STYLE_CHOICES
+            )
+            raise UsageError(
+                f"{ASSERTION_TEXT_DIFF_STYLE_INI} must be one of {choices}; got {style!r}"
+            )
+
+
+def validate_assertion_text_diff_style(config: Config) -> None:
+    get_assertion_text_diff_style(config)
+
+
 def format_explanation(explanation: str) -> str:
     r"""Format an explanation.
 
@@ -180,6 +208,7 @@ def assertrepr_compare(
     *,
     verbose: int,
     highlighter: _HighlightFunc,
+    assertion_text_diff_style: _AssertionTextDiffStyle,
 ) -> list[str] | None:
     """Return specialised explanations for some operators/operands."""
     # Strings which normalize equal are often hard to distinguish when printed; use ascii() to make this easier.
@@ -208,7 +237,13 @@ def assertrepr_compare(
     explanation = None
     try:
         if op == "==":
-            explanation = _compare_eq_any(left, right, highlighter, verbose)
+            explanation = _compare_eq_any(
+                left,
+                right,
+                highlighter,
+                verbose,
+                assertion_text_diff_style,
+            )
         elif op == "not in":
             if istext(left) and istext(right):
                 explanation = _notin_text(left, right, verbose)
@@ -246,11 +281,21 @@ def assertrepr_compare(
 
 
 def _compare_eq_any(
-    left: object, right: object, highlighter: _HighlightFunc, verbose: int = 0
+    left: object,
+    right: object,
+    highlighter: _HighlightFunc,
+    verbose: int,
+    assertion_text_diff_style: _AssertionTextDiffStyle,
 ) -> list[str]:
     explanation = []
     if istext(left) and istext(right):
-        explanation = _diff_text(left, right, highlighter, verbose)
+        explanation = _compare_eq_text(
+            left,
+            right,
+            highlighter,
+            verbose,
+            assertion_text_diff_style,
+        )
     else:
         from _pytest.python_api import ApproxBase
 
@@ -266,7 +311,13 @@ def _compare_eq_any(
             # 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.
-            explanation = _compare_eq_cls(left, right, highlighter, verbose)
+            explanation = _compare_eq_cls(
+                left,
+                right,
+                highlighter,
+                verbose,
+                assertion_text_diff_style,
+            )
         elif issequence(left) and issequence(right):
             explanation = _compare_eq_sequence(left, right, highlighter, verbose)
         elif isset(left) and isset(right):
@@ -281,6 +332,34 @@ def _compare_eq_any(
     return explanation
 
 
+def _compare_eq_text(
+    left: str,
+    right: str,
+    highlighter: _HighlightFunc,
+    verbose: int,
+    assertion_text_diff_style: _AssertionTextDiffStyle,
+) -> list[str]:
+    match assertion_text_diff_style:
+        case "block":
+            return _diff_text_block(left, right)
+        case "ndiff":
+            return _diff_text(left, right, highlighter, verbose)
+
+
+def _diff_text_block(left: str, right: str) -> list[str]:
+    return [
+        "Left:",
+        *_format_text_block_lines(left),
+        "",
+        "Right:",
+        *_format_text_block_lines(right),
+    ]
+
+
+def _format_text_block_lines(text: str) -> list[str]:
+    return [f"  {line}" for line in text.split("\n")]
+
+
 def _diff_text(
     left: str, right: str, highlighter: _HighlightFunc, verbose: int = 0
 ) -> list[str]:
@@ -541,7 +620,11 @@ def _compare_eq_dict(
 
 
 def _compare_eq_cls(
-    left: object, right: object, highlighter: _HighlightFunc, verbose: int
+    left: object,
+    right: object,
+    highlighter: _HighlightFunc,
+    verbose: int,
+    assertion_text_diff_style: _AssertionTextDiffStyle,
 ) -> list[str]:
     if not has_default_eq(left):
         return []
@@ -587,7 +670,11 @@ def _compare_eq_cls(
             explanation += [
                 indent + line
                 for line in _compare_eq_any(
-                    field_left, field_right, highlighter, verbose
+                    field_left,
+                    field_right,
+                    highlighter,
+                    verbose,
+                    assertion_text_diff_style,
                 )
             ]
     return explanation