#11616 disttrial worker test improvements

setup.cfg

@@ -51,6 +51,7 @@ packages = find:
 test =
     cython-test-exception-raiser >= 1.0.2, <2
     PyHamcrest >= 1.9.0
+    hypothesis ~= 6.0
 
 ; List of dependencies required to build the documentation and test the
 ; release scripts and process.

src/twisted/trial/_dist/test/matchers.py

@@ -5,8 +5,48 @@
 Hamcrest matchers useful throughout the test suite.
 """
 
-from hamcrest import equal_to, has_length, has_properties
+__all__ = [
+    "matches_result",
+    "HasSum",
+    "IsSequenceOf",
+]
+
+from typing import List, Sequence, Tuple, TypeVar
+
+from hamcrest import (
+    contains_exactly,
+    contains_string,
+    equal_to,
+    has_length,
+    has_properties,
+    instance_of,
+)
+from hamcrest.core.base_matcher import BaseMatcher
+from hamcrest.core.core.allof import AllOf
+from hamcrest.core.description import Description
 from hamcrest.core.matcher import Matcher
+from typing_extensions import Protocol
+
+from twisted.python.failure import Failure
+
+T = TypeVar("T")
+
+
+class Semigroup(Protocol[T]):
+    """
+    A type with an associative binary operator.
+
+    Common examples of a semigroup are integers with addition and strings with
+    concatenation.
+    """
+
+    def __add__(self, other: T) -> T:
+        """
+        This must be associative: a + (b + c) == (a + b) + c
+        """
+
+
+S = TypeVar("S", bound=Semigroup)
 
 
 def matches_result(
@@ -30,3 +70,134 @@ def matches_result(
             "unexpectedSuccesses": unexpectedSuccesses,
         }
     )
+
+
+class HasSum(BaseMatcher[Sequence[S]]):
+    """
+    Match a sequence the elements of which sum to a value matched by
+    another matcher.
+
+    :ivar sumMatcher: The matcher which must match the sum.
+    :ivar zero: The zero value for the matched type.
+    """
+
+    def __init__(self, sumMatcher: Matcher[S], zero: S) -> None:
+        self.sumMatcher = sumMatcher
+        self.zero = zero
+
+    def _sum(self, sequence: Sequence[S]) -> S:
+        if not sequence:
+            return self.zero
+        result = self.zero
+        for elem in sequence:
+            result = result + elem
+        return result
+
+    def _matches(self, item: Sequence[S]) -> bool:
+        """
+        Determine whether the sum of the sequence is matched.
+        """
+        s = self._sum(item)
+        return self.sumMatcher.matches(s)
+
+    def describe_mismatch(self, item: Sequence[S], description: Description) -> None:
+        """
+        Describe the mismatch.
+        """
+        s = self._sum(item)
+        description.append_description_of(self)
+        self.sumMatcher.describe_mismatch(s, description)
+        return None
+
+    def describe_to(self, description: Description) -> None:
+        """
+        Describe this matcher for error messages.
+        """
+        description.append_text("a sequence with sum ")
+        description.append_description_of(self.sumMatcher)
+        description.append_text(", ")
+
+
+class IsSequenceOf(BaseMatcher[Sequence[T]]):
+    """
+    Match a sequence where every element is matched by another matcher.
+
+    :ivar elementMatcher: The matcher which must match every element of the
+        sequence.
+    """
+
+    def __init__(self, elementMatcher: Matcher[T]) -> None:
+        self.elementMatcher = elementMatcher
+
+    def _matches(self, item: Sequence[T]) -> bool:
+        """
+        Determine whether every element of the sequence is matched.
+        """
+        for elem in item:
+            if not self.elementMatcher.matches(elem):
+                return False
+        return True
+
+    def describe_mismatch(self, item: Sequence[T], description: Description) -> None:
+        """
+        Describe the mismatch.
+        """
+        for idx, elem in enumerate(item):
+            if not self.elementMatcher.matches(elem):
+                description.append_description_of(self)
+                description.append_text(f"not sequence with element #{idx} {elem!r}")
+
+    def describe_to(self, description: Description) -> None:
+        """
+        Describe this matcher for error messages.
+        """
+        description.append_text("a sequence containing only ")
+        description.append_description_of(self.elementMatcher)
+        description.append_text(", ")
+
+
+def isFailure(**properties: Matcher[object]) -> Matcher[object]:
+    """
+    Match an instance of L{Failure} with matching attributes.
+    """
+    return AllOf(
+        instance_of(Failure),
+        has_properties(**properties),
+    )
+
+
+def similarFrame(
+    functionName: str, fileName: str
+) -> Matcher[Sequence[Tuple[str, str, int, List[object], List[object]]]]:
+    """
+    Match a tuple representation of a frame like those used by
+    L{twisted.python.failure.Failure}.
+    """
+    # The frames depend on exact layout of the source
+    # code in files and on the filesystem so we won't
+    # bother being very precise here.  Just verify we
+    # see some distinctive fragments.
+    #
+    # In particular, the last frame should be a tuple like
+    #
+    # (functionName, fileName, someint, [], [])
+    return contains_exactly(
+        equal_to(functionName),
+        contains_string(fileName),  # type: ignore[arg-type]
+        instance_of(int),  # type: ignore[arg-type]
+        # Unfortunately Failure makes them sometimes tuples, sometimes
+        # dict_items.
+        has_length(0),  # type: ignore[arg-type]
+        has_length(0),  # type: ignore[arg-type]
+    )
+
+
+def isTuple(*matchers: Matcher[object]) -> Matcher[object]:
+    """
+    Match tuples for which the elements are matched by corresponding
+    elements of a tuple of matchers.
+    """
+    return AllOf(
+        instance_of(tuple),
+        contains_exactly(*matchers),  # type: ignore[arg-type]
+    )