Package: precisely
Precisely allows you to write precise assertions so you only test the behaviour you’re really interested in.
This makes it clearer to the reader what the expected behaviour is,
and makes tests less brittle.
This also allows better error messages to be generated when assertions fail.
Inspired byHamcrest.For instance, suppose we want to make sure that auniquefunction removes duplicates from a list.
We might write a test like so:frompreciselyimportassert_that,contains_exactlydeftest_unique_removes_duplicates():result=unique(["a","a","b","a","b"])assert_that(result,contains_exactly("a","b"))The assertion will pass so long asresultcontains"a"and"b"in any order,
but no other items.
Unlike, say,assert result == ["a", "b"], our assertion ignores the ordering of elements.
This is useful when:the ordering of the result is non-determistic, such as when usingset.the ordering isn’t specified in the contract ofunique.
If we assert a particular ordering, then we’d be testing the implementation rather than the contract.the ordering is specified in the contract ofunique,
but the ordering is tested in a separate test case.When the assertion fails,
rather than just stating the two values weren’t equal,
the error message will describe the failure in more detail.
For instance, if unique has the value["a", "a", "b"],
we’d get the failure message:Expected: iterable containing in any order:
  * 'a'
  * 'b'
but: had extra elements:
  * 'a'Installationpip install preciselyAPIUseassert_that(value, matcher)to assert that a value satisfies a matcher.Many matchers are composed of other matchers.
If they are given a value instead of a matcher,
then that value is wrapped inequal_to().
For instance,has_attrs(name="bob")is equivalent tohas_attrs(name=equal_to("bob")).equal_to(value): matches a value if it is equal tovalueusing==.has_attrs(**kwargs): matches a value if it has the specified attributes.
For instance:assert_that(result,has_attrs(id=is_instance(int),name="bob"))has_attr(attribute_name, matcher): matches a value if it has the specified attribute.
Usinghas_attrsis generally considered more idiomatic when the attribute name is constant.
For instance, instead of:assert_that(result,has_attr("id",is_instance(int)))use:assert_that(result, has_attrs(id=is_instance(int)))contains_exactly(*args): matches an iterable if it has the same elements in any order.
For instance:assert_that(result,contains_exactly("a","b"))# Matches ["a", "b"] and ["b", "a"],# but not ["a", "a", "b"] nor ["a"] nor ["a", "b", "c"]is_sequence(*args): matches an iterable if it has the same elements in the same order.
For instance:assert_that(result,is_sequence("a","b"))# Matches ["a", "b"]# but not ["b", "a"] nor ["a", "b", "c"] nor ["c", "a", "b"]includes(*args): matches an iterable if it includes all of the elements.
For instance:assert_that(result,includes("a","b"))# Matches ["a", "b"], ["b", "a"] and ["a", "c", "b"]# but not ["a", "c"] nor ["a"]assert_that(result,includes("a","a"))# Matches ["a", "a"] and ["a", "a", "a"]# but not ["a"]all_elements(matcher): matches an iterable if every element matchesmatcher.
For instance:assert_that(result,all_elements(equal_to(42)))# Matches [42], [42, 42, 42] and []# but not [42, 43]is_mapping(matchers): matches a mapping, such as adict, if it has the same keys with matching values.
An error will be raised if the mapping is missing any keys, or has any extra keys.
For instance:assert_that(result,is_mapping({"a":equal_to(1),"b":equal_to(4),}))mapping_includes(matchers): matches a mapping, such as adict, if it has the same keys with matching values.
An error will be raised if the mapping is missing any keys, but extra keys are allowed.
For instance:assert_that(result,mapping_includes({"a":equal_to(1),"b":equal_to(4),}))# Matches {"a": 1, "b": 4} and {"a": 1, "b": 4, "c": 5}# but not {"a": 1} nor {"a": 1, "b": 5}anything: matches all values.is_instance(type): matches any value whereisinstance(value, type).all_of(*matchers): matchers a value if all sub-matchers match.
For instance:assert_that(result,all_of(is_instance(User),has_attrs(name="bob"),))any_of(*matchers): matchers a value if any sub-matcher matches.
For instance:assert_that(result,any_of(equal_to("x=1, y=2"),equal_to("y=2, x=1"),))not_(matcher): negates a matcher.
For instance:assert_that(result,not_(equal_to("hello")))starts_with(prefix): matches a string if it starts withprefix.contains_string(substring): matches a string if it containssubstring.greater_than(value): matches values greater thanvalue.greater_than_or_equal_to(value): matches values greater than or equal tovalue.less_than(value): matches values less thanvalue.less_than_or_equal_to(value): matches values less than or equal tovalue.close_to(value, delta): matches values close tovaluewithin a tolerance of +/-delta.has_feature(name, extract, matcher): matchesvalueifextract(value)matchesmatcher.
For instance:assert_that(result,has_feature("len",len,equal_to(2)))For clarity, it often helps to extract the use ofhas_featureinto its own function:defhas_len(matcher):returnhas_feature("len",len,matcher)assert_that(result,has_len(equal_to(2)))raises(matcher): matchesvalueifvalue()raises an exception matched bymatcher.
For instance:assert_that(lambda:func("arg"),raises(is_instance(ValueError)))AlternativesPyHamcrest is another Python implemention of matchers. I prefer the error
messages that this project produces, but feel free to judge for yourself:# Preciselyfrompreciselyimportassert_that,is_sequence,has_attrsassert_that([User("bob","jim@example.com"),User("jim","bob@example.com"),],is_sequence(has_attrs(username="bob",email_address="bob@example.com"),has_attrs(username="jim",email_address="jim@example.com"),))# Expected: iterable containing in order:#   0: attributes:#     * username: 'bob'#     * email_address: 'bob@example.com'#   1: attributes:#     * username: 'jim'#     * email_address: 'jim@example.com'# but: element at index 0 mismatched:#   * attribute email_address: was 'jim@example.com'# Hamcrestfromhamcrestimportassert_that,contains,has_propertiesassert_that([User("bob","jim@example.com"),User("jim","bob@example.com"),],contains(has_properties(username="bob",email_address="bob@example.com"),has_properties(username="jim",email_address="jim@example.com"),))# Hamcrest error:# Expected: a sequence containing [(an object with a property 'username' matching 'bob' and an object with a property 'email_address' matching 'bob@example.com'), (an object with a property 'username' matching 'jim' and an object with a property 'email_address' matching 'jim@example.com')]#      but: item 0: an object with a property 'email_address' matching 'bob@example.com' property 'email_address' was 'jim@example.com'