Add testtools.matchers.test module

End users can provide their own matchers. It is helpful
to provide a test harness for them to use to test this.

Signed-off-by: Stephen Finucane <stephen@that.guru>

Author: stephenfin

tests/matchers/test_basic.py

@@ -24,9 +24,9 @@
     _BinaryMismatch,
     _NotNearlyEqual,
 )
+from testtools.matchers.test import TestMatchersInterface
 
 from ..helpers import FullStackRunTest
-from ..matchers.helpers import TestMatchersInterface
 
 
 class Test_BinaryMismatch(TestCase):

tests/matchers/test_const.py

@@ -4,8 +4,7 @@
 
 from testtools import TestCase
 from testtools.matchers import Always, Never
-
-from ..matchers.helpers import TestMatchersInterface
+from testtools.matchers.test import TestMatchersInterface
 
 
 class TestAlwaysInterface(TestMatchersInterface, TestCase):

tests/matchers/test_datastructures.py

@@ -20,9 +20,9 @@
     MatchesSetwise,
     MatchesStructure,
 )
+from testtools.matchers.test import TestMatchersInterface
 
 from ..helpers import FullStackRunTest
-from ..matchers.helpers import TestMatchersInterface
 
 
 def run_doctest(obj, name):

tests/matchers/test_dict.py

@@ -14,8 +14,7 @@
     MatchesDict,
     _SubDictOf,
 )
-
-from ..matchers.helpers import TestMatchersInterface
+from testtools.matchers.test import TestMatchersInterface
 
 
 class TestMatchesAllDictInterface(TestCase, TestMatchersInterface):

tests/matchers/test_doctest.py

@@ -5,9 +5,9 @@
 
 from testtools import TestCase
 from testtools.matchers._doctest import DocTestMatches
+from testtools.matchers.test import TestMatchersInterface
 
 from ..helpers import FullStackRunTest
-from ..matchers.helpers import TestMatchersInterface
 
 
 class TestDocTestMatchesInterface(TestCase, TestMatchersInterface):

tests/matchers/test_exception.py

@@ -13,9 +13,9 @@
     Raises,
     raises,
 )
+from testtools.matchers.test import TestMatchersInterface
 
 from ..helpers import FullStackRunTest
-from ..matchers.helpers import TestMatchersInterface
 
 
 def make_error(type, *args, **kwargs):

tests/matchers/test_higherorder.py

@@ -23,9 +23,9 @@
     MatchesPredicateWithParams,
     Not,
 )
+from testtools.matchers.test import TestMatchersInterface
 
 from ..helpers import FullStackRunTest
-from ..matchers.helpers import TestMatchersInterface
 
 
 class TestAllMatch(TestCase, TestMatchersInterface):

tests/matchers/test_warnings.py

@@ -13,9 +13,9 @@
     MatchesStructure,
 )
 from testtools.matchers._warnings import IsDeprecated, WarningMessage, Warnings
+from testtools.matchers.test import TestMatchersInterface
 
 from ..helpers import FullStackRunTest
-from ..matchers.helpers import TestMatchersInterface
 
 
 def make_warning(warning_type, message):

tests/matchers/helpers.py testtools/matchers/test.pytests/matchers/helpers.py renamed to testtools/matchers/test.py

@@ -1,66 +1,15 @@
 # Copyright (c) 2008-2012 testtools developers. See LICENSE for details.
 
 import warnings
-from collections.abc import Callable
-from typing import Any, ClassVar, Protocol, runtime_checkable
+
+from testtools.matchers.test import TestMatchersInterface
 
 warnings.warn(
     "This module is deprecated for removal",
     DeprecationWarning,
     stacklevel=2,
 )
 
-
-@runtime_checkable
-class MatcherTestProtocol(Protocol):
-    """Protocol for test classes that test matchers."""
-
-    matches_matcher: ClassVar[Any]
-    matches_matches: ClassVar[Any]
-    matches_mismatches: ClassVar[Any]
-    str_examples: ClassVar[Any]
-    describe_examples: ClassVar[Any]
-    assertEqual: Callable[..., Any]
-    assertNotEqual: Callable[..., Any]
-    assertThat: Callable[..., Any]
-
-
-class TestMatchersInterface:
-    """Mixin class that provides test methods for matcher interfaces."""
-
-    __test__ = False  # Tell pytest not to collect this as a test class
-
-    def test_matches_match(self: MatcherTestProtocol) -> None:
-        matcher = self.matches_matcher
-        matches = self.matches_matches
-        mismatches = self.matches_mismatches
-        for candidate in matches:
-            self.assertEqual(None, matcher.match(candidate))
-        for candidate in mismatches:
-            mismatch = matcher.match(candidate)
-            self.assertNotEqual(None, mismatch)
-            self.assertNotEqual(None, getattr(mismatch, "describe", None))
-
-    def test__str__(self: MatcherTestProtocol) -> None:
-        # [(expected, object to __str__)].
-        from testtools.matchers._doctest import DocTestMatches
-
-        examples = self.str_examples
-        for expected, matcher in examples:
-            self.assertThat(matcher, DocTestMatches(expected))
-
-    def test_describe_difference(self: MatcherTestProtocol) -> None:
-        # [(expected, matchee, matcher), ...]
-        examples = self.describe_examples
-        for difference, matchee, matcher in examples:
-            mismatch = matcher.match(matchee)
-            self.assertEqual(difference, mismatch.describe())
-
-    def test_mismatch_details(self: MatcherTestProtocol) -> None:
-        # The mismatch object must provide get_details, which must return a
-        # dictionary mapping names to Content objects.
-        examples = self.describe_examples
-        for difference, matchee, matcher in examples:
-            mismatch = matcher.match(matchee)
-            details = mismatch.get_details()
-            self.assertEqual(dict(details), details)
+__all__ = [
+    "TestMatchersInterface",
+]