OCHamcrest is an iOS and Mac OS X library providing:
- a library of "matcher" objects for declaring rules to check whether a given object matches those rules.
- a framework for writing your own matchers.
Matchers are useful for a variety of purposes, such as UI validation. But they're most commonly used for writing unit tests that are expressive and flexible.
The Examples folder shows projects using OCHamcrest either through CocoaPods or through the prebuilt frameworks, for iOS and Mac OS X development.
If you want to add OCHamcrest using Cocoapods then add the following dependency to your Podfile. Most people will want OCHamcrest in their test targets, and not include any pods from their main targets:
target :MyTests, :exclusive => true do
pod 'OCHamcrest', '~> 4.0'
end
Use the following import:
#define HC_SHORTHAND
#import <OCHamcrest/OCHamcrest.h>
Prebuilt binaries are available on GitHub. The binaries are packaged as frameworks:
- OCHamcrestIOS.framework for iOS development
- OCHamcrest.framework for Mac OS X development
Drag the appropriate framework into your project, specifying "Copy items into
destination group's folder". Then specify -ObjC
in your "Other Linker Flags".
Use the following import:
#define HC_SHORTHAND
#import <OCHamcrestIOS/OCHamcrestIOS.h>
Add a "Copy Files" build phase to copy OCHamcrest.framework to your Products Directory.
Use the following import:
#define HC_SHORTHAND
#import <OCHamcrest/OCHamcrest.h>
If you want to build OCHamcrest yourself, clone the repo, then
$ git submodule update --init
$ cd Source
$ ./MakeDistribution.sh
We'll start by writing a very simple Xcode unit test, but instead of using
XCTest's XCTAssertEqualObjects
function, we'll use OCHamcrest's assertThat
construct and a predefined matcher:
#import <SenTestingKit/SenTestingKit.h>
#define HC_SHORTHAND
#import <OCHamcrest/OCHamcrest.h>
@interface BiscuitTest : SenTestCase
@end
@implementation BiscuitTest
- (void)testEquals
{
Biscuit* theBiscuit = [[Biscuit alloc] initWithName:@"Ginger"];
Biscuit* myBiscuit = [[Biscuit alloc] initWithName:@"Ginger"];
assertThat(theBiscuit, equalTo(myBiscuit));
}
@end
The assertThat
function is a stylized sentence for making a test assertion. In
this example, the subject of the assertion is the object theBiscuit
, which is
the first method parameter. The second method parameter is a matcher for
Biscuit
objects, here a matcher that checks one object is equal to another
using the -isEqual:
method. The test passes since the Biscuit
class defines
an -isEqual:
method.
OCHamcrest's functions are actually declared with an "HC" package prefix (such
as HC_assertThat
and HC_equalTo
) to avoid name clashes. To make test writing
faster and test code more legible, shorthand macros are provided if
HC_SHORTHAND
is defined before including the OCHamcrest header. For example,
instead of writing HC_assertThat
, simply write assertThat
.
OCHamcrest comes with a library of useful matchers:
-
Object
conformsTo
- match object that conforms to protocolequalTo
- match equal objecthasDescription
- match object's-description
hasProperty
- match return value of method with given nameinstanceOf
- match object typeisA
- match object type precisely, no subclassesnilValue
,notNilValue
- matchnil
, or notnil
sameInstance
- match same object
-
Number
closeTo
- match number close to a given value- equalTo<TypeName> - match number equal to a primitive number (such as
equalToInt
for anint
) greaterThan
,greaterThanOrEqualTo
,lessThan
,lessThanOrEqualTo
- match numeric ordering
-
Text
containsString
- match part of a stringendsWith
- match the end of a stringequalToIgnoringCase
- match the complete string but ignore caseequalToIgnoringWhitespace
- match the complete string but ignore extra whitespacestartsWith
- match the beginning of a stringstringContainsInOrder
- match parts of a string, in relative order
-
Logical
allOf
- "and" together all matchersanyOf
- "or" together all matchersanything
- match anything (useful in composite matchers when you don't care about a particular value)isNot
- negate the matcher
-
Collection
contains
- exactly match the entire collectioncontainsInAnyOrder
- match the entire collection, but in any orderhasCount
- match number of elements against another matcherhasCountOf
- match collection with given number of elementshasEntries
- match dictionary with list of key-value pairshasEntry
- match dictionary containing a key-value pairhasItem
- match if given item appears in the collectionhasItems
- match if all given items appear in the collection, in any orderhasKey
- match dictionary with a keyhasValue
- match dictionary with a valueisEmpty
- match empty collectiononlyContains
- match if collection's items appear in given list
-
Decorator
describedAs
- give the matcher a custom failure descriptionis
- decorator to improve readability - see "Syntactic sugar" below
The arguments for many of these matchers accept not just a matching value, but
another matcher, so matchers can be composed for greater flexibility. For
example, only_contains(endsWith(@"."))
will match any collection where every
item is a string ending with period.
OCHamcrest strives to make your tests as readable as possible. For example, the
is
matcher is a wrapper that doesn't add any extra behavior to the underlying
matcher. The following assertions are all equivalent:
assertThat(theBiscuit, equalTo(myBiscuit));
assertThat(theBiscuit, is(equalTo(myBiscuit)));
assertThat(theBiscuit, is(myBiscuit));
The last form is allowed since is
wraps non-matcher arguments with equalTo
.
Other matchers that take matchers as arguments provide similar shortcuts,
wrapping non-matcher arguments in equalTo
.
OCHamcrest comes bundled with lots of useful matchers, but you'll probably find that you need to create your own from time to time to fit your testing needs. See the "Writing Custom Matchers" guide for more information.