Core Matchers

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.

Base Matchers

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:

to_equal

Expr.to_equal(other)

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!'

to_be

Expr.to_be(other)

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']

to_be_less_than

Expr.to_be_less_than(other)

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

to_be_less_than_or_equal_to

Expr.to_be_less_than_or_equal_to(other)

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

to_be_greater_than

Expr.to_be_greater_than(other)

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

to_be_greater_than_or_equal_to

Expr.to_be_greater_than_or_equal_to(other)

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

to_be_none

Expr.to_be_none()

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

to_be_truthy

Expr.to_be_truthy()

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

to_be_falsy

Expr.to_be_falsy()

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

to_contain

Expr.to_contain(other)

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')

to_return

Expr.to_return(expected)

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'

to_raise

Expr.to_raise(exception_class=None, exception_message=None)

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!',)

“Rich Comparison” Matchers

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

== , equal to

Expr.__eq__(other)

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!'

< , less than

Expr.__lt__(other)

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

<= , less than or equal to

Expr.__le__(other)

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

> , greater than

Expr.__gt__(other)

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

>= , greater than or equal to

Expr.__ge__(other)

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