Merge lp:~mwhudson/testtools/moar-matchers into lp:~testtools-committers/testtools/trunk

[Michael Hudson-Doyle]

This branch adds 5 more matchers that I felt compelled to write whilst working on linaro-image-tools to testtools: EachOf, MatchesStructure, MatchesRegex, MatchesSetwise and AfterPreprocessing. As is usually for "add code" code reviews, if there's anything that's unclear, it should be fixed in the branch, not in this description here!

You can see these matchers in action at https://code.launchpad.net/~mwhudson/linaro-image-tools/better-hwpack-matcher/+merge/42902 if the motivations are not obvious.

I've not contributed a big chunk of code to testtools before, so please educate me on local style :-)

Cheers,
mwh

[Michael Hudson-Doyle (mwhudson)]

Ah, I misunderstood bug 615108 and my EachOf isn't the same as the one proposed there. So I'm not sure what a good name would be.

[lp:~mwhudson/testtools/moar-matchers]

163. By Michael Hudson-Doyle on 2010-12-13

merge trunk

164. By Michael Hudson-Doyle on 2010-12-13

update NEWS

[Robert Collins (lifeless)]

Interesting, um processing - one c. Re each of,will need to read up.

On 13/12/2010 3:05 PM, "Michael Hudson-Doyle" <email address hidden>
wrote:

Ah, I misunderstood bug 615108 and my EachOf isn't the same as the one
proposed there. So I'm not sure what a good name would be.

--
https://code.launchpad.net/~mwhudson/testtools/moar-matchers/+merge/43489
You are subscribed to ...

[Jonathan Lange (jml)]

The tests & code look good. I'm going to review the documentation changes now and maybe rename a couple of the classes to work around the EachOf bug.

=== modified file 'NEWS'
--- NEWS	2010-12-13 01:15:11 +0000
+++ NEWS	2010-12-13 02:13:08 +0000
@@ -30,6 +30,31 @@
 Improvements
 ------------
 
+* New matchers:
+
+  * ``EachOf`` matches an iterable of matchers against an iterable of values.
+    (Michael Hudson-Doyle)
+
+  * ``MatchesRegex`` matches a string against a regular expression.  (Michael
+    Hudson-Doyle)
+
+  * ``MatchesStructure`` matches attributes of an object against given
+    matchers.  (Michael Hudson-Doyle)
+
+  * ``AfterPreproccessing`` matches values against a matcher after passing them
+    through a callable.  (Michael Hudson-Doyle)
+
+  * ``MatchesSetwise`` matches an iterable of matchers against an iterable of
+    values, without regard to order.  (Michael Hudson-Doyle)
+
+  * ``EndsWith`` which complements the existing ``StartsWith`` matcher.
+    (Jonathan Lange, #669165)
+
+  * ``MatchesException`` matches an exception class and parameters. (Robert
+    Collins)
+
+  * ``KeysEqual`` matches a dictionary with particular keys.  (Jonathan Lange)
+
 * ``assertIsInstance`` supports a custom error message to be supplied, which
   is necessary when using ``assertDictEqual`` on Python 2.7 with a
   ``testtools.TestCase`` base class. (Jelmer Vernooij)
@@ -43,22 +68,14 @@
 * Fix the runTest parameter of TestCase to actually work, rather than raising
   a TypeError.  (Jonathan Lange, #657760)
 
-* New matcher ``EndsWith`` added to complement the existing ``StartsWith``
-  matcher.  (Jonathan Lange, #669165)
-
 * Non-release snapshots of testtools will now work with buildout.
   (Jonathan Lange, #613734)
 
 * Malformed SyntaxErrors no longer blow up the test suite.  (Martin [gz])
 
-* ``MatchesException`` added to the ``testtools.matchers`` module - matches
-  an exception class and parameters. (Robert Collins)
-
 * ``MismatchesAll.describe`` no longer appends a trailing newline.
   (Michael Hudson-Doyle, #686790)
 
-* New ``KeysEqual`` matcher.  (Jonathan Lange)
-
 * New helpers for conditionally importing modules, ``try_import`` and
   ``try_imports``.  (Jonathan Lange)
 

=== modified file 'testtools/matchers.py'
--- testtools/matchers.py	2010-12-12 23:48:10 +0000
+++ testtools/matchers.py	2010-12-13 02:13:08 +0000
@@ -30,7 +30,9 @@
 import doctest
 import operator
 from pprint import pformat
+import re
 import sys
+import types
 
 from testtools.compat import classtypes, _error_repr, isbaseexception
 
@@ -528,3 +530,210 @@
     See `Raises` and `MatchesException` for more information.
     """
     return Raises(MatchesException(exception))
+
+
+class EachOf(object):
+    """Matches if each matcher matches the corresponding value.
+
+    More easily explained by example than in words:
+
+    >>> EachOf([Equals(1)]).match([1])
+    >>> EachOf([Equals(1), Equals(2)]).match([1, 2])
+    >>> print EachOf([Equals(1), Equals(2)]).match([2, 1]).describe()
+    Differences: [
+    1 != 2
+    2 != 1
+    ]
+    """
+
+    def __init__(self, matchers):
+        self.matchers = matchers
+
+    def match(self, values):
+        mismatches = []
+        length_mismatch = Annotate(
+            "Length mismatch", Equals(len(self.matchers))).match(len(values))
+        if length_mismatch:
+            mismatches.append(length_mismatch)
+        for matcher, value in zip(self.matchers, values):
+            mismatch = matcher.match(value)
+            if mismatch:
+                mismatches.append(mismatch)
+        if mismatches:
+            return MismatchesAll(mismatches)
+
+
+class MatchesStructure(object):
+    """Matcher that matches an object structurally.
+
+    'Structurally' here means that attributes of the object being matched are
+    compared against given matchers.
+
+    `fromExample` allows the creation of a matcher from a prototype object and
+    then modified versions can be created with `update`.
+    """
+
+    def __init__(self, **kwargs):
+        self.kws = kwargs
+
+    @classmethod
+    def fromExample(cls, example, *attributes):
+        kwargs = {}
+        for attr in attributes:
+            kwargs[attr] = Equals(getattr(example, attr))
+        return cls(**kwargs)
+
+    def update(self, **kws):
+        new_kws = self.kws.copy()
+        for attr, matcher in kws.iteritems():
+            if matcher is None:
+                new_kws.pop(attr, None)
+            else:
+                new_kws[attr] = matcher
+        return type(self)(**new_kws)
+
+    def __str__(self):
+        kws = []
+        for attr, matcher in sorted(self.kws.iteritems()):
+            kws.append("%s=%s" % (attr, matcher))
+        return "%s(%s)" % (self.__class__.__name__, ', '.join(kws))
+
+    def match(self, value):
+        matchers = []
+        values = []
+        for attr, matcher in sorted(self.kws.iteritems()):
+            matchers.append(Annotate(attr, matcher))
+            values.append(getattr(value, attr))
+        return EachOf(matchers).match(values)
+
+
+class MatchesRegex(object):
+    """Matches if the matchee is matched by a regular expression."""
+
+    def __init__(self, pattern, flags=0):
+        self.pattern = pattern
+        self.flags = flags
+
+    def __str__(self):
+        args = ['%r' % self.pattern]
+        flag_arg = []
+        # dir() sorts the attributes for us, so we don't need to do it again.
+        for flag in dir(re):
+            if len(flag) == 1:
+                if self.flags & getattr(re, flag):
+                    flag_arg.append('re.%s' % flag)
+        if flag_arg:
+            args.append('|'.join(flag_arg))
+        return '%s(%s)' % (self.__class__.__name__, ', '.join(args))
+
+    def match(self, value):
+        if not re.match(self.pattern, value, self.flags):
+            return Mismatch("%r did not match %r" % (self.pattern, value))
+
+
+class MatchesSetwise(object):
+    """Matches if all the matchers match elements of the value being matched.
+
+    The difference compared to `EachOf` is that the order of the matchings
+    does not matter.
+    """
+
+    def __init__(self, *matchers):
+        self.matchers = matchers
+
+    def match(self, observed):
+        remaining_matchers = set(self.matchers)
+        not_matched = []
+        for value in observed:
+            for matcher in remaining_matchers:
+                if matcher.match(value) is None:
+                    remaining_matchers.remove(matcher)
+                    break
+            else:
+                not_matched.append(value)
+        if not_matched or remaining_matchers:
+            remaining_matchers = list(remaining_matchers)
+            # There are various cases that all should be reported somewhat
+            # differently.
+
+            # There are two trivial cases:
+            # 1) There are just some matchers left over.
+            # 2) There are just some values left over.
+
+            # Then there are three more interesting cases:
+            # 3) There are the same number of matchers and values left over.
+            # 4) There are more matchers left over than values.
+            # 5) There are more values left over than matchers.
+
+            if len(not_matched) == 0:
+                if len(remaining_matchers) > 1:
+                    msg = "There were %s matchers left over: " % (
+                        len(remaining_matchers),)
+                else:
+                    msg = "There was 1 matcher left over: "
+                msg += ', '.join(map(str, remaining_matchers))
+                return Mismatch(msg)
+            elif len(remaining_matchers) == 0:
+                if len(not_matched) > 1:
+                    return Mismatch(
+                        "There were %s values left over: %s" % (
+                            len(not_matched), not_matched))
+                else:
+                    return Mismatch(
+                        "There was 1 value left over: %s" % (
+                            not_matched, ))
+            else:
+                common_length = min(len(remaining_matchers), len(not_matched))
+                if common_length == 0:
+                    raise AssertionError("common_length can't be 0 here")
+                if common_length > 1:
+                    msg = "There were %s mismatches" % (common_length,)
+                else:
+                    msg = "There was 1 mismatch"
+                if len(remaining_matchers) > len(not_matched):
+                    extra_matchers = remaining_matchers[common_length:]
+                    msg += " and %s extra matcher" % (len(extra_matchers), )
+                    if len(extra_matchers) > 1:
+                        msg += "s"
+                    msg += ': ' + ', '.join(map(str, extra_matchers))
+                elif len(not_matched) > len(remaining_matchers):
+                    extra_values = not_matched[common_length:]
+                    msg += " and %s extra value" % (len(extra_values), )
+                    if len(extra_values) > 1:
+                        msg += "s"
+                    msg += ': ' + str(extra_values)
+                return Annotate(
+                    msg, EachOf(remaining_matchers[:common_length])
+                    ).match(not_matched[:common_length])
+
+
+class AfterPreproccessing(object):
+    """Matches if the value matches after passing through a function.
+
+    This can be used to aid in creating trivial matchers as functions, for
+    example:
+
+    def PathHasFileContent(content):
+        def _read(path):
+            return open(path).read()
+        return AfterPreproccessing(_read, Equals(content))
+    """
+
+    def __init__(self, preprocessor, matcher):
+        self.preprocessor = preprocessor
+        self.matcher = matcher
+
+    def _str_preprocessor(self):
+        if isinstance(self.preprocessor, types.FunctionType):
+            return '<function %s>' % self.preprocessor.__name__
+        return str(self.preprocessor)
+
+    def __str__(self):
+        return "AfterPreproccessing(%s, %s)" % (
+            self._str_preprocessor(), self.matcher)
+
+    def match(self, value):
+        value = self.preprocessor(value)
+        return Annotate(
+            "after %s" % self._str_preprocessor(),
+            self.matcher).match(value)

=== modified file 'testtools/tests/test_matchers.py'
--- testtools/tests/test_matchers.py	2010-12-12 23:48:10 +0000
+++ testtools/tests/test_matchers.py	2010-12-13 02:13:08 +0000
@@ -3,6 +3,8 @@
 """Tests for matchers."""
 
 import doctest
+import re
+import StringIO
 import sys
 
 from testtools import (
@@ -10,11 +12,13 @@
     TestCase,
     )
 from testtools.matchers import (
+    AfterPreproccessing,
     Annotate,
     Equals,
     DocTestMatches,
     DoesNotEndWith,
     DoesNotStartWith,
+    EachOf,
     EndsWith,
     KeysEqual,
     Is,
@@ -22,6 +26,9 @@
     MatchesAny,
     MatchesAll,
     MatchesException,
+    MatchesRegex,
+    MatchesSetwise,
+    MatchesStructure,
     Mismatch,
     Not,
     NotEquals,
@@ -446,6 +453,193 @@
         self.assertEqual("bar", mismatch.expected)
 
 
+def run_doctest(obj, name):
+    p = doctest.DocTestParser()
+    t = p.get_doctest(
+        obj.__doc__, sys.modules[obj.__module__].__dict__, name, '', 0)
+    r = doctest.DocTestRunner()
+    output = StringIO.StringIO()
+    r.run(t, out=output.write)
+    return r.failures, output.getvalue()
+
+
+class TestEachOf(TestCase):
+
+    def test_docstring(self):
+        failure_count, output = run_doctest(EachOf, "EachOf")
+        if failure_count:
+            self.fail("Doctest failed with %s" % output)
+
+
+class TestMatchesStructure(TestCase, TestMatchersInterface):
+
+    class SimpleClass:
+        def __init__(self, x, y):
+            self.x = x
+            self.y = y
+
+    matches_matcher = MatchesStructure(x=Equals(1), y=Equals(2))
+    matches_matches = [SimpleClass(1, 2)]
+    matches_mismatches = [
+        SimpleClass(2, 2),
+        SimpleClass(1, 1),
+        SimpleClass(3, 3),
+        ]
+
+    str_examples = [
+        ("MatchesStructure(x=Equals(1))", MatchesStructure(x=Equals(1))),
+        ("MatchesStructure(y=Equals(2))", MatchesStructure(y=Equals(2))),
+        ("MatchesStructure(x=Equals(1), y=Equals(2))",
+         MatchesStructure(x=Equals(1), y=Equals(2))),
+        ]
+
+    describe_examples = [
+        ("""\
+Differences: [
+3 != 1: x
+]""", SimpleClass(1, 2), MatchesStructure(x=Equals(3), y=Equals(2))),
+        ("""\
+Differences: [
+3 != 2: y
+]""", SimpleClass(1, 2), MatchesStructure(x=Equals(1), y=Equals(3))),
+        ("""\
+Differences: [
+0 != 1: x
+0 != 2: y
+]""", SimpleClass(1, 2), MatchesStructure(x=Equals(0), y=Equals(0))),
+        ]
+
+    def test_fromExample(self):
+        self.assertThat(
+            self.SimpleClass(1, 2),
+            MatchesStructure.fromExample(self.SimpleClass(1, 3), 'x'))
+
+    def test_update(self):
+        self.assertThat(
+            self.SimpleClass(1, 2),
+            MatchesStructure(x=NotEquals(1)).update(x=Equals(1)))
+
+    def test_update_none(self):
+        self.assertThat(
+            self.SimpleClass(1, 2),
+            MatchesStructure(x=Equals(1), z=NotEquals(42)).update(
+                z=None))
+
+
+class TestMatchesRegex(TestCase, TestMatchersInterface):
+
+    matches_matcher = MatchesRegex('a|b')
+    matches_matches = ['a', 'b']
+    matches_mismatches = ['c']
+
+    str_examples = [
+        ("MatchesRegex('a|b')", MatchesRegex('a|b')),
+        ("MatchesRegex('a|b', re.M)", MatchesRegex('a|b', re.M)),
+        ("MatchesRegex('a|b', re.I|re.M)", MatchesRegex('a|b', re.I|re.M)),
+        ]
+
+    describe_examples = [
+        ("'a|b' did not match 'c'", 'c', MatchesRegex('a|b')),
+        ]
+
+
+class TestMatchesSetwise(TestCase):
+
+    def assertMismatchWithDescriptionMatching(self, value, matcher,
+                                              description_matcher):
+        mismatch = matcher.match(value)
+        if mismatch is None:
+            self.fail("%s matched %s" % (matcher, value))
+        actual_description = mismatch.describe()
+        self.assertThat(
+            actual_description,
+            Annotate(
+                "%s matching %s" % (matcher, value),
+                description_matcher))
+
+    def test_matches(self):
+        self.assertIs(
+            None, MatchesSetwise(Equals(1), Equals(2)).match([2, 1]))
+
+    def test_mismatches(self):
+        self.assertMismatchWithDescriptionMatching(
+            [2, 3], MatchesSetwise(Equals(1), Equals(2)),
+            MatchesRegex('.*There was 1 mismatch$', re.S))
+
+    def test_too_many_matchers(self):
+        self.assertMismatchWithDescriptionMatching(
+            [2, 3], MatchesSetwise(Equals(1), Equals(2), Equals(3)),
+            Equals('There was 1 matcher left over: Equals(1)'))
+
+    def test_too_many_values(self):
+        self.assertMismatchWithDescriptionMatching(
+            [1, 2, 3], MatchesSetwise(Equals(1), Equals(2)),
+            Equals('There was 1 value left over: [3]'))
+
+    def test_two_too_many_matchers(self):
+        self.assertMismatchWithDescriptionMatching(
+            [3], MatchesSetwise(Equals(1), Equals(2), Equals(3)),
+            MatchesRegex(
+                'There were 2 matchers left over: Equals\([12]\), '
+                'Equals\([12]\)'))
+
+    def test_two_too_many_values(self):
+        self.assertMismatchWithDescriptionMatching(
+            [1, 2, 3, 4], MatchesSetwise(Equals(1), Equals(2)),
+            MatchesRegex(
+                'There were 2 values left over: \[[34], [34]\]'))
+
+    def test_mismatch_and_too_many_matchers(self):
+        self.assertMismatchWithDescriptionMatching(
+            [2, 3], MatchesSetwise(Equals(0), Equals(1), Equals(2)),
+            MatchesRegex(
+                '.*There was 1 mismatch and 1 extra matcher: Equals\([01]\)',
+                re.S))
+
+    def test_mismatch_and_too_many_values(self):
+        self.assertMismatchWithDescriptionMatching(
+            [2, 3, 4], MatchesSetwise(Equals(1), Equals(2)),
+            MatchesRegex(
+                '.*There was 1 mismatch and 1 extra value: \[[34]\]',
+                re.S))
+
+    def test_mismatch_and_two_too_many_matchers(self):
+        self.assertMismatchWithDescriptionMatching(
+            [3, 4], MatchesSetwise(
+                Equals(0), Equals(1), Equals(2), Equals(3)),
+            MatchesRegex(
+                '.*There was 1 mismatch and 2 extra matchers: '
+                'Equals\([012]\), Equals\([012]\)', re.S))
+
+    def test_mismatch_and_two_too_many_values(self):
+        self.assertMismatchWithDescriptionMatching(
+            [2, 3, 4, 5], MatchesSetwise(Equals(1), Equals(2)),
+            MatchesRegex(
+                '.*There was 1 mismatch and 2 extra values: \[[145], [145]\]',
+                re.S))
+
+
+class TestAfterPreproccessing(TestCase, TestMatchersInterface):
+
+    def parity(x):
+        return x % 2
+
+    matches_matcher = AfterPreproccessing(parity, Equals(1))
+    matches_matches = [3, 5]
+    matches_mismatches = [2]
+
+    str_examples = [
+        ("AfterPreproccessing(<function parity>, Equals(1))",
+         AfterPreproccessing(parity, Equals(1))),
+        ]
+
+    describe_examples = [
+        ("1 != 0: after <function parity>",
+         2,
+         AfterPreproccessing(parity, Equals(1))),
+        ]
+
+
 def test_suite():
     from unittest import TestLoader
     return TestLoader().loadTestsFromName(__name__)