Custom Matchers¶

Introduction¶

Expects can be extended by defining new matchers. The matchers module contains the bases for building custom matchers.

Tutorial¶

The easiest way to define a new matcher is to extend the Matcher class and override the Matcher._match() method.

For example, to define a matcher to check if a request object contains a given header takes <10 lines of code:

from expects.matchers import Matcher

class have_header(Matcher):
    def __init__(self, expected):
        self._expected = expected

    def _match(self, request):
        if self._expected in request.headers:
            return True, ['header found']
        return True, ['header not found']

An then you only need to import the new defined matcher and write your expectation:

from expects import expect
from my_custom_matchers import have_header

expect(my_request).to(have_header('Content-Type'))

Advanced¶

For more complex matchers you can override the Matcher methods in order to achieve the needed behavior.

class expects.matchers.Matcher¶

The Matcher class is the base class for all Expects matchers.

It defines a set of methods to ease writting new matchers.

_failure_message(subject, reasons)¶

This method will be called from an expectation only when the expectation is going to fail. It should return a string with the failure message.

By default returns a failure message with the following format:

expected: {subject} to {description}
     but: {reasons}

With the passed subject repr, this matcher repr as description and the passed reasons from the matcher result.

Parameters:	subject (a string) – The target value of the expectation. reasons (list of strings) – A list of reasons that caused this matcher to fail.
Return type:	a string

_failure_message_negated(subject, reasons)¶

Like the _failure_message() method but will be called when a negated expectation is going to fail. It should return a string with the failure message for the negated expectation.

By default returns a failure message with the following format:

expected: {subject} to {description}
     but: {reasons}

Parameters:	subject (a string) – The target value of the expectation. reasons (list of strings) – A list of reasons that caused this matcher to fail.
Return type:	a string

_match(subject)¶

This method will be called when the matcher is used in an expectation. It should be overwritten to implement the matcher logic. If not raises NotImplementedError.

Receives the expectation subject as the unique positional argument and should return a tuple with the bool result of the matcher and a list of reasons for this result.

If the matcher matches the subject then the boolean result should be True. The reasons should be a list with 0 or more strings.

Parameters:	subject – The target value of the expectation.
Return type:	tuple (bool, [str])

_match_negated(subject)¶

Like _match() but will be called when used in a negated expectation. It can be used to implement a custom logic for negated expectations.

By default returns the result of negating self._match(subject).

Parameters:	subject – The target value of the expectation.
Return type:	tuple (bool, [str])

class expects.matchers._And(op1, op2)¶

_match(subject)¶

This method will be called when the matcher is used in an expectation. It should be overwritten to implement the matcher logic. If not raises NotImplementedError.

Receives the expectation subject as the unique positional argument and should return a tuple with the bool result of the matcher and a list of reasons for this result.

If the matcher matches the subject then the boolean result should be True. The reasons should be a list with 0 or more strings.

Parameters:	subject – The target value of the expectation.
Return type:	tuple (bool, [str])

class expects.matchers._Or(op1, op2)¶

_match(subject)¶

This method will be called when the matcher is used in an expectation. It should be overwritten to implement the matcher logic. If not raises NotImplementedError.

Receives the expectation subject as the unique positional argument and should return a tuple with the bool result of the matcher and a list of reasons for this result.

If the matcher matches the subject then the boolean result should be True. The reasons should be a list with 0 or more strings.

Parameters:	subject – The target value of the expectation.
Return type:	tuple (bool, [str])

Testing¶

The testing module provides helpers to ease the testing of your custom matchers.