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.

Source code

The source code for OCMock is available on GitHub

License

Copyright (c) 2004 - 2012 by Mulle Kybernetik. All rights reserved.

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.

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.

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

[[[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.

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

[[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.

Poking Objective-C with a Testing Stick

General tutorial that explains in detail how to set up a project for testing with OCUnit and OCMock. Also shows how partial mocks can be used to substitute individual methods in a test.

Testing Cocoa Controllers

A tutorial that shows how to test Cocoa controller objects without having to load the user interface from the NIB file. The objects defined in InterfaceBuilder are replaced with mocks.

Mocking Singletons with OCMock

The title says it all. Uses categories to allow substitution of system-provided singletons.

Writing custom constraints

OCMock integrates with Hamcrest but sometimes it can be easier to write a constraint using the API used by OCMock's built-in constraints. This tutorial shows how it's done. Applies to iPhone and Cocoa development.

OCMock and the iPhone

This tutorial shows how to use OCMock as a framework for an iPhone project. There are some limitations to this approach. Please visit the "iPhone/iOS" tab for more information.

Mocking a database connection

This tutorial describes a classic use case for mock objects, it shows how to replace a dependency on an external call with a mock object that returns canned values. This tutorial is in German.

For feedback and questions please use the OCMock forum on this site.

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.