Matchers¶
Lemoncheesecake comes with support of matchers, a feature inspired by Hamcrest / PyHamcrest.
The following stock matchers are available:
- Values:
equal_to(expected)
: check if actual==
expectednot_equal_to(expected)
: check if actual!=
expectedgreater_than(expected)
: check if actual>
expectedgreater_than_or_equal_to(expected)
: check if actual>=
expectedless_than(expected)
: check if actual<
expectedless_than_or_equal_to(expected)
: check if actual<=
expectedis_between(min, max)
: check if actual is between min and maxis_none()
: check if actual== None
is_not_none()
: check if actual!= None
has_length(expected)
: check if value has expected length (expected
can be a value or aMatcher
object)is_true()
: check if value is a boolean trueis_false()
: check if value is a boolean falseis_json(expected)
: check is the actual JSON equalsexpected
, if not, the unified diff of actual vs expected is displayed
- Character strings:
starts_with(expected)
: check if the actual string starts withexpected
ends_with(expected)
: check if the actual string ends withexpected
match_pattern(expected)
: check if the actual string matchexpected
regexp (expected can be a raw string or an object returned byre.compile()
)is_text(expected)
: check is the actual (multi-lined) text equalsexpected
, if not, the unified diff of actual vs expected is displayed
- Types (
expected
is optional and can be a value or a matcher object):is_integer([expected])
: check if actual is of typeint
is_float([expected])
: check if actual is of typefloat
is_str([expected])
: check if actual is of typestr
(orunicode
if Python 2.7)is_dict([expected])
: check if actual is of typedict
is_list([expected])
: check if actual is of typelist
ortuple
is_bool([expected])
: check if actual is of typebool
- Iterable:
has_item(expected)
: check is actual iterable has an element that matches expected (expected can be a value or a Matcher)has_values(expected)
: check is actual iterable contains at least the expected valueshas_only_values(expected)
: check if actual iterable only contains the expected valuesis_in(expected)
: check if actual value is among the expected values
- Dict:
has_entry(expected_key [,expected_value])
: check if actual dict hasexpected_key
and (optionally) the expected associated valueexpected_value
(which can be a value or a matcher)
- Logical:
is_(expected)
: return the matcher ifexpected
is a matcher, otherwise wrapsexpected
in theequal_to
matcheris_not(expected)
: make the negation of theexpected
matcher (orequal_to
if the argument is not a matcher)all_of(matcher1, [matcher2, [...]])
: check if all the matchers succeed (logical AND between all the matchers)any_of(matcher1, [matcher2, [...]])
: check if any of the matchers succeed (logical OR between all the matchers)anything()
,something()
,existing()
: these matchers always succeed whatever the actual value is (only the matcher description changes to fit the matcher’s name)
Those matcher are used by a matching function:
check_that(hint, actual, matcher, quiet=False)
: run the matcher, log the result and return the matching result as a booleanrequire_that(hint, actual, matcher, quiet=False)
: run the matcher, log the result and raise anAbortTest
exception in case of a match failureassert_that(hint, actual, matcher, quiet=False)
: run the match, in case of a match failure (and only in this case) log the result and raise anAbortTest
exception
The quiet
flag can be set to True
to hide the matching result details in the report.
The lemoncheesecake.matching
module also provides helper functions to ease operations on dict object:
The code:
data = {"foo": 1, "bar": 2}
check_that("data", data, has_entry("foo", equal_to(1)))
check_that("data", data, has_entry("bar", equal_to(2)))
Can be shortened like this:
data = {"foo": 1, "bar": 2}
check_that_entry("foo", equal_to(1), in_=data)
check_that_entry("bar", equal_to(2), in_=data)
check_that_entry
can also be used with the context manager this_dict
:
with this_dict({"foo": 1, "bar": 2}):
check_that_entry("foo", equal_to(1))
check_that_entry("bar", equal_to(2))
check_that_in
can conveniently be used instead of this_dict
+ check_that_entry
when the context manager
block is only composed of calls to check_that_entry
:
check_that_in(
{"foo": 1, "bar": 2},
"foo", equal_to(1),
"bar", equal_to(2)
)
The same dict helper counter parts are available for require_that
and assert_that
:
require_that_entry
andrequire_that_in
assert_that_entry
andassert_that_in
If one match fails in a test, this test will be marked as failed.