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 thebool
result of the matcher and alist
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 thebool
result of the matcher and alist
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 thebool
result of the matcher and alist
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.