pyassert is an assertion library for the Python programming language.
Assertions are used in automated tests to verify that a given piece of code behaves as expected. pyassert aims to provide assertions with provide
- rich functionality: common assertions should be expressed easily
- good readability: assertions should be easy to read and easy to understand to enhance the overall understandability of the test
- independent of the test framework: pyassert assertions work with every Python test environment.
How to install it?
pyassert is available via the Cheeseshop so you can use easy_install or pip:
$ pip install pyassert
How to use it?
The most important function pyassert provides is assert_that. This function is used to start an assertion. You pass in the actual value and as a result you get an AssertionHandler (although you will never care, most of the time).
The AssertionHandler provides several assertion predicates. These are functions you can use to verify a given state of the actual value.
from pyassert import * assert_that('spam and eggs').ends_with('eggs') assert_that(['spam', 'and', 'eggs']).contains(any_of('spam', 'ham'))
The general structure is
Every assertion will return None if the actual value matches the expectations or raise an AssertionError with a readable message in case the expectations are not met.
The following matcher are provided by pyassert.
is_not_equal_to- Asserts that two objects are (not) equal (using
is_not_identical_to- Asserts that two objects are (not) identical (using
is_not_none- Asserts that an object is (not)
does_not_raise- Asserts that a given callable raises/ does not raise an expected exception
does_not_contain- Asserts that the actual string contains an expected string
does_not_end_with- Asserts that the actual string ends with an expected string
is_not_empty- Asserts that the actual string is empty
does_not_match- Asserts that the actual string matches the expected regular expression
does_not_start_with- Asserts that actual string starts with the expected string
List/ Tuple Matchers
does_not_contain- Asserts that actual list/ tuple contains the expected elements.
is_not_empty?- Asserts that actual list/ tuple is empty
is_true- Asserts that the actual object is
is_false- Asserts that the actual object is
is_not_an_instance_of- Asserts that the actual object is an instance of the expected type
is_a- Asserts that the actual object is of the actual type
lt- Asserts that the actual number is less than the expected number
le- Asserts that the actual number is less or equal than the expected number
gt- Asserts that the actual number is greater than the expected number
ge- Asserts that the actual number is greater or equal than the expected number
is_not_a_directory- Asserts that a given string names an existing directory
is_not_a_file- Asserts that a given string names an existing file
has_file_length_of- Asserts that a given string names an existing file with an expected file length in bytes
is_a_empty_file- Asserts that a given string names an existing empty file
is_a_file_with_content- Asserts that a given string names an existing file with the expected content
How to extend it?
pyassert uses Matchers to match actual values against expected values. A matcher is simply a class extending the pyassert Matcher class which looks like this:
class Matcher (object): def accepts (self, actual): """Returns True if the given actual value is accepted by this matcher.""" return True def matches (self, actual): """Returns True if the given actual value matches this matcher. Returns False otherwise""" pass def describe (self, actual): """Returns a description which is used in case the actual value did not match this matcher's expectation.""" pass
Once you have created your Matcher you need to register it. The registration is done with a class decorator register_matcher providing the name of the matcher
from pyassert import Matcher, register_matcher @register_matcher("matches_my_matcher") class MyMatcher (Matcher): ...
Now your matcher is available using
All arguments that are passed to the matches_my_matcher function call are passed to the constructor of MyMatcher that is used by this assertion.
If you have a matcher that should also be available in a negated manner (such as
can register the matcher twice but set the second one to negated:
from pyassert import Matcher, register_matcher @register_matcher("matches_my_matcher") @register_matcher("does_not_match_my_matcher", negated=True) class MyMatcher (Matcher): ...
If you also want to provide a custom message that describes the failed, negated state, you can additionally override
describe_negated method in your matcher class. See this example
@register_matcher("is_empty") @register_negated_matcher("is_not_empty") class IsEmptyMatcher(ListOrTupleMatcher, StringMatcher): def matches(self, actual): return len(actual) == 0 def describe(self, actual): return "'%s' is not empty" % actual def describe_negated(self, actual): return "'%s' is empty" % actual
Version 0.4.2 released 2014-03-03
does_not_containmatcher to ContainsMatcher (Pull-Request by @fraisse, Sylvain Fraïssé)
- Enabled flake8 plugin
Version 0.4.1 released 2013-02-13
- Allow any collection in ListOrTupleMatcher (Pull-Request by @charlax, Charles-Axel Dein)
Version 0.3.2 released 2013-02-14
Version 0.3.1 released 2012-10-01
- Added filesystem matchers
- Using six to provide compatibiliy with Python 3
Version 0.2.5 released 2012-09-24
- Negated matchers
Version 0.2.4 released 2012-09-20
- Added number matchers
is_equal_toas alias to
equalswhich is now deprecated
- Hosting project as part of the pyclectic organisation
Version 0.2.3 released 2012-09-11
Version 0.2.2 released 2012-08-29
Version 0.2.1 released 2012-08-28
is_a matcherthat assert that actual values are of an expected type
- pyassert is now compatible with Python 3 (see Travis Build)