Merge lp:~allenap/maas/text-equals-matcher into lp:~maas-committers/maas/trunk

[Gavin Panella]

TextEquals matcher which displays a diff of differences when there's a mismatch.

This is especially useful when dealing with larger blocks of text.

I wrote this while working on another branch. I didn't need it there in the end, but it seems useful.

[Lee Trager (ltrager)]

Thanks for writing this, should make debug of tests much easier!

review: Approve

=== modified file 'src/maastesting/matchers.py'
--- src/maastesting/matchers.py	2016-03-28 13:54:47 +0000
+++ src/maastesting/matchers.py	2016-11-10 15:36:36 +0000
@@ -21,12 +21,18 @@
     'MockCallsMatch',
     'MockNotCalled',
     'Provides',
+    'TextEquals',
     ]
 
+from difflib import ndiff
 import doctest
 from functools import partial
 
 from testtools import matchers
+from testtools.content import (
+    Content,
+    UTF8_TEXT,
+)
 from testtools.matchers import (
     AfterPreprocessing,
     Annotate,
@@ -427,3 +433,35 @@
                 "File at path exists and its contents (encoded as %s) "
                 "match %s" % (self.encoding, self.matcher)
             )
+
+
+class TextEquals(Matcher):
+    """Compares two blocks of text for equality.
+
+    This differs from `Equals` in that is calculates an `ndiff` between the
+    two which will be included in the test results, making this especially
+    appropriate for longer pieces of text.
+    """
+
+    def __init__(self, expected):
+        super(TextEquals, self).__init__()
+        self.expected = expected
+
+    def match(self, observed):
+        if observed != self.expected:
+            diff = self._diff(self.expected, observed)
+            return Mismatch(
+                "Observed text does not match expectations; see diff.",
+                {"diff": Content(UTF8_TEXT, lambda: map(str.encode, diff))})
+
+    @staticmethod
+    def _diff(expected, observed):
+        # ndiff works better when lines consistently end with newlines.
+        a = str(expected).splitlines(keepends=False)
+        a = list(line + "\n" for line in a)
+        b = str(observed).splitlines(keepends=False)
+        b = list(line + "\n" for line in b)
+
+        yield "--- expected\n"
+        yield "+++ observed\n"
+        yield from ndiff(a, b)

=== modified file 'src/maastesting/tests/test_matchers.py'
--- src/maastesting/tests/test_matchers.py	2016-06-22 17:03:02 +0000
+++ src/maastesting/tests/test_matchers.py	2016-11-10 15:36:36 +0000
@@ -5,6 +5,7 @@
 
 __all__ = []
 
+from textwrap import dedent
 from unittest.mock import (
     call,
     create_autospec,
@@ -31,12 +32,16 @@
     MockCalledWith,
     MockCallsMatch,
     MockNotCalled,
+    TextEquals,
 )
 from maastesting.testcase import MAASTestCase
+from testtools.content import Content
 from testtools.matchers import (
     AfterPreprocessing,
     Contains,
+    ContainsDict,
     Equals,
+    IsInstance,
     MatchesStructure,
     Mismatch,
 )
@@ -499,3 +504,66 @@
             "File at path exists and its contents (encoded as %s) "
             "match %s" % (encoding, contents_matcher),
             FileContains(matcher=contents_matcher, encoding=encoding))
+
+
+class TestTextEquals(MAASTestCase, MockTestMixin):
+    """Tests for the `TextEquals` matcher."""
+
+    def test_matches_equal_strings(self):
+        contents = factory.make_string()
+        self.assertThat(contents, TextEquals(contents))
+
+    def test_matches_equal_things(self):
+        contents = object()
+        self.assertThat(contents, TextEquals(contents))
+
+    def test_describes_mismatch(self):
+        self.assertMismatch(
+            TextEquals("foo").match("bar"),
+            "Observed text does not match expectations; see diff.")
+
+    def test_includes_diff_of_mismatch(self):
+        expected = "A line of text that differs at the end."
+        observed = "A line of text that differs at THE end."
+        mismatch = TextEquals(expected).match(observed)
+        details = mismatch.get_details()
+        self.assertThat(details, ContainsDict({"diff": IsInstance(Content)}))
+        self.assertThat(details["diff"].as_text(), Equals(dedent("""\
+        --- expected
+        +++ observed
+        - A line of text that differs at the end.
+        ?                                ^^^
+        + A line of text that differs at THE end.
+        ?                                ^^^
+        """)))
+
+    def test_includes_diff_of_mismatch_multiple_lines(self):
+        expected = "A line of text that differs\nat the end of the 2nd line."
+        observed = "A line of text that differs\nat the end of the 2ND line."
+        mismatch = TextEquals(expected).match(observed)
+        details = mismatch.get_details()
+        self.assertThat(details, ContainsDict({"diff": IsInstance(Content)}))
+        self.assertThat(details["diff"].as_text(), Equals(dedent("""\
+        --- expected
+        +++ observed
+          A line of text that differs
+        - at the end of the 2nd line.
+        ?                    ^^
+        + at the end of the 2ND line.
+        ?                    ^^
+        """)))
+
+    def test_includes_diff_of_coerced_arguments(self):
+        expected = "A tuple", "that differs", "here."
+        observed = "A tuple", "that differs", "HERE."
+        mismatch = TextEquals(expected).match(observed)
+        details = mismatch.get_details()
+        self.assertThat(details, ContainsDict({"diff": IsInstance(Content)}))
+        self.assertThat(details["diff"].as_text(), Equals(dedent("""\
+        --- expected
+        +++ observed
+        - ('A tuple', 'that differs', 'here.')
+        ?                              ^^^^
+        + ('A tuple', 'that differs', 'HERE.')
+        ?                              ^^^^
+        """)))