Chai - Python Mocking Made Easy
|Keywords:||python, mocking, testing, unittest, unittest2|
Chai provides a very easy to use api for mocking/stubbing your python objects, patterned after the Mocha library for Ruby.
The following is an example of a simple test case which is mocking out a get method
CustomObject. The Chai api allows use of call chains to make the code
short, clean, and very readable. It also does away with the standard setup-and-replay
work flow, giving you more flexibility in how you write your cases.
from chai import Chai class CustomObject (object): def get(self, arg): pass class TestCase(Chai): def test_mock_get(self): obj = CustomObject() self.expect(obj.get).args('name').returns('My Name') self.assert_equals(obj.get('name'), 'My Name') self.expect(obj.get).args('name').returns('Your Name') self.assert_equals(obj.get('name'), 'Your Name') def test_mock_get_with_at_most(self): obj = CustomObject() self.expect(obj.get).args('name').returns('My Name').at_most(2) self.assert_equals(obj.get('name'), 'My Name') self.assert_equals(obj.get('name'), 'My Name') self.assert_equals(obj.get('name'), 'My Name') # this one will fail if __name__ == '__main__': import unittest2 unittest2.main()
All of the features are available by extending the
Chai class, itself a subclass of
unittest2 is available Chai will use that, else it will fall back to
unittest. Chai also aliases all of the
assert* methods to lower-case with undersores. For example,
assertNotEquals can also be referenced as
Chai loads in all assertions, comparators and mocking methods into the module in which a
Chai subclass is declared. This is done to cut down on the verbosity of typing
self. everywhere that you want to run a test. The references are loaded into the subclass' module during
setUp, so you're sure any method you call will be a reference to the class and module in which a particular test method is currently being executed. Methods and comparators you define locally in a test case will be globally available when you're running that particular case as well.
class ProtocolInterface(object): def _private_call(self, arg): pass def get_result(self, arg): self._private_call(arg) return 'ok' class TestCase(Chai): def assert_complicated_state(self, obj): return True # ..or.. raise AssertionError() def test_mock_get(self): obj = ProtocolInterface() data = object() expect(obj._private_call).args(data) assert_equals('ok', obj.get_result(data)) assert_complicated_state(data)
The simplest mock is to stub a method. This replaces the original method with a subclass of
chai.Stub, the main instrumentation class. All additional
expect calls will re-use this stub, and the stub is responsible for re-installing the original reference when
Chai.tearDown is run.
Stubbing is used for situations when you want to assert that a method is never called.
class CustomObject (object): def get(self, arg): pass @property def prop(self): pass class TestCase(Chai): def test_mock_get(self): obj = CustomObject() stub(obj.get) assert_raises( UnexpectedCall, obj.get )
In this example, we can reference
obj.get directly because
get is a bound method and provides all of the context we need to refer back to
obj and stub the method accordingly. There are cases where this is insufficient, such as module imports, special Python types, and when module attributes are imported from another (like
posix). If the object can't be stubbed with a reference,
UnsupportedStub will be raised and you can use the verbose reference instead.
class TestCase(Chai): def test_mock_get(self): obj = CustomObject() stub(obj, 'get') assert_raises( UnexpectedCall, obj.get )
Stubbing an unbound method will apply that stub to all future instances of that class.
class TestCase(Chai): def test_mock_get(self): stub(CustomObject.get) obj = CustomObject() assert_raises( UnexpectedCall, obj.get )
Some methods cannot be stubbed because it is impossible to call
setattr on the object. A good example of this is the
Finally, Chai supports stubbing of properties on classes. In all cases, the stub will be applied to a class and individually to each of the 3 property methods. Because the stub is on the class, all instances need to be addressed when you write expectations. The first interface is via the named attribute method which can be used on both classes and instances.
class TestCase(Chai): def test_prop_attr(self): obj = CustomObject() stub( obj, 'prop' ) assert_raises( UnexpectedCall, lambda: obj.prop ) stub( stub( obj, 'prop' ).setter )
Using the class, you can directly refer to all 3 methods of the property. To refer to the getter you use the property directly, and for the methods you use its associated attribute name. You can stub in any order and it will still resolve correctly.
class TestCase(Chai): def test_prop_attr(self): stub( CustomObject.prop.setter ) stub( CustomObject.prop ) stub( CustomObject.prop.deleter ) assert_raises( UnexpectedCall, lambda: CustomObject().prop )
Expectations are individual test cases that can be applied to a stub. They are expected to be run in order (unless otherwise noted). They are greedy, in that so long as an expectation has not been met and the arguments match, the arguments will be processed by that expectation. This mostly applies to the "at_least" and "any_order" expectations, which (may) stay open throughout the test and will handle any matching call.
Expectations will automatically create a stub if it's not already applied, so no separate call to
stub is necessary. The arguments and edge cases regarding what can and cannot have expectations applied are identical to stubs. The
expect call will return a new
chai.Expectation object which can then be used to modify the expectation. Without any modifiers, an expectation will expect a single call without arguments and return None.
class TestCase(Chai): def test_mock_get(self): obj = CustomObject() expect(obj.get) assert_equals( None, obj.get() ) assert_raises( UnexpectedCall, obj.get )
Modifiers can be applied to the expectation. Each modifier will return a reference to the expectation for easy chaining. In this example, we're going to match a parameter and change the behavior depending on the argument. This also shows the ability to incrementally add expectations throughout the test.
class TestCase(Chai): def test_mock_get(self): obj = CustomObject() expect(obj.get).args('foo').returns('hello').times(2) assert_equals( 'hello', obj.get('foo') ) assert_equals( 'hello', obj.get('foo') ) expect(obj.get).args('bar').raises( ValueError ) assert_raises( ValueError, obj.get, 'bar' )
It is very common to need to run expectations on the constructor for an object, possibly including returning a mock object. Chai makes this very simple.
def method(): obj = CustomObject('state') obj.save() return obj class TestCase(Chai): def test_method(self): obj = mock() expect( CustomObject ).args('state').returns( obj ) expect( obj.save ) assert_equals( obj, method() )
Lastly, the arguments modifier supports several matching functions. For simplicity in covering the common cases, the arg expectation assumes an equals test for instances and an instanceof test for types. All rules that apply to positional arguments also apply to keyword arguments.
class TestCase(Chai): def test_mock_get(self): obj = CustomObject() expect(obj.get).args(is_a(float)).returns(42) assert_raises( UnexpectedCall, obj.get, 3 ) assert_equals( 42, obj.get(3.14) ) expect(obj.get).args(str).returns('yes') assert_equals( 'yes', obj.get('no') ) expect(obj.get).args(is_arg(list)).return('yes') assert_raises( UnexpectedCall, obj.get,  ) assert_equals( 'yes', obj.get(list) )
Expectations expose the following public methods for changing their behavior.
- Add a test to the expectation for matching arguments.
- Any arguments are accepted.
- Add a return value to the expectation when it is matched and executed.
- When the expectation is run it will raise this exception. Accepts type or instance.
- An integer that defines a hard limit on the minimum and maximum number of times the expectation should be executed.
- Sets a minimum number of times the expectation should run and removes any maximum.
- Equivalent to
- Sets a maximum number of times the expectation should run. Does not affect the minimum.
- Equivalent to
- Equivalent to
times(1), also the default for any expectation.
- The expectation can be called at any time, independent of when it was defined. Can be combined with
at_least_onceto force it to respond to all matching calls throughout the test.
- Called with a function argument. When the expectation passes a test, the function will be executed. The side effect will be executed even if the expectation is configured to raise an exception.
- Will remove the stub after the expectation has been met. This is useful in cases where you need to mock core methods such as
open, but immediately return its original behavior after the mocked call has run.
Argument comparators are defined as classes in
chai.comparators, but loaded into the
Chai class for convenience (and by extension, a subclass' module).
- The default comparator, uses standard Python equals operator
- almost_equals(float, places)
- Identical to assertAlmostEquals, will match an argument to the comparator value to a most
placesdigits beyond the decimal point.
- Match an argument of a given type. Supports same arguments as builtin function
- Matches an argument using the Python
- Matches an argument if any of the comparators in the argument list are met. Uses automatic comparator generation for instances and types in the list.
- Matches an argument if all of the comparators in the argument list are met. Uses automatic comparator generation for instances and types in the list.
- Matches an argument if the supplied comparator does not match.
- Matches an argument using a regular expression. Standard
- Matches an argument if the callable returns True. The callable must take one argument, the parameter being checked.
- Matches any argument.
- Matches if the argument is in the
- Matches if the argument contains the object using the Python
- Matches if the argument contains all of the same items as in
container. Insists that the argument is the same type as
container. Useful when you need to assert a few values in a list or dictionary, but the exact contents are not known or can vary.
- A variable match against the first time that the argument is called. In the case of multiple calls, the second one must match the previous value of
name. After your tests have run, you can check the value against expected arguments through
var(name).value. This is really useful when you're testing a deep stack and it's simpler to assert that "value A was used in method call X".
A note of caution
If you are using the
func comparator to produce side effects, be aware that it may be called more than once even if the expectation you're defining only occurs once. This is due to the way
Stub.__call__ processes the expectations and determines when to process arguments through an expectation.
Sometimes you need a mock object which can be used to stub and expect anything. Chai exposes this through the
mock method which can be called in one of two ways.
Without any arguments,
Chai.mock() will return a
chai.Mock object that can be used for any purpose. If called with arguments, it behaves like
expect, creating a Mock object and setting it as the attribute on another object.
Any request for an attribute from a Mock will return a new Mock object, but
setattr behaves as expected so it can store state as well. The dynamic function will act like a stub, raising
UnexpectedCall if no expectation is defined.
class CustomObject(object): def __init__(self, handle): _handle = handle def do(self, arg): return _handle.do(arg) class TestCase(Chai): def test_mock_get(self): obj = CustomObject( mock() ) expect( obj._handle.do ).args('it').returns('ok') assert_equals('ok', obj.do('it')) assert_raises( UnexpectedCall, obj._handle.do_it_again )
expect methods handle
Mock objects as arguments by mocking the
__call__ method, which can also act in place of
# module custom.py from collections import deque class CustomObject(object): def __init__(self): self._stack = deque() # module custom_test.py import custom from custom import CustomObject class TestCase(Chai): def test_mock_get(self): mock( custom, 'deque' ) expect( custom.deque ).returns( 'stack' ) obj = CustomObject() assert_equals('stack', obj._stack)
Mock objects, because of the
getattr implementation, can also support nested attributes.
class TestCase(Chai): def test_mock(self): m = mock() m.id = 42 expect( m.foo.bar ).returns( 'hello' ) assert_equals( 'hello', m.foo.bar() ) assert_equals( 42, m.id )
In addition to implementing
Mock objects implement
the container and context manager interfaces are defined. Nonzero will always return
True; other methods will raise
cannot be itself stubbed.
You can install Chai either via the Python Package Index (PyPI) or from source.
To install using
$ pip install chai
Download the latest version of Chai from http://pypi.python.org/pypi/chai
You can install it by doing the following,:
$ tar xvfz chai-*.*.*.tar.gz $ cd chai-*.*.*.tar.gz $ python setup.py install # as root
You can clone the repository by doing the following:
$ git clone git://github.com/agoragames/chai.git
If you have any suggestions, bug reports or annoyances please report them to our issue tracker at https://github.com/agoragames/chai/issues
This software is licensed under the New BSD License. See the
file in the top distribution directory for the full license text.