When a compare matcher is registered, it is simply attached to the Expr class. The matcher may then be accessed through the expect() function/starter.
Compare ships with some generic/base matchers that focus on handling simple comparisons. If you need use-case specific matchers, it is very easy to create and attach your own matcher to the Expr class. In fact you are encouraged to create custom matchers since they make your assertions more readable and concise.
Here are the base matchers that are available by default:
Checks if value == other – simple equality.
Passes if the values are equal:
>>> expect(555).to_equal(555)
Fails if the values are not equal:
>>> expect('waiting...').to_equal('done!')
Traceback (most recent call last):
...
UnmetExpectation: Expected 'waiting...' to equal 'done!'
Checks if value is other – identity, id().
Passes if the values are identical:
>>> a1 = a2 = ['foo', 'bar']
>>> expect(a1).to_be(a2)
Fails if the values are not identical:
>>> b1 = ['foo', 'bar']
>>> expect(a1).to_be(b1)
Traceback (most recent call last):
...
UnmetExpectation: Expected ['foo', 'bar'] to be ['foo', 'bar']
Checks if value < other.
Passes if the wrapped value is less than other:
>>> expect(9).to_be_less_than(10)
Fails if wrapped value is greater than or equal to other:
>>> expect(9).to_be_less_than(5)
Traceback (most recent call last):
...
UnmetExpectation: Expected 9 to be less than 5
>>> expect(9).to_be_less_than(9)
Traceback (most recent call last):
...
UnmetExpectation: Expected 9 to be less than 9
Checks if value <= other.
Passes if the wrapped value is less than or equal to other:
>>> expect(9).to_be_less_than_or_equal_to(10)
>>> expect(9).to_be_less_than_or_equal_to(9)
Fails if wrapped value is greater than other:
>>> expect(9).to_be_less_than_or_equal_to(5)
Traceback (most recent call last):
...
UnmetExpectation: Expected 9 to be less than or equal to 5
Checks if value > other.
Passes if the wrapped value is greater than other:
>>> expect(20).to_be_greater_than(10)
Fails if wrapped value is less than or equal to other:
>>> expect(20).to_be_greater_than(30)
Traceback (most recent call last):
...
UnmetExpectation: Expected 20 to be greater than 30
>>> expect(20).to_be_greater_than(20)
Traceback (most recent call last):
...
UnmetExpectation: Expected 20 to be greater than 20
Checks if value >= other.
Passes if the wrapped value is greater than or equal to other:
>>> expect(20).to_be_greater_than_or_equal_to(10)
>>> expect(20).to_be_greater_than_or_equal_to(20)
Fails if wrapped value is less than other:
>>> expect(20).to_be_greater_than_or_equal_to(30)
Traceback (most recent call last):
...
UnmetExpectation: Expected 20 to be greater than or equal to 30
Checks that the wrapped value is None.
Passes if the given value is None:
>>> foo = None
>>> expect(foo).to_be_none()
Fails if the given value is not None:
>>> bar = 'This is not None'
>>> expect(bar).to_be_none()
Traceback (most recent call last):
...
UnmetExpectation: Expected 'This is not None' to be None
Evaluates the Python “truthiness” – bool() of a given expression. See to_be_falsy() for inverse matcher.
Here are some examples of a truth value test:
>>> bool(1)
True
>>> bool(0)
False
>>> bool('')
False
>>> bool('Foo')
True
For more information about truth value testing in Python please see http://docs.python.org/library/stdtypes.html#truth-value-testing
Passes if the given value is truthy:
>>> foo = 'This is truthy'
>>> expect(foo).to_be_truthy()
Fails of the given value does not evaluate as truthy:
>>> bar = ''
>>> expect(bar).to_be_truthy()
Traceback (most recent call last):
...
UnmetExpectation: Expected '' to be truthy
As you would expect, the number 1 is truthy but 0 is not:
>>> expect(1).to_be_truthy()
>>> expect(0).to_be_truthy()
Traceback (most recent call last):
...
UnmetExpectation: Expected 0 to be truthy
A value of True is truthy but False and None are not:
>>> expect(True).to_be_truthy()
>>> expect(False).to_be_truthy()
Traceback (most recent call last):
...
UnmetExpectation: Expected False to be truthy
>>> expect(None).to_be_truthy()
Traceback (most recent call last):
...
UnmetExpectation: Expected None to be truthy
Evaluates the Python “falsyness” – not bool() of a given expression. See to_be_truthy() for inverse matcher and details on Python truth tests.
Passes if the given value is falsy:
>>> foo = ''
>>> expect(foo).to_be_falsy()
Fails of the given value does not evaluate as falsy:
>>> bar = 'This is not falsy'
>>> expect(bar).to_be_falsy()
Traceback (most recent call last):
...
UnmetExpectation: Expected 'This is not falsy' to be falsy
The number 0 is falsy but 1 is not:
>>> expect(0).to_be_falsy()
>>> expect(1).to_be_falsy()
Traceback (most recent call last):
...
UnmetExpectation: Expected 1 to be falsy
The values False and None are falsy but True is not:
>>> expect(False).to_be_falsy()
>>> expect(None).to_be_falsy()
>>> expect(True).to_be_falsy()
Traceback (most recent call last):
...
UnmetExpectation: Expected True to be falsy
Checks if the wrapped value contains the other value.
It applies to lists, strings, dict keys
Passes if the other value is in the wrapped value:
>>> fruits = ['apple', 'orange', 'pear']
>>> expect(fruits).to_contain('apple')
Fails if the other value cannot be found in the wrapped value:
>>> mammals = ['dog', 'whale', 'cat']
>>> expect(mammals).to_contain('fly')
Traceback (most recent call last):
...
UnmetExpectation: Expected ['dog', 'whale', 'cat'] to contain 'fly'
Works for stings:
>>> foo = "There is a BAR in here"
>>> expect(foo).to_contain('BAR')
And dict keys:
>>> pos = {'x': 40, 'y': 500}
>>> expect(pos).to_contain('x')
Compares the return value of the wrapped callable to the expected value
Passes if the callable returns the expected value:
>>> def foo():
... return "Foo"
>>> expect(foo).to_return('Foo')
Fails if the callable does not return the expected value:
>>> def bar():
... return "Barf"
>>> expect(bar).to_return('Bar')
Traceback (most recent call last):
...
UnmetExpectation: Expected callable to return 'Bar' but got 'Barf'
Invokes the provided callable and ensures that it raises an Exception.
Passes if the callable raises an exeption (any exception):
>>> def bad():
... raise Exception()
>>> expect(bad).to_raise()
Fails if the callable does not raise any exception:
>>> def good():
... return "No exceptions here"
>>> expect(good).to_raise()
Traceback (most recent call last):
...
UnmetExpectation: Expected callable to raise an exception
You may specify the type of exception you expect to be raised. The expectation will fail if the callable raises an exception which is not an instance of the expected exception class:
>>> class MildError(Exception):
... pass
>>> class CatastrophicError(Exception):
... pass
>>> def raise_custom_exception():
... raise MildError
>>> expect(raise_custom_exception).to_raise(CatastrophicError)
Traceback (most recent call last):
...
UnmetExpectation: Expected callable to raise CatastrophicError() but got MildError()
Further, you may specify the message you expect the exception to be raised with. The expectation will fail if the callable raises the right exception but with a non matching message:
>>> def raise_exception_with_message():
... raise CatastrophicError('BOOM!')
>>> expect(raise_exception_with_message).to_raise(CatastrophicError, 'Ohly Crap...')
Traceback (most recent call last):
...
UnmetExpectation: Expected callable to raise CatastrophicError('Ohly Crap...',)
but got CatastrophicError('BOOM!',)
These are convenient matchers that harness the concept of Python “rich comparison” methods to provide succinct alternatives to some of the more verbose base matchers. For more information on these special methods, please see: http://docs.python.org/reference/datamodel.html#special-method-names
Checks if value == other. It is an alternative to the to_equal base matcher. For instance, this example:
>>> expect(555).to_equal(555)
May be expressed as:
>>> expect(555) == 555
Fails if the values are not equal:
>>> expect('waiting...') == 'done!'
Traceback (most recent call last):
...
UnmetExpectation: Expected 'waiting...' to equal 'done!'
Checks if value < other. It is an alternative to the to_be_less_than base matcher. For instance, this example:
>>> expect(45).to_be_less_than(50)
May be expressed as:
>>> expect(45) < 50
Fails if the wrapped value is not less than other:
>>> expect(350) < 200
Traceback (most recent call last):
...
UnmetExpectation: Expected 350 to be less than 200
Checks if value <= other. It is an alternative to the to_be_less_than_or_equal_to base matcher. For instance, this example:
>>> expect(50).to_be_less_than_or_equal_to(50)
May be expressed as:
>>> expect(50) <= 50
Fails if the wrapped value is greater than other:
>>> expect(201) <= 200
Traceback (most recent call last):
...
UnmetExpectation: Expected 201 to be less than or equal to 200
Checks if value > other. It is an alternative to the to_be_greater_than base matcher. For instance, this example:
>>> expect(45).to_be_greater_than(40)
May be expressed as:
>>> expect(45) > 40
Fails if the wrapped value is not greater than other:
>>> expect(150) > 200
Traceback (most recent call last):
...
UnmetExpectation: Expected 150 to be greater than 200
Checks if value >= other. It is an alternative to the to_be_greater_than_or_equal_to base matcher. For instance, this example:
>>> expect(50).to_be_greater_than_or_equal_to(50)
May be expressed as:
>>> expect(50) >= 50
Fails if the wrapped value is less than other:
>>> expect(199) >= 200
Traceback (most recent call last):
...
UnmetExpectation: Expected 199 to be greater than or equal to 200