2 files changed, 44 insertions, 0 deletions
diff --git a/lib/subunit/python/testtools/matchers.py b/lib/subunit/python/testtools/matchers.py
index 244daceb7f..039c84b7c7 100644
--- a/lib/subunit/python/testtools/matchers.py
+++ b/lib/subunit/python/testtools/matchers.py
@@ -12,6 +12,7 @@ $ python -c 'import testtools.matchers; print testtools.matchers.__all__'
 
 __metaclass__ = type
 __all__ = [
+    'Annotate',
     'DocTestMatches',
     'Equals',
     'MatchesAll',
@@ -249,3 +250,33 @@ class MatchedUnexpectedly:
 
     def describe(self):
         return "%r matches %s" % (self.other, self.matcher)
+
+
+class Annotate:
+    """Annotates a matcher with a descriptive string.
+
+    Mismatches are then described as '<mismatch>: <annotation>'.
+    """
+
+    def __init__(self, annotation, matcher):
+        self.annotation = annotation
+        self.matcher = matcher
+
+    def __str__(self):
+        return 'Annotate(%r, %s)' % (self.annotation, self.matcher)
+
+    def match(self, other):
+        mismatch = self.matcher.match(other)
+        if mismatch is not None:
+            return AnnotatedMismatch(self.annotation, mismatch)
+
+
+class AnnotatedMismatch:
+    """A mismatch annotated with a descriptive string."""
+
+    def __init__(self, annotation, mismatch):
+        self.annotation = annotation
+        self.mismatch = mismatch
+
+    def describe(self):
+        return '%s: %s' % (self.mismatch.describe(), self.annotation)
diff --git a/lib/subunit/python/testtools/tests/test_matchers.py b/lib/subunit/python/testtools/tests/test_matchers.py
index d5fd8bab3b..74b1ebc56a 100644
--- a/lib/subunit/python/testtools/tests/test_matchers.py
+++ b/lib/subunit/python/testtools/tests/test_matchers.py
@@ -9,6 +9,7 @@ from testtools import (
     TestCase,
     )
 from testtools.matchers import (
+    Annotate,
     Equals,
     DocTestMatches,
     MatchesAny,
@@ -153,6 +154,18 @@ class TestMatchesAllInterface(TestCase, TestMatchersInterface):
                           1, MatchesAll(NotEquals(1), NotEquals(2)))]
 
 
+class TestAnnotate(TestCase, TestMatchersInterface):
+
+    matches_matcher = Annotate("foo", Equals(1))
+    matches_matches = [1]
+    matches_mismatches = [2]
+
+    str_examples = [
+        ("Annotate('foo', Equals(1))", Annotate("foo", Equals(1)))]
+
+    describe_examples = [("1 != 2: foo", 2, Annotate('foo', Equals(1)))]
+
+
 def test_suite():
     from unittest import TestLoader
     return TestLoader().loadTestsFromName(__name__)