Mulle kybernetiK -- OCMock

OCMock is an Objective-C implementation of mock objects. If you are unfamiliar with the concept of mock objects please visit mockobjects.com which has more details and discussions about this approach to testing software.

This implementation fully utilises the dynamic nature of Objective-C. It creates mock objects on the fly and uses the trampoline pattern so that you can define expectations and stubs using the same syntax that you use to call methods. No strings, no @selector, just method invocations like this:

Pre-built binaries as well as instructions on how to access the source code are available on the "Download" tab. The "Features" tab lists all features supported by OCMock. Support details, including a link to the support forum, are on the "Support" tab.

2-Mar-2012

New binary release (2.0) bringing compatibility with iOS 5 and Xcode 4.2/4.3. The version is 2.0 not because of a major change in OCMock itself but because the 1.x numbering scheme depended on Subversion, and the code is now on Github.

20-Aug-2011

Some infrastructure changes. Following public demand the source code for OCMock is now on GitHub (erikdoe/ocmock). Going forward this will be the master repository for the source code. Because the current version numbers are based on the Subversion revisions we will introduce a new numbering scheme with the next release.

At the same time the website is moving to its own top-level domain, ocmock.org.

17-Mar-2011

New release (1.77) bringing Xcode 4 compatibility, an explicit check to see whether the static library has been linked correctly, and a feature to stop a partial mock from intercepting calls to the underlying object.

21-Aug-2010

New release (1.70) which adds the following features: support for blocks, static library for iOS development, forwarding of methods from a partial mock to the real object, and rejecting methods when using nice mocks. All new features are highlighted on the "Features" tab on this page, and the static library is described in detail on the "iPhone/iOS" tab.

16-Oct-2009

New release (1.55) offering several new features, including partial mocks, method swizzling, posting of notifications, and verification of call sequence, as well as a handful of bug fixes. Details in the "Features" tab on this page and in the change notes.

10-Oct-2009

The mailing list is great for submitting patches and discussing future development of OCMock. To just get a quick answer for a problem using OCMock it might be a bit too involved, which is why we're going to trial the use of a web-based forum. Have a look at the brand new OCMock Forum.

19-May-2009

New release (1.42) which combines several contributions, adding support for mock observers of notifications, setters for pass-by-reference arguments, and several improvements to existing features. The default binary release now uses @rpath, which allows for more flexible deployment, and it supports garbage collection.

07-Jul-2008

With this new release (1.29) OCMock supports hamcrest matchers like this:

[[mock expect] doSomething:startsWith(@"foo")]

Note that this dependency is optional. OCMock does not require or link against hamcrest, but if the test suite uses hamcrest matchers and links against hamcrest then OCMock works with the matchers. This release also contains a small bugfix that removes a memory leak in OCMockRecorder.

08-May-2008

New release (1.24) which combines several contributions, adds support for more flexible constraints as well as experimental 64-bit support. The default binary release is now in “embedded” mode.

22-Nov-2007

We now have a mailing list for OCMock. Please send an empty message to ocmock-subscribe@mulle-kybernetik.com to subscribe. The actual mailing list address is ocmock@mulle-kybernetik.com but you must be subscribed to be able to post. (Too much hassle with spam otherwise.)

21-Jun-2007

New release (1.17) which combines several contributions. Added nice mocks, which ignore unexpected invocations, and exceptions meant to cause the test to fail fast are now rethrown in verify.

11-Jun-2006

New release (1.12) which combines several contributions. Added support for stubbing primitive return types, matching nil and struct arguments, and throwing exceptions.

03-Oct-2005

New release (1.10) which has support for mocking protocols. Also added XCode 2.1 compliant project files and moved to built-in OCUnit.

26-Sep-2004

Changed a small but important detail: The MockObject and MockRecorder classes now inherit from NSProxy which carries much less baggage in terms of methods that cannot be mocked because they are defined by the base class.

30-Aug-2004

First public release. I am using the Subversion revision numbers to version the releases, which is why we start with 1.4 and not 1.0 as one could expect.

23-Jul-2004

While working on a new Objective-C project, a Mac OS X monitor for Damage Control, I decide that I've gotten so used to developing test-first and using mock objects that I will bite the bullet and do a simple mock objects implementation in Objective-C. It'll be basic but since Objective-C is so dynamic I probably only need a fraction of the code needed for the Java and .NET versions.

Stable Releases

The binaries require the lowest version of OS X and the iOS SDK that supports all features. It is usually possible to build a given version of OCMock from source for older versions of OS X at the expense of losing some features.

Release	Date	File
2.0 - Source and binary for Xcode 4.2/4.3 (iOS 5)	2-Mar-2012	ocmock-2.0.1.dmg
1.77 - Source and binary for Xcode 3.2.5 and Xcode 4	17-Mar-2011	ocmock-1.77.dmg

Source code

The source code for OCMock is available on GitHub

 
									https://github.com/erikdoe/ocmock

License

Permission to use, copy, modify and distribute this software and its documentation is hereby granted, provided that both the copyright notice and this permission notice appear in all copies of the software, derivative works or modified versions, and any portions thereof, and that both notices appear in supporting documentation, and that credit is given to Mulle Kybernetik in all documents and publicity pertaining to direct or indirect use of this code or its derivatives.

THIS IS EXPERIMENTAL SOFTWARE AND IT IS KNOWN TO HAVE BUGS, SOME OF WHICH MAY HAVE SERIOUS CONSEQUENCES. THE COPYRIGHT HOLDER ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" CONDITION. THE COPYRIGHT HOLDER DISCLAIMS ANY LIABILITY OF ANY KIND FOR ANY DAMAGES WHATSOEVER RESULTING DIRECTLY OR INDIRECTLY FROM THE USE OF THIS SOFTWARE OR OF ANY DERIVATIVE WORK.

Highlighted features were added in the latest few releases.

Class mocks

id mock = [OCMockObject mockForClass:[SomeClass class]]

Creates a mock object that can be used as if it were an instance of SomeClass.

Expectations and verification

[[mock expect] someMethod:someArgument]

Tells the mock object that someMethod: should be called with an argument that is equal to someArgument. After this setup the functionality under test should be invoked followed by

[mock verify]

The verify method will raise an exception if the expected method has not been invoked.

Stubs

[[[mock stub] andReturn:aValue] someMethod:someArgument]

Tells the mock object that when someMethod: is called with someArgument it should return aValue.

If the method returns a primitive type the return value must be wrapped as follows:

BOOL value = YES;
   [[[mock stub] andReturnValue:OCMOCK_VALUE(value)] someMethod:someArgument]

Values can also be returned in pass-by-reference arguments:

[[mock stub] someMethodWithReferenceArgument:[OCMArg setTo:aValue]]

In this case the mock object will set the reference that is passed to the method to aValue, which currently has to be an object.

The mock object can also throw an exception or post a notification when a method is called:

[[[mock stub] andThrow:anException] someMethod:someArgument]

[[[mock stub] andPost:aNotification] someMethod:someArgument]

In fact, the notification can be posted in addition to returning a value:

[[[[mock stub] andPost:aNotification] andReturn:aValue] someMethod:someArgument]

The mock can delegate the handling of an invocation to a completely different method:

[[[mock stub] andCall:@selector(aMethod:) onObject:anObject] someMethod:someArgument]

In this case the mock object will call aMethod: on anObject when someMethod: is called. The signature of the replacement method must be the same as that of the method that is replaced. Arguments will be passed and the return value of the replacement method is returned from the stubbed method.

If Objective-C blocks are available a block can be used to handle the invocation and set up a return value:

 void (^theBlock)(NSInvocation *) = ^(NSInvocation *invocation) {
       /* code that reads and modifies the invocation object */
       };
   [[[mock stub] andDo:theBlock] someMethod:[OCMArg any]];

If using a partial mock (see below) it is possible to forward the method to the implementation in the real object, which can be useful to simply check that a method was called:

[[[mock expect] andForwardToRealObject] someMethod]

Note that it is possible to use andReturn:, andThrow:, etc with expect, too. This will then return the given return value and, on verify, ensure that the method has been called.

Argument constraints

[[mock expect] someMethod:[OCMArg any]]

Tells the mock object that someMethod: should be called and it does not matter what the argument is. Pointers require special treatment:

[[mock expect] someMethodWithPointerArgument:[OCMArg anyPointer]]

Other constraints available are:

[[mock expect] someMethod:[OCMArg isNil]]

[[mock expect] someMethod:[OCMArg isNotNil]]

[[mock expect] someMethod:[OCMArg isNotEqual:aValue]]

[[mock expect] someMethod:[OCMArg checkWithSelector:aSelector onObject:anObject]]

The last constraint will, when the mock object receives someMethod:, send aSelector to anObject and if aSelector takes an argument will pass the argument that was passed to someMethod:. The method should return a boolean indicating whether the argument matched the expectation or not.

If Objective-C blocks are available it is possible to check the argument with a block as follows:

[[mock expect] someMethod:[OCMArg checkWithBlock:^(id value) { /* return YES if value is ok */ }]];

Last but not least it is also possible to use Hamcrest matchers like this:

[[mock expect] someMethod:startsWith(@"foo")]

Note that this will only work when the Hamcrest framework is explicitly linked by the unit test bundle.

Nice mocks / failing fast

When a method is called on a mock object that has not been set up with either expect or stub the mock object will raise an exception. This fail-fast mode can be turned off by creating a "nice" mock:

id mock = [OCMockObject niceMockForClass:[SomeClass class]]

While nice mocks will simply ignore all unexpected methods it is possible to disallow specific methods:

[[mock reject] someMethod]

Note that in fail-fast mode, if the exception is ignored, it will be rethrown when verify is called. This makes it possible to ensure that unwanted invocations from notifications etc. can be detected.

Protocol mocks

id aMock = [OCMockObject mockForProtocol:@protocol(SomeProtocol)]

Creates a mock object that can be used as if it were an instance of an object that implements SomeProtocol.

Partial mocks

id aMock = [OCMockObject partialMockForObject:anObject]

Creates a mock object that can be used in the same way as anObject. When a method that is not stubbed is invoked it will be forwarded to anObject. When a stubbed method is invoked using a reference to anObject, rather than the mock, it will still be handled by the mock.

Note that currently partial mocks cannot be created for instances of toll-free bridged classes, e.g. NSString.

Observer mocks

id aMock = [OCMockObject observerMock]

Creates a mock object that can be used to observe notifications. The mock must be registered in order to receive notifications:

[notificatonCenter addMockObserver:aMock name:SomeNotification object:nil]

Expectations can then be set up as follows:

[[mock expect] notificationWithName:SomeNotification object:[OCMArg any]]

Note that currently there is no "nice" mode for observer mocks, they will always raise an exception when an unexpected notification is received.

Instance-based method swizzling

In a nutshell, Method Swizzling describes the replacement of a method implementation with a different implementation at runtime. Using partial mocks and the andCall: stub OCMock allows such replacements on a per-instance basis.

id mock = [OCMockObject partialMockForObject:anObject]

[[[mock stub] andCall:@selector(differentMethod:) onObject:differentObject] someMethod:[OCMArg any]]

After these two lines, when someMethod: is sent to anObject the implementation of that method is not invoked. Instead, differentMethod: is called on differentObject. Other instances of the same class are not affected; for these the original implementation of someMethod: is still invoked. The methods can have different names but their signatures should be the same.

More detail

The test cases in OCMockObjectTests and OCMockObjectHamcrestTests show all uses of OCMock.

Changes.txt contains a chronological list of all changes.

This section was written for Xcode 4.2 and iOS 5. It applies to Xcode 4.3 and iOS 5.1, too.

OCMock static library

OCMock comes in two flavours, a framework for use in OS X projects and a static library for use in iOS projects. You might find references to so-called "logic tests" for the iPhone that worked with the framework. This is outdated. Today we always use the static library for iOS development.

When a test project links against the static library the OCMock classes are included in the binary itself, which means they can be run in the simulator or an iOS device. The library included in the binary releases of OCMock is built "fat", containing binary code for i386, which is required for the simulator, and armv7, which is required for running on the device.

Adding the library to a project

To use the library in an iOS project, you have to make the actual library, ie. libOCMock.a, as well as the header files available to the target containing the tests. In the iOS5 example project we're using this directory structure:

The library must be added to the the test target in the "Link Binaries With Libraries" build phase. Click on the plus (+) icon, choose "Add other..." and find the library in the filesystem.

Adding the library this way automatically adds a library search path to the project so that the linker can find the library. Unfortunately, it does not add a header search path, which is needed for the compiler to resolve includes/imports. This must be done manually in the build settings. Search for "header" which should bring up the "Header Search Paths" setting. Following the directory layout above the best way to point to the header directory is by adding a reference relative to the project's source directory. Don't be confused, the table view will show what that resolves to, but the setting saved does retain the variable.

One further step is required to work around an issue in the linker. For static libraries the linker tries to be clever and only includes those symbols that it thinks are used. It gets this wrong with Objective-C categories, and we need to tell it that (a) we're dealing with Objective-C and (b) that it should load all symbols for the OCMock library.

If you forget this step or you get the force load path wrong you will get an appropriate warning (in the form of an exception) the first time you try to use a mock object in your tests. Different linker flags have been suggested but I do recommend -force_load; it works, as long as the path following it is correct. More details in Apple's Technical Q&A QA1490.

If you have copied the library or headers to a different place all of these settings must be adjusted accordingly.

The iPhoneExample project

OCMock now contains an iOS5 example project that shows how to use OCMock in iOS application tests. The project is set up following Apple's guidelines and the linker flags are set as described above. Note that in the Xcode table view the path variables are expanded and the full paths are shown. This can be confusing.

The project contains one unit test that shows how to use mocks to replace a UITableView when testing a controller. This project should build and the test should pass. If it doesn't something is very wrong.

If you modify the test to fail, for example by changing the call to the method under test, the most useful output is available from the log section with the output expanded:

More support

If you have any questions or issues, please use the OCMock forum or Stackoverflow. I'm trying to monitor both but things can get busy for me...

For contributions and discussions of future development of OCMock please join the mailing list by sending an empty message to ocmock-subscribe@mulle-kybernetik.com.

You can also contact me directly by email.