matchers

PyHamcrest Custom Matchers Guide

When to Create a Custom Matcher

Create a custom matcher when:

• Multiple tests check the same object's properties
• You want clearer failure messages than plain assertions provide

Don't create a matcher for a one-off assertion - plain assert is fine.

Spotting Opportunities

Test smell: Length assertion followed by individual item checks:

# Before - verbose and redundant length check
assert len(tasks_node.children) == 2
assert tasks_node.children[0].id == "ID_1"
assert tasks_node.children[0].title == "Task A"
assert tasks_node.children[1].id == "ID_2"
assert tasks_node.children[1].title == "Task B"

# After - expressive, no length check needed
assert_that(tasks_node.children, contains_exactly(
    node(id="ID_1", title="Task A"),
    node(id="ID_2", title="Task B"),
))

The contains_exactly matcher handles "exactly these items, no more, no less" - eliminating the redundant length assertion.

Naming Convention

Name matcher functions after the type they match, without an is_ prefix:

• node(...) not is_node(...)
• link(...) not is_link(...)

This reads naturally with contains_exactly: "contains exactly node with id X, node with id Y".

The Pattern

"""Custom PyHamcrest matchers for the test suite."""

from hamcrest.core.base_matcher import BaseMatcher
from hamcrest.core.description import Description

from myproject.domain import MyObject


class IsMyObjectMatcher(BaseMatcher):
    """Matcher for MyObject with optional property checks."""

    def __init__(self, name: str | None = None, value: int | None = None):
        self.expected_name = name
        self.expected_value = value

    def _matches(self, item) -> bool:
        if not isinstance(item, MyObject):
            return False
        if self.expected_name is not None and item.name != self.expected_name:
            return False
        if self.expected_value is not None and item.value != self.expected_value:
            return False
        return True

    def describe_to(self, description: Description) -> None:
        parts = ["a MyObject"]
        if self.expected_name is not None:
            parts.append(f"with name={self.expected_name!r}")
        if self.expected_value is not None:
            parts.append(f"with value={self.expected_value}")
        description.append_text(" ".join(parts))

    def describe_mismatch(self, item, mismatch_description: Description) -> None:
        if not isinstance(item, MyObject):
            mismatch_description.append_text(f"was {type(item).__name__}")
        elif self.expected_name is not None and item.name != self.expected_name:
            mismatch_description.append_text(f"had name={item.name!r}")
        elif self.expected_value is not None and item.value != self.expected_value:
            mismatch_description.append_text(f"had value={item.value}")


def my_object(name: str | None = None, value: int | None = None):
    """Match a MyObject with optional property checks."""
    return IsMyObjectMatcher(name=name, value=value)