Matcher

A matcher taking no argument is given as a string such like "be_null". A matcher taking an argument is given as a dictionary such like equal: 1.

A Value given as a Matcher is equivalent to equal: it.

For Objects

Matchers for Objects

Name	Arguments	Description
be	none	Matches an object that matches the given matcher.
be_null	none	Matches null.
not_be_null	none	Matches not null.
equal	Value	Matches an equal object
have_length	Integer	Matches an object that has a length and whose length matches the given matcher.

For Comparable Values

Matchers for Comparable Values

Name	Arguments	Description
be_greater_than	Comparable	Matches a value that is greater than the given value (it > argument).
be_greater_than_or_equal_to	Comparable	Matches a value that is greater than or equal to the given value (it >= argument).
be_less_than	Comparable	Matches a value that is less than the given value (it < argument).
be_less_than_or_equal_to	Comparable	Matches a value that is less than or equal to the given value (it <= argument).

For String Values

Matchers for String Values

Name	Arguments	Description
contain_string	String	Matches a string that contains the given string.
start_with	String	Matches a string that starts with the given string.
end_with	String	Matches a string that ends with the given string.
match_regexp	String	Matches a string that matches the given regular expression.

For Datetime Values

Note

Validated datetime values must be in ISO 8601 format like 2019-01-23T12:34:56Z.

Matchers for Datetime Values

Name	Arguments	Description
be_monday	none	Matches a datetime on Monday.
be_tuesday	none	Matches a datetime on Tuesday.
be_wednesday	none	Matches a datetime on Wednesday.
be_thursday	none	Matches a datetime on Thursday.
be_friday	none	Matches a datetime on Friday.
be_saturday	none	Matches a datetime on Saturday.
be_sunday	none	Matches a datetime on Sunday.
be_before	Datetime	Matches a datetime before the given datetime.
be_after	Datetime	Matches a datetime after the given datetime.

Datetime

The format of a datetime value is the same as Duration. Here are some examples.

- be_before: 2021-01-23T12:34:56Z  # Absolute
- be_after: -2 days  # Relative
- be_after: !relative_datetime  # Relative, with a format.
    delta: 1 second
    format: "%Y/%m/%d %H:%M:%S"

For Sequence Values

Matchers for Sequence Values

Name	Arguments	Description
be_empty	none	Matches an empty sequence.
have_item	Matcher	Matches a collection that has an item matching the given item.
have_items	List<Matcher>	Matches if all given items appear in the list, in any order.
contain_exactly	List<Matcher>	Exactly matches the entire sequence.
contain_in_any_order	List<Matcher>	Matches the entire sequence, but in any order.

Logical Matchers

Logical Matchers

Name	Arguments	Description
not	Matcher	Matches a value that doesn’t match the given matcher.
all_of	List<Matcher>	Matches a value that matches all of the given matchers.
any_of	List<Matcher>	Matches a value that matches any of the given matchers.
anything	none	Matches anything.

Custom matchers

You can define custom matchers and load as a plugins.

First, implement a custom matcher plugin like below.

"""
A custom matcher plugin example.
"""

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

from preacher.compilation.verification import MatcherFactoryCompiler
from preacher.plugin import hookimpl


class IsEven(BaseMatcher[int]):
    """
    A custom matcher example
    according to: https://pyhamcrest.readthedocs.io/en/stable/custom_matchers/
    """

    def _matches(self, item: int) -> bool:
        if not isinstance(item, int):
            return False
        return item % 2 == 0

    def describe_to(self, description: Description) -> None:
        description.append_text("even")


class IsMultipleOf(BaseMatcher[int]):
    """
    Another custom matcher example, which takes a value.
    """

    def __init__(self, base: int):
        self.base = base

    def _matches(self, item: int) -> bool:
        if not isinstance(item, int):
            return False
        return item % self.base == 0

    def describe_to(self, description: Description) -> None:
        description.append_text("multiple of ").append_description_of(self.base)


@hookimpl
def preacher_add_matchers(compiler: MatcherFactoryCompiler) -> None:
    """
    An example of hook to add matchers. This hook requires:
    - decoration of `preacher.plugin.hookimpl`
    - named `preacher_add_matchers`
    """

    # Add a static matcher.
    compiler.add_static(("be_even", "is_even", "even"), IsEven())

    # Add a matcher taking a value.
    compiler.add_taking_value(("be_multiple_of", "is_multiple_of", "multiple_of"), IsMultipleOf)

And then, run Preacher with loading that plugin.

$ preacher-cli -p path/to/plugin.py with-custom-matchers.yml

# with-custom-matchers.yml

label: Custom matchers example
response:
  body:
    describe: .six
    should:
      - be_even
      - be_multiple_of: 3