Core API

The compare module contains the components you need to compare values and ensure that your expectations are met.

To make use of this module, you simply import the expect() starter into your spec/test file, and specify the expectation you have about two values.

expect()

compare.expect

This is an alias for the Expr class that starts an expectation contruct. It makes it easier to construct a readable assertion/expectation for some value, callable or expression that you are interested in.

When you apply expect to a value or expression, that value is stored as an attribute on the Expr instance that is returned. For instance the example below shows how the “value” attribute is the evaluated expression:

>>> expect(5 + 10).value == 15
True

If expect is applied to a callable, it does not evaluate immediately. Whether or not the callable is evaluated depends on the matcher that is applied. So as you can see from the example below, the callable is stored as-is:

>>> def call_me():
...     return "I was called..."
>>> expect(call_me).value      
<function call_me at 0x...>

However, if the function is called and passed into expect, the wrapped value stored is of course the return value of the callable:

>>> expect(call_me()).value == "I was called..."
True

@matcher

compare.matcher(func)

Decorator to register a function as a matcher. It attaches the decorated function to the Expr class so that it is available through the “expect” starter.

The matcher being registered is expected to accept at least a single parameter self, which is the Expr object it is attached to.

Here is a trivial example showing how to create and register a matcher:

>>> def to_equal_foo(self):
...     assert self.value == "foo"
>>> matcher(to_equal_foo)

Now you may use the matcher with the expect syntax:

>>> expect("foo").to_equal_foo()

Typically, a matcher would also accept a second parameter other, which is the python expression, primitive or callable that the wrapped value would be compared to.

Another trivial matcher example. This time it takes a value to compare with and it spits out a helpful message if the comparison fails:

>>> def to_equal(self, other):
...     assert self.value == other, "Expected '%s' to equal '%s'" % (self.value, other)
>>> matcher(to_equal)

You may now use the matcher in an expectation:

>>> expect("foo").to_equal("foo")

When the matcher fails, it tells you what went wrong:

>>> expect("foo").to_equal("BAR")
Traceback (most recent call last):
    ...
AssertionError: Expected 'foo' to equal 'BAR'

ensure()

compare.ensure(expr, outcome, message='')

Compares the result of the given boolean expression to the anticipated boolean outcome.

All the the default matchers delegate to the trusty ensure helper to handle the actual determination of pass/fail for a given comparison. If there is a match, all is well. If the comparison fails, it raises an UnmetExpectation error with the given message.

Stays quite if the comparison lines up:

>>> ensure(5 == 5, True)

Raises an error if the comparison fails:

>>> ensure('Foo' == 'foo', True)
Traceback (most recent call last):
    ...
UnmetExpectation

Raises an error with the given message if the comparison fails:

>>> A = 'Foo'
>>> B = 'foo'
>>> message = "'%s' does not equal '%s'" % (A, B)
>>> ensure(A == B, True, message)
Traceback (most recent call last):
    ...
UnmetExpectation: 'Foo' does not equal 'foo'

The Expr class

class compare.Expr(expr)

Wraps a python expression, primitive value or callable that is to be evaluated and compared to another value.

Serves as the basic construct for describing an expectation. Generally you would not use this class directly, instead it is available through the “expect” alias which allows for a more pythonic syntax.

It initializes with primitives, native types and expressions:

>>> e = Expr("Foo")
>>> e.value == "Foo"
True

>>> e = Expr(['a', 'b'])
>>> e.value == ['a', 'b']
True

>>> Expr(4 + 7).value == 11
True

>>> Expr(4 == 7).value == False
True

Exceptions

exception compare.UnmetExpectation

Error that is raised if an expectation is not met.

This error class inherits AssertionError so it is compatible with unittest assertion errors and plain old python “assert” errors.