assertpy
Simple assertions library for unit testing in Python with a nice fluent API. Supports both Python 2 and 3.
Usage
Just import the assert_that function, and away you go...
from assertpy import assert_that
def test_something():
assert_that(1 + 2).is_equal_to(3)
assert_that('foobar').is_length(6).starts_with('foo').ends_with('bar')
assert_that(['a', 'b', 'c']).contains('a').does_not_contain('x')
Of course, assertpy works best with a python test runner like pytest (our favorite) or Nose.
Installation
Install via pip
The assertpy library is available via PyPI. Just install with:
pip install assertpy
Install via conda
Or, if you are a big fan of conda like we are, there is an assertpy-feedstock for Conda-Forge that you can use:
conda install assertpy --channel conda-forge
The API
The fluent API of assertpy is designed to create compact, yet readable tests. The API has been modeled after other fluent testing APIs, especially the awesome AssertJ assertion library for Java. Of course, in the assertpy library everything is fully pythonic and designed to take full advantage of the dynamism in the Python runtime.
Strings
Matching strings:
assert_that('').is_not_none()
assert_that('').is_empty()
assert_that('').is_false()
assert_that('').is_type_of(str)
assert_that('').is_instance_of(str)
assert_that('foo').is_length(3)
assert_that('foo').is_not_empty()
assert_that('foo').is_true()
assert_that('foo').is_alpha()
assert_that('123').is_digit()
assert_that('foo').is_lower()
assert_that('FOO').is_upper()
assert_that('foo').is_iterable()
assert_that('foo').is_equal_to('foo')
assert_that('foo').is_not_equal_to('bar')
assert_that('foo').is_equal_to_ignoring_case('FOO')
assert_that(u'foo').is_unicode() # on python 2
assert_that('foo').is_unicode() # on python 3
assert_that('foo').contains('f')
assert_that('foo').contains('f','oo')
assert_that('foo').contains_ignoring_case('F','oO')
assert_that('foo').does_not_contain('x')
assert_that('foo').contains_only('f','o')
assert_that('foo').contains_sequence('o','o')
assert_that('foo').contains_duplicates()
assert_that('fox').does_not_contain_duplicates()
assert_that('foo').is_in('foo','bar','baz')
assert_that('foo').is_not_in('boo','bar','baz')
assert_that('foo').is_subset_of('abcdefghijklmnopqrstuvwxyz')
assert_that('foo').starts_with('f')
assert_that('foo').ends_with('oo')
assert_that('foo').matches(r'\w')
assert_that('123-456-7890').matches(r'\d{3}-\d{3}-\d{4}')
assert_that('foo').does_not_match(r'\d+')
Regular expressions can be tricky. Be sure to use raw strings (prefix the pattern string with r) for the regex pattern to be matched. Also, note that the matches() function passes for partial matches (as does the re.match function that underlies it). If you want to match the entire string, just include anchors in the regex pattern.
# partial matches, these all pass
assert_that('foo').matches(r'\w')
assert_that('foo').matches(r'oo')
assert_that('foo').matches(r'\w{2}')
# match the entire string with an anchored regex pattern, passes
assert_that('foo').matches(r'^\w{3}$')
# fails
assert_that('foo').matches(r'^\w{2}$')
Additionally, while assertpy matches() assertion does not have support for re.match flags such as re.MULTILINE or re.DOTALL, it works as expected with inline flags in the pattern.
s = """bar
foo
baz"""
# use multiline inline flag (?m)
assert_that(s).matches(r'(?m)^foo$')
# use dotall inline flag (?s)
assert_that(s).matches(r'(?s)b(.*)z')
Numbers
Matching integers:
assert_that(0).is_not_none()
assert_that(0).is_false()
assert_that(0).is_type_of(int)
assert_that(0).is_instance_of(int)
assert_that(0).is_zero()
assert_that(1).is_not_zero()
assert_that(1).is_positive()
assert_that(-1).is_negative()
assert_that(123).is_equal_to(123)
assert_that(123).is_not_equal_to(456)
assert_that(123).is_greater_than(100)
assert_that(123).is_greater_than_or_equal_to(123)
assert_that(123).is_less_than(200)
assert_that(123).is_less_than_or_equal_to(200)
assert_that(123).is_between(100, 200)
assert_that(123).is_close_to(100, 25)
assert_that(1).is_in(0,1,2,3)
assert_that(1).is_not_in(-1,-2,-3)
Matching floats:
assert_that(0.0).is_not_none()
assert_that(0.0).is_false()
assert_that(0.0).is_type_of(float)
assert_that(0.0).is_instance_of(float)
assert_that(123.4).is_equal_to(123.4)
assert_that(123.4).is_not_equal_to(456.7)
assert_that(123.4).is_greater_than(100.1)
assert_that(123.4).is_greater_than_or_equal_to(123.4)
assert_that(123.4).is_less_than(200.2)
assert_that(123.4).is_less_than_or_equal_to(123.4)
assert_that(123.4).is_between(100.1, 200.2)
assert_that(123.4).is_close_to(123, 0.5)
assert_that(float('NaN')).is_nan()
assert_that(123.4).is_not_nan()
assert_that(float('Inf')).is_inf()
assert_that(123.4).is_not_inf()
Of course, using is_equal_to() with a float value is just asking for trouble. You'll always want to use the assertions methods like is_close_to() and is_between().
Lists
Matching lists:
assert_that([]).is_not_none()
assert_that([]).is_empty()
assert_that([]).is_false()
assert_that([]).is_type_of(list)
assert_that([]).is_instance_of(list)
assert_that([]).is_iterable()
assert_that(['a','b']).is_length(2)
assert_that(['a','b']).is_not_empty()
assert_that(['a','b']).is_equal_to(['a','b'])
assert_that(['a','b']).is_not_equal_to(['b','a'])
assert_that(['a','b']).contains('a')
assert_that(['a','b']).contains('b','a')
assert_that(['a','b']).does_not_contain('x','y')
assert_that(['a','b']).contains_only('a','b')
assert_that(['a','a']).contains_only('a')
assert_that(['a','b','c']).contains_sequence('b','c')
assert_that(['a','b']).is_subset_of(['a','b','c'])
assert_that(['a','x','x']).contains_duplicates()
assert_that(['a','b','c']).does_not_contain_duplicates()
assert_that(['a','b','c']).starts_with('a')
assert_that(['a','b','c']).ends_with('c')
List Flattening
Lists of lists can be flattened on any item (by index) using the extracting helper (see dict flattening):
people = [['Fred', 'Smith'], ['Bob', 'Barr']]
assert_that(people).extracting(0).is_equal_to(['Fred','Bob'])
assert_that(people).extracting(-1).is_equal_to(['Smith','Barr'])
Tuples
Matching tuples:
assert_that(()).is_not_none()
assert_that(()).is_empty()
assert_that(()).is_false()
assert_that(()).is_type_of(tuple)
assert_that(()).is_instance_of(tuple)
assert_that(()).is_iterable()
assert_that((1,2,3)).is_length(3)
assert_that((1,2,3)).is_not_empty()
assert_that((1,2,3)).is_equal_to((1,2,3))
assert_that((1,2,3)).is_not_equal_to((1,2,4))
assert_that((1,2,3)).contains(1)
assert_that((1,2,3)).contains(3,2,1)
assert_that((1,2,3)).does_not_contain(4,5,6)
assert_that((1,2,3)).contains_only(1,2,3)
assert_that((1,1,1)).contains_only(1)
assert_that((1,2,3)).contains_sequence(2,3)
assert_that((1,2,3)).is_subset_of((1,2,3,4))
assert_that((1,2,2)).contains_duplicates()
assert_that((1,2,3)).does_not_contain_duplicates()
assert_that((1,2,3)).starts_with(1)
assert_that((1,2,3)).ends_with(3)
Tuple Flattening
Tuples of tuples can be flattened on any item (by index) using the extracting helper (see dict flattening):
points = ((1,2,3),(4,5,6))
assert_that(points).extracting(0).is_equal_to([1, 4])
assert_that(points).extracting(-1).is_equal_to([3, 6])
Dicts
Matching dicts:
assert_that({}).is_not_none()
assert_that({}).is_empty()
assert_that({}).is_false()
assert_that({}).is_type_of(dict)
assert_that({}).is_instance_of(dict)
assert_that({'a':1,'b':2}).is_length(2)
assert_that({'a':1,'b':2}).is_not_empty()
assert_that({'a':1,'b':2}).is_equal_to({'a':1,'b':2})
assert_that({'a':1,'b':2}).is_equal_to({'b':2,'a':1})
assert_that({'a':1,'b':2}).is_not_equal_to({'a':1,'b':3})
assert_that({'a':1,'b':2}).contains('a')
assert_that({'a':1,'b':2}).contains('b','a')
assert_that({'a':1,'b':2}).does_not_contain('x')
assert_that({'a':1,'b':2}).does_not_contain('x','y')
assert_that({'a':1,'b':2}).contains_only('a','b')
assert_that({'a':1,'b':2}).is_subset_of({'a':1,'b':2,'c':3})
# contains_key() is just an alias for contains()
assert_that({'a':1,'b':2}).contains_key('a')
assert_that({'a':1,'b':2}).contains_key('b','a')
# does_not_contain_key() is just an alias for does_not_contain()
assert_that({'a':1,'b':2}).does_not_contain_key('x')
assert_that({'a':1,'b':2}).does_not_contain_key('x','y')
assert_that({'a':1,'b':2}).contains_value(1)
assert_that({'a':1,'b':2}).contains_value(2,1)
assert_that({'a':1,'b':2}).does_not_contain_value(3)
assert_that({'a':1,'b':2}).does_not_contain_value(3,4)
assert_that({'a':1,'b':2}).contains_entry({'a':1})
assert_that({'a':1,'b':2}).contains_entry({'a':1},{'b':2})
assert_that({'a':1,'b':2}).does_not_contain_entry({'a':2})
assert_that({'a':1,'b':2}).does_not_contain_entry({'a':2},{'b':1})
Dict Comparison
Dict keys can optionally be ignored or included when using the is_equal_to() assertion.
Ignore dict keys with the ignore keyword argument:
# ignore a single key
assert_that({'a':1,'b':2}).is_equal_to({'a':1}, ignore='b')
# ignore multiple keys using a list
assert_that({'a':1,'b':2,'c':3}).is_equal_to({'a':1}, ignore=['b','c'])
# ignore nested keys using a tuple
assert_that({'a':1,'b':{'c':2,'d':3}}).is_equal_to({'a':1,'b':{'c':2}}, ignore=('b','d'))
Or include dict keys with the include keyword argument:
# include a single key
assert_that({'a':1,'b':2}).is_equal_to({'a':1}, include='a')
# include multiple keys using a list
assert_that({'a':1,'b':2,'c':3}).is_equal_to({'a':1,'b':2}, include=['a','b'])
# include nested keys using a tuple
assert_that({'a':1,'b':{'c':2,'d':3}}).is_equal_to({'b':{'d':3}}, include=('b','d'))
Or do both:
assert_that({'a':1,'b':{'c':2,'d':3,'e':4,'f':5}}).is_equal_to(
{'b':{'d':3,'f':5}},
ignore=[('b','c'),('b','e')],
include='b'
)
Dict Flattening
Lists of dicts can be flattened on key using the extracting helper (see extracting attributes):
fred = {'first_name': 'Fred', 'last_name': 'Smith'}
bob = {'first_name': 'Bob', 'last_name': 'Barr'}
people = [fred, bob]
assert_that(people).extracting('first_name').is_equal_to(['Fred','Bob'])
assert_that(people).extracting('first_name').contains('Fred','Bob')
Dict Key Assertions
Fluent assertions against the value of a given key can be done by prepending has_ to the key name (see dynamic assertions):
fred = {'first_name': 'Fred', 'last_name': 'Smith', 'shoe_size': 12}
assert_that(fred).has_first_name('Fred')
assert_that(fred).has_last_name('Smith')
assert_that(fred).has_shoe_size(12)
Sets
Matching sets:
assert_that(set([])).is_not_none()
assert_that(set([])).is_empty()
assert_that(set([])).is_false()
assert_that(set([])).is_type_of(set)
assert_that(set([])).is_instance_of(set)
assert_that(set(['a','b'])).is_length(2)
assert_that(set(['a','b'])).is_not_empty()
assert_that(set(['a','b'])).is_equal_to(set(['a','b']))
assert_that(set(['a','b'])).is_equal_to(set(['b','a']))
assert_that(set(['a','b'])).is_not_equal_to(set(['a','x']))
assert_that(set(['a','b'])).contains('a')
assert_that(set(['a','b'])).contains('b','a')
assert_that(set(['a','b'])).does_not_contain('x','y')
assert_that(set(['a','b'])).contains_only('a','b')
assert_that(set(['a','b'])).is_subset_of(set(['a','b','c']))
assert_that(set(['a','b'])).is_subset_of(set(['a']), set(['b']))
Booleans
Matching booleans:
assert_that(True).is_true()
assert_that(False).is_false()
assert_that(True).is_type_of(bool)
None
Matching None:
assert_that(None).is_none()
assert_that('').is_not_none()
assert_that(None).is_type_of(type(None))
Dates
Matching dates:
import datetime
today = datetime.datetime.today()
yesterday = today - datetime.timedelta(days=1)
assert_that(yesterday).is_before(today)
assert_that(today).is_after(yesterday)
You can also make assertions about date equality (ignoring various units of time) like this:
today_0us = today - datetime.timedelta(microseconds=today.microsecond)
today_0s = today - datetime.timedelta(seconds=today.second)
today_0h = today - datetime.timedelta(hours=today.hour)
assert_that(today).is_equal_to_ignoring_milliseconds(today_0us)
assert_that(today).is_equal_to_ignoring_seconds(today_0s)
assert_that(today).is_equal_to_ignoring_time(today_0h)
assert_that(today).is_equal_to(today)
You can use these numeric assertions on dates:
middle = today - datetime.timedelta(hours=12)
hours_24 = datetime.timedelta(hours=24)
assert_that(today).is_greater_than(yesterday)
assert_that(yesterday).is_less_than(today)
assert_that(middle).is_between(yesterday, today)
#note that the tolerance must be a datetime.timedelta object
assert_that(yesterday).is_close_to(today, hours_24)
Lastly, because datetime is an object we can easily test the properties of a given date by prepending has_ to the property name (see dynamic assertions):
# 1980-01-02 03:04:05.000006
x = datetime.datetime(1980, 1, 2, 3, 4, 5, 6)
assert_that(x).has_year(1980)
assert_that(x).has_month(1)
assert_that(x).has_day(2)
assert_that(x).has_hour(3)
assert_that(x).has_minute(4)
assert_that(x).has_second(5)
assert_that(x).has_microsecond(6)
Currently, assertpy only supports dates via the datetime type.
Files
Matching files:
assert_that('foo.txt').exists()
assert_that('missing.txt').does_not_exist()
assert_that('foo.txt').is_file()
assert_that('mydir').exists()
assert_that('missing_dir').does_not_exist()
assert_that('mydir').is_directory()
assert_that('foo.txt').is_named('foo.txt')
assert_that('foo.txt').is_child_of('mydir')
Matching file contents is done using the contents_of() helper to read the file into a string with the given encoding (if no encoding is given it defaults to utf-8). Once the file is read into a string, you can make quick work of it using the assertpy string assertions like this:
from assertpy import assert_that, contents_of
contents = contents_of('foo.txt', 'ascii')
assert_that(contents).starts_with('foo').ends_with('bar').contains('oob')
Objects
Matching an object:
fred = Person('Fred','Smith')
assert_that(fred).is_not_none()
assert_that(fred).is_true()
assert_that(fred).is_type_of(Person)
assert_that(fred).is_instance_of(object)
assert_that(fred).is_same_as(fred)
Matching an attribute, a property, and a method:
assert_that(fred.first_name).is_equal_to('Fred')
assert_that(fred.name).is_equal_to('Fred Smith')
assert_that(fred.say_hello()).is_equal_to('Hello, Fred!')
Given fred is an instance of the following Person class:
class Person(object):
def __init__(self, first_name, last_name):
self.first_name = first_name
self.last_name = last_name
@property
def name(self):
return '%s %s' % (self.first_name, self.last_name)
def say_hello(self):
return 'Hello, %s!' % self.first_name
Extracting Attributes from Objects
It is frequently necessary to test collections of objects. The assertpy library includes an extracting helper to flatten the collection on a given attribute, like this:
fred = Person('Fred','Smith')
bob = Person('Bob','Barr')
people = [fred, bob]
assert_that(people).extracting('first_name').is_equal_to(['Fred','Bob'])
assert_that(people).extracting('first_name').contains('Fred','Bob')
assert_that(people).extracting('first_name').does_not_contain('Charlie')
Of course extracting works with subclasses too...suppose we create a simple class hierarchy by creating a Developer subclass of Person, like this:
class Developer(Person):
def say_hello(self):
return '%s writes code.' % self.first_name
Testing a mixed collection of parent and child objects works as expected:
fred = Person('Fred','Smith')
joe = Developer('Joe','Coder')
people = [fred, joe]
assert_that(people).extracting('first_name').contains('Fred','Joe')
Additionally, the extracting helper can accept a list of attributes to be extracted, and will flatten them into a list of tuples:
assert_that(people).extracting('first_name', 'last_name').contains(('Fred','Smith'), ('Joe','Coder'))
Lastly, extracting works on not just class attributes, but also properties, and even zero-argument methods:
assert_that(people).extracting('name').contains('Fred Smith', 'Joe Coder')
assert_that(people).extracting('say_hello').contains('Hello, Fred!', 'Joe writes code.')
As noted above, the extracting helper also works on a collection of dicts:
fred = {'first_name': 'Fred', 'last_name': 'Smith'}
bob = {'first_name': 'Bob', 'last_name': 'Barr'}
people = [fred, bob]
assert_that(people).extracting('first_name').contains('Fred','Bob')
Extracting and Filtering
The extracting helper can include a filter to keep only those items for which the given filter is truthy. For example, suppose we have the following list of dicts we wish to test:
users = [
{'user': 'Fred', 'age': 36, 'active': True},
{'user': 'Bob', 'age': 40, 'active': False},
{'user': 'Johnny', 'age': 13, 'active': True}
]
The filter can be the name of a key (or attribute, or property, or zero-argument method) and the extracted items are kept if the corresponding value is truthy:
assert_that(users).extracting('user', filter='active')\
.is_equal_to(['Fred','Johnny'])
The filter can be a dict-like object and the extracted items are kept if all corresponding key-value pairs are equal:
assert_that(users).extracting('user', filter={'active': False})\
.is_equal_to(['Bob'])
assert_that(users).extracting('user', filter={'age': 36, 'active': True})\
.is_equal_to(['Fred'])
The filter can be any function (including an in-line lambda) that accepts as its single argument each item in the collection and the extracted items are kept if the function evaluates to True:
assert_that(users).extracting('user', filter=lambda x: x['age'] > 20)\
.is_equal_to(['Fred', 'Bob'])
Extracting and Sorting
The extracting helper can include a sort to enforce order on the extracted items.
The sort can be the name of a key (or attribute, or property, or zero-argument method) and the extracted items are ordered by the corresponding values:
assert_that(users).extracting('user', sort='age').is_equal_to(['Johnny','Fred','Bob'])
The sort can be an iterable of names and the extracted items are ordered by corresponding value of the first name, ties are broken by the corresponding values of the second name, and so on:
assert_that(users).extracting('user', sort=['active','age']).is_equal_to(['Bob','Johnny','Fred'])
The sort can be any function (including an in-line lambda) that accepts as its single argument each item in the collection and the extracted items are ordered by the corresponding function return values:
assert_that(users).extracting('user', sort=lambda x: -x['age'])\
.is_equal_to(['Bob','Fred','Johnny'])
Dynamic Assertions on Objects
When testing attributes of an object, the basic assertpy assertions can get a little verbose like this:
fred = Person('Fred','Smith')
assert_that(fred.first_name).is_equal_to('Fred')
assert_that(fred.name).is_equal_to('Fred Smith')
assert_that(fred.say_hello()).is_equal_to('Hello, Fred!')
So, assertpy takes advantage of the awesome dyanmism in the Python runtime to provide dynamic assertions in the form of has_<name>() where <name> is the name of any attribute, property, or zero-argument method on the given object.
Using dynamic assertions, we can rewrite the above assertions in a more compact and readable way like this:
assert_that(fred).has_first_name('Fred')
assert_that(fred).has_name('Fred Smith')
assert_that(fred).has_say_hello('Hello, Fred!')
Since fred has the attribute first_name, the dynamic assertion method has_first_name() is available. Similarly, the property name can be tested via has_name() and the zero-argument method say_hello() via the has_say_hello() assertion.
As noted above, dynamic assertions also work on dicts:
fred = {'first_name': 'Fred', 'last_name': 'Smith'}
assert_that(fred).has_first_name('Fred')
assert_that(fred).has_last_name('Smith')
Failure
The assertpy library includes a fail() method to explicitly force a test failure. It can be used like this:
from assertpy import assert_that,fail
def test_fail():
fail('forced failure')
A very useful test pattern that requires the fail() method is to verify the exact contents of an error message. For example:
from assertpy import assert_that,fail
def test_error_msg():
try:
some_func('foo')
fail('should have raised error')
except RuntimeError as e:
assert_that(str(e)).is_equal_to('some err')
In the above code, we invoke some_func() with a bad argument which raises an exception. The exception is then handled by the try..except block and the exact contents of the error message are verified. Lastly, if an exception is not thrown by some_func() as expected, we fail the test via fail().
This pattern is only used when you need to verify the contents of the error message. If you only wish to check for an expected exception (and don't need to verify the contents of the error message itself), you're much better off using a test runner that supports expected exceptions. Nose provides a @raises decorator. Pytest has a pytest.raises method.
Expected Exceptions
We recommend you use your test runner to check for expected exceptions (Pytest's pytest.raises context or Nose's @raises decorator). In the special case of invoking a function, assertpy provides its own expected exception handling via a simple fluent API.
Given a function some_func():
def some_func(arg):
raise RuntimeError('some err')
We can expect a RuntimeError with:
assert_that(some_func).raises(RuntimeError).when_called_with('foo')
Additionally, the error message contents are chained, and can be further verified:
assert_that(some_func).raises(RuntimeError).when_called_with('foo')\
.is_length(8).starts_with('some').is_equal_to('some err')
Custom Error Messages
Sometimes you need a little more information in your failures. For this case, assertpy includes a described_as() helper that will add a custom message when a failure occurs. For example, if we had these failing assertions:
assert_that(1+2).is_equal_to(2)
assert_that(1+2).described_as('adding stuff').is_equal_to(2)
When run (separately, of course), they would produce these errors:
Expected <3> to be equal to <2>, but was not.
[adding stuff] Expected <3> to be equal to <2>, but was not.
The described_as() helper causes the custom message adding stuff to be prepended to the front of the second error.
Just A Warning
There are times when you only want a warning message instead of a failing test. For example, if you are using assertpy to write defensive assertions in the normal flow of your application (not in a test). In this case, just replace assert_that with assert_warn.
assert_warn('foo').is_length(4)
assert_warn('foo').is_empty()
assert_warn('foo').is_false()
assert_warn('foo').is_digit()
assert_warn('123').is_alpha()
assert_warn('foo').is_upper()
assert_warn('FOO').is_lower()
assert_warn('foo').is_equal_to('bar')
assert_warn('foo').is_not_equal_to('foo')
assert_warn('foo').is_equal_to_ignoring_case('BAR')
Even though all of the above assertions fail, an AssertionError is never raised and execution is not halted. Instead, the failed assertions merely log the following warning messages to stdout:
2019-10-27 20:00:35 WARNING [test_readme.py:423]: Expected <foo> to be of length <4>, but was <3>.
2019-10-27 20:00:35 WARNING [test_readme.py:424]: Expected <foo> to be empty string, but was not.
2019-10-27 20:00:35 WARNING [test_readme.py:425]: Expected <False>, but was not.
2019-10-27 20:00:35 WARNING [test_readme.py:426]: Expected <foo> to contain only digits, but did not.
2019-10-27 20:00:35 WARNING [test_readme.py:427]: Expected <123> to contain only alphabetic chars, but did not.
2019-10-27 20:00:35 WARNING [test_readme.py:428]: Expected <foo> to contain only uppercase chars, but did not.
2019-10-27 20:00:35 WARNING [test_readme.py:429]: Expected <FOO> to contain only lowercase chars, but did not.
2019-10-27 20:00:35 WARNING [test_readme.py:430]: Expected <foo> to be equal to <bar>, but was not.
2019-10-27 20:00:35 WARNING [test_readme.py:431]: Expected <foo> to be not equal to <foo>, but was.
2019-10-27 20:00:35 WARNING [test_readme.py:432]: Expected <foo> to be case-insensitive equal to <BAR>, but was not.
Custom Warning Logger
By default, warnings are written to stdout with a formatter that includes timestamp, log level WARNING, and message, plus some stack frame magic to find the correct filename and line number where assert_warn() was called and failed. For more control or better log formatting, you can pass in your own customer logger when you call assert_warn().
assert_warn('foo', logger=my_logger).is_length(4)
assert_warn('foo', logger=my_logger).is_equal_to_ignoring_case('BAR')
Soft Assertions
Normally, an assertion failure will halt test execution immediately by raising an error. Soft assertions are way to collect assertion failures together, to be raise all at once at the end, without halting your test. To use soft assertions in assertpy, just use the with soft_assertions() context manager, like this:
from assertpy import assert_that, soft_assertions
with soft_assertions():
assert_that('foo').is_length(4)
assert_that('foo').is_empty()
assert_that('foo').is_false()
assert_that('foo').is_digit()
assert_that('123').is_alpha()
assert_that('foo').is_upper()
assert_that('FOO').is_lower()
assert_that('foo').is_equal_to('bar')
assert_that('foo').is_not_equal_to('foo')
assert_that('foo').is_equal_to_ignoring_case('BAR')
At the end of the block, all assertion failures are collected together and a single AssertionError is raised:
AssertionError: soft assertion failures:
1. Expected <foo> to be of length <4>, but was <3>.
2. Expected <foo> to be empty string, but was not.
3. Expected <False>, but was not.
4. Expected <foo> to contain only digits, but did not.
5. Expected <123> to contain only alphabetic chars, but did not.
6. Expected <foo> to contain only uppercase chars, but did not.
7. Expected <FOO> to contain only lowercase chars, but did not.
8. Expected <foo> to be equal to <bar>, but was not.
9. Expected <foo> to be not equal to <foo>, but was.
10. Expected <foo> to be case-insensitive equal to <BAR>, but was not.
Also, note that only assertion failures are collected, errors such as TypeError or ValueError are raised immediately. Triggering an explicit test failure with fail() will similarly halt execution immediately. If you need more forgiving behavior, you can use soft_fail() which is collected like any other failing assertion within a soft assertions block.
Snapshot Testing
Take a snapshot of a python data structure, store it on disk in JSON format, and automatically compare the latest data to the stored data on every test run. The snapshot testing features of assertpy are borrowed from Jest, a well-kwown and powerful Javascript testing framework. Snapshots require Python 3.
For example, snapshot the following dict:
assert_that({'a':1,'b':2,'c':3}).snapshot()
Stored on disk as the following JSON:
{
"a": 1,
"b": 2,
"c": 3
}
Additionally, the on-disk snapshot format supports most python data structures (dict, list, object, etc). For example:
assert_that(None).snapshot()
assert_that(True).snapshot()
assert_that(123).snapshot()
assert_that(-987.654).snapshot()
assert_that('foo').snapshot()
assert_that([1,2,3]).snapshot()
assert_that(set(['a','b','c'])).snapshot()
assert_that({'a':1,'b':2,'c':3}).snapshot()
assert_that(1 + 2j).snapshot()
assert_that(someobj).snapshot()
Snapshot artifacts (typically found in the __snapshots folder), should be committed to source control alongside any code changes.
On the first run (when the snapshot file doesn't yet exist), the snapshot is created, stored to disk, and the test is passed. On all subsequent runs, the given data is compared to the on-disk snapshot, and the test fails if they don't match. Failure means that some change occured, so either a bug or a known implementation changed.
Updating Snapshots
It's easy to update your snapshots...just delete them all and re-run the test suite to regenerate all snapshots.
Snapshot Parameters
By default, snapshots are identified by test filename plus line number. Alternately, you can specify a custom identifier using the id keyword:
assert_that({'a':1,'b':2,'c':3}).snapshot(id='my-custom-id')
By default, all snapshots (including those with custom identifiers) are stored in the __snapshots folder. Alternately, you can specify a custom path using the path keyword:
assert_that({'a':1,'b':2,'c':3}).snapshot(path='my-custom-folder')
Snapshot Blackbox
Functional testing (which snapshot testing falls under) is very much blackbox testing. When something goes wrong, it's hard to pinpoint the issue, because functional tests provide little isolation. On the plus side, snapshots can provide enormous leverage as a few well-placed snapshot tests can strongly verify an application is working that would otherwise require dozens if not hundreds of unit tests.
Extension System - adding custom assertions
Sometimes you want to add your own custom assertions to assertpy. This can be done using the add_extension() helper.
For example, we can write a custom is_5() assertion like this:
from assertpy import add_extension
def is_5(self):
if self.val != 5:
self._err(f'{self.val} is NOT 5!')
return self
add_extension(is_5)
Once registered with assertpy, we can use our new assertion as expected:
assert_that(5).is_5()
assert_that(6).is_5() # fails!
Of course, is_5() is only available in the test file where add_extension() is called. If you want better control of scope of your custom extensions, such as writing extensions once and using them in any test file, you'll need to use the test setup functionality of your test runner. With pytest, you can just use a conftest.py file and a fixture.
For example, if your conftest.py is:
import pytest
from assertpy import add_extension
def is_5(self):
if self.val != 5:
self._err(f'{self.val} is NOT 5!')
return self
@pytest.fixture(scope='module')
def my_extensions():
add_extension(is_5)
Then in any test method in any test file (like test_foo.py for example), you just pass in the fixture and all of your extensions are available, like this:
from assertpy import assert_that
def test_foo(my_extensions):
assert_that(5).is_5()
assert_that(6).is_5() # fails!
where the my_extensions parameter must be the name of your fixture function in conftest.py. See the fixture docs for details.
Writing custom assertions
Here are some useful tips to help you write your own custom assertions:
- Use
selfas first param (as if your function was an instance method). - Use
self.valto get the actual value to be tested. - It's better to test the negative, and then fail if true.
- Fail by raising an
AssertionError. - Always use the
self._err()helper to fail (and print your failure message). - Always
return selfto allow for chaining.
Putting it all together, here is another custom assertion example, but annotated with comments:
def is_multiple_of(self, other):
# validate actual value - must be "integer" (aka int or long)
if isinstance(self.val, numbers.Integral) is False or self.val <= 0:
# bad input is error, not an assertion fail, so raise error
raise TypeError('val must be a positive integer')
# validate expected value
if isinstance(other, numbers.Integral) is False or other <= 0:
raise TypeError('given arg must be a positive integer')
# divide and compute remainder using divmod() built-in
_, rem = divmod(self.val, other)
# test the negative (is remainder non-zero?)
if rem > 0:
# non-zero remainder, so not multiple -> we fail!
self._err('Expected <%s> to be multiple of <%s>, but was not.' % (self.val, other))
# success, and return self to allow chaining
return self
Chaining
One of the nicest aspects of any fluent API is the ability to chain methods together. In the case of assertpy, chaining allows you to write assertions as single statement -- that reads like a sentence, and is easy to understand.
Here are just a few examples:
assert_that('foo').is_length(3).starts_with('f').ends_with('oo')
assert_that([1,2,3]).is_type_of(list).contains(1,2).does_not_contain(4,5)
assert_that(fred).has_first_name('Fred').has_last_name('Smith').has_shoe_size(12)
assert_that(people).is_length(2).extracting('first_name').contains('Fred','Joe')
Future
There are always a few new features in the works...if you'd like to help, check out the open issues and see our Contributing doc.
License
All files are licensed under the BSD 3-Clause License as follows:
Copyright (c) 2015-2019, Activision Publishing, Inc. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
492 Jan 03, 2023
1 Jul 11, 2022
3 Dec 04, 2021
9 Dec 09, 2022
1 Dec 26, 2021
632 Jan 08, 2023
2 Jan 16, 2022
863 Dec 29, 2022
3.8k Dec 29, 2022
226 Dec 30, 2022
3 Feb 07, 2022
1 Jan 22, 2022
3.5k Dec 29, 2022
1 Nov 11, 2021
1 Feb 01, 2022
17 Nov 04, 2022
35 Dec 15, 2022
31 May 28, 2021
191 Dec 21, 2022
3.1k Jan 04, 2023