1962c53 Nov 24, 2016
658 lines (417 sloc) 18.8 KB



  • Adopt latest Objective-C annotations for designated initializers, unavailable initializers, typed arrays, nullability.

Version 6.0.0

04 Aug 2016


  • Improved mismatch descriptions for contains, containsIn when actual collection exceeds expected size.


  • equalToIgnoringWhiteSpace matcher (deprecated in v5.4.0)
  • HCCollectMatchers (deprecated in v5.3.0)

Project changes:

  • Increased deployment targets to OS X 10.9, iOS 7.0.

Version 5.4.0

03 Jun 2016


  • Added captureEnabled property to HCArgumentCaptor to control whether subsequent matched values are captured.


  • Updated CocoaPods instructions and examples to CocoaPods 1.0.


  • equalToIgnoringWhiteSpace has been renamed to equalToCompressingWhiteSpace.
  • Known issue: warning on this deprecation

Version 5.3.0

22 May 2016


  • Removed semicolons that triggered warnings for -Wsemicolon-before-method-body. Thanks to: Sylvain Defresne
  • Describe isIn matcher in README.


  • Rewrote assertThatAfter to use runloop observer instead of while loop comparing dates. The condition is now tested on every pump of the runloop instead of polling after a predefined delay. Thanks to: Dan Fleming


  • Deprecated HCCollectMatchers. Instead, follow the example of HCAllOf.m and break it into two steps: HCCollectItems, then HCWrapIntoMatchers. This will let you expose a new interface to your matcher that takes an NSArray.

Version 5.2.0

16 Jan 2016


  • Fixed umbrella header for Carthage. Thanks to: Sylvain Rebaud, Engin Kurutepe


  • Improved mismatch descriptions for allOf, allOfIn.

Version 5.1.0

14 Dec 2015


  • Added HCDescribeMismatch, a helper function to describe mismatches the way assertThat does.
  • Added Carthage support for Mac, iOS, watchOS and tvOS. Thanks to: Nikolaj Schumacher

Version 5.0.0

02 Nov 2015

For detailed discussion on v5.0.0, see


  • Instead of enabling short syntax by defining HC_SHORTHAND, short syntax is now enabled by default. To disable it, #define HC_DISABLE_SHORT_SYNTAX.
  • Matchers which take nil-terminated lists have "In" variants which take a single NSArray, like allOfIn. The matcher hasEntriesIn is an exception and takes an NSDictionary.
  • Improved documentation on all matchers. Documentation is now shown for matchers with fixed numbers of arguments. All matchers provide argument hinting.


  • Renamed long syntax for containsInRelativeOrder from prefix hc_ to HC_ to conform to other matchers.


  • equalToBool matcher (deprecated in v4.1.0)
  • containsString matcher (deprecated in v4.2.0)
  • assertThatAfter/futureValueOf (deprecated in v4.2.0)
  • HC_testFailureHandlerChain() (deprecated in v4.2.0)

Version 4.3.2

31 Oct 2015

Project changes:

  • Enabling "Symbols hidden by default" in 4.3.1 was overkill, preventing people from using the prebuilt Mac framework.

Version 4.3.1

24 Oct 2015

Project changes:

  • Remove debug symbols from Release configuration, which bloated the libraries and kept folks from using the prebuilt iOS framework.

Version 4.3.0

11 Oct 2015


  • New matcher containsInRelativeOrder matches collections containing items in relative order.
  • New matcher HCArgumentCaptor matches anything, capturing matched values.

Project changes:

  • Updated project settings to Xcode 7, with tests now run by XCTest.

Version 4.2.0

11 Sep 2015


  • Fixed "Incompatible pointer types sending 'Class' to parameter of type 'NSString *'" warning on instanceOf.


  • Improved readability of asynchronous tests: assertWithTimeout(1, thatEventually(var), is(@10));
  • Added ability to add custom test failure reporter. See HCTestFailureReporterChain.


  • Deprecated containsString; use containsSubstring instead. containsString clashes with an NSString method introduced in iOS 8.
  • Deprecated assertThatAfter/futureValueOf. Use assertWithTimeout/thatEventually instead.
  • Deprecated HC_testFailureHandlerChain(); use [HCTestFailureReporterChain reporterChain] instead.

Version 4.1.1

31 Dec 2014

  • Oops! Add the new features to OCHamcrest.h

Version 4.1.0

30 Dec 2014


  • Fixed crash when OCHamcrest tries to describe an OCMockito mock object. Thanks to: Michael Seghers
  • Fixed crash when equalToBool attempts to match a non-number.


  • assertThatAfter tests asynchronous code, retrying the assertion until a given timeout. Wrap the code you want to evaluate in futureValueOf. Thanks to: Sergio Padrino
  • New matcher everyItem matches collections if every item satisfies a given matcher.
  • New matcher throwsException matches a block if it throws an exception satisfying a given matcher.
  • New matchers isTrue and isFalse match non-zero and zero NSNumbers. Intended to replace equalToBool.


  • Added new base class HCDiagnosingMatcher to simplify complex matchers.
  • equalToBool matcher can no longer be created with a value other than YES or NO. This especially avoids the accidental @YES.
  • Improved ordered comparison matchers (greaterThan, etc.) so that when the given object can't be compared, the matchers return NO instead of throwing an exception.
  • Improved mismatch descriptions for hasItem.
  • Improved mismatch descriptions for hasProperty to show actual property value or "no property".
  • Improved mismatch descriptions for onlyContains, especially in reporting all elements that don't match.
  • Updated project to make it run-path dependent. Thanks to: csano


  • equalToBool deprecated in favor of isTrue and isFalse. equalToBool(YES) had too much potential for semantic error since any non-zero number evaluates to true.

Version 4.0.1

04 Jun 2014

Project changes:

  • Increased deployment targets to OS X 10.8, iOS 6.0.

Version 4.0.0

10 May 2014

This is a refactoring release with potential backwards compatibility issues for writers of custom matchers:

  • Almost all ivars have been converted to hidden properties. Let me know if this trips you up.
  • If you subclass HCInvocationMatcher for a custom matcher, the ivars have been renamed.
  • If you import HCCollectMatchers.h for a custom matcher, change this to import HCCollect.h.
  • HCTestFailureHandler has changed from a protocol to a class.

Also, if you're not using CocoaPods, specify -ObjC in your "Other Linker Flags".

Version 3.0.1

29 Oct 2013


  • Fixed problem where isNot did not ask the sub-matcher's mismatch description. Thanks to: James Richard and Jonathan Barnes
  • Fixed crash in describedAs matcher . Thanks to: Nikolaj Schumacher
  • Fixed crash in hasProperty matcher when the property is a primitive type. Thanks to: Nikolaj Schumacher


  • Changed matcher factory methods to return plain id so that matchers can be used without casting to (id) for OCMockito arguments.
  • Added support for 64-bit iOS devices.

Examples & Documentation:

  • Updated examples so they are based on Apple's templates for main target vs. test target. Added CocoaPods examples.
  • Eliminated DocSet. Documentation will be in the main README and in the OCHamcrest wiki,

Version 3.0.0

06 Sep 2013


  • Added support for XCTest. Special thanks to Jiajun "gaosboy" for pointing the way, and to Richard Clem for testing.
  • Made unit test integration more flexible with HC_testFailureHandlerChain. It can be called from outside OCHamcrest to signal a test failure within the current testing framework. (At present it tries XCTest, then SenTestCase, then falls back on raising a generic exception.)


  • HCRequireNonNilString.h (deprecated in v1.2)
  • empty matcher (deprecated in v2.1.0)

Version 2.1.0

23 Jun 2013


  • Made build script flexible so that doxygen isn't required, or can be in a different location. Thanks to: Bennett Smith
  • Fixed problem formatting percent symbols in assertion failures. Thanks to: Nikolaj Schumacher
  • Fixed wrong descriptions in the unordered collection matcher. Thanks to: Nikolaj Schumacher
  • Fixed underlying cause of crash in Mac version on assertion failure. With this fix, we could switch back to optimized code. Thanks to: Nikolaj Schumacher
  • Fixed MacExample so it finds OCHamcrest.


  • Added support for XCTest. (This was undone by subsequent updates to XCTest.)


  • empty clashed with the C++ string method of the same name. It has been renamed to isEmpty.

Project changes:

  • Increased deployment targets to Mac OS X 10.7, iOS 5.0.

Version 2.0.1

12 May 2013


  • Fixed crash in Mac version on assertion failure. (Problem with optimized code)
  • Fixed crash in instanceOf and isA when argument was nil.


  • Updated example projects to Xcode 4.6.

Version 2.0.0

13 Apr 2013

This release adopts Semantic Versioning ( Since removal of deprecated items is a backwards incompatible change, the major version number is incremented. Thanks to: Jens Nerup


  • Fixed GTM compatibility -- avoid shadowing conformsToProtocol:

New matchers:

  • isA matches objects that are instances of a given class, but not of any subclass.

Improved matchers:

  • equalToBool has a better description. Thanks to: Jonathan Crooke
  • instanceOf mismatch description now includes actual class.

Deleted following items deprecated in v1.8:

  • C++ template function boxNumber
  • HC_conformsToProtocol (which was renamed to HC_conformsTo)

Project changes:

  • Updated project settings to Xcode 4.6. Thanks to: Florian Buerger
  • Fixed unit tests so they remain quiet when handling expected test failures.
  • Replaced older code coverage scripts with XcodeCoverage submodule.

Version 1.9

23 Nov 2012

Improved matchers:

  • Changed hasCount / hasCountOf mismatch description so that count comes first (if object has a count).

Project changes:

  • Fixed warnings revealed by latest Xcode. Thanks to: David Hart
  • Changed iOS Architecture support to "Standard" (which includes armv7s)
  • Changed Mac Architecture support to 64-bit only
  • Converted source, tests, and examples to ARC

Version 1.8

09 Jul 2012

The primary purpose of this release is to make it easier to add OCHamcrest to iOS projects. No more need to specify "Other Linker Flags"! Depending on your project, you may be able to eliminate:

  • -lstdc++
  • -ObjC

Also, the repository has a new official home:

No need to specify "Other Linker Flags" in iOS projects:

  • Changed all Objective-C++ to Objective-C
  • Eliminated categories


  • C++ template function boxNumber.
  • conformsToProtocol clashed with the method of the same name. It has been renamed to conformsTo.

Deleted following items deprecated in v1.2:

  • -[HCDescription appendValue]
  • +[HCInvocationMatcher createInvocationForSelector:onClass:]
  • NSObject+SelfDescribingValue

Version 1.7

20 Feb 2012

New matchers:

  • conformsToProtocol matches objects that conform to a given protocol. Thanks to: Todd Farrell

Improved matchers:

  • hasProperty now works for methods with primitive return types. Thanks to: Christopher Pickslay

Other improvements:

  • Rewrote introductory sections of documentation.

Version 1.6

27 Sep 2011


  • stringContainsInOrder was missing from the master header; now it's there.

New matchers:

  • hasProperty matches the return value of a method with a given name. (It could be a property, but really can be any method with no arguments that returns an object.) Thanks to: Justin Shacklette


  • Rewrote documentation.
  • Matchers that require a nil-terminated list now generate a compiler error if you don't have nil at the end.

Version 1.5

29 Apr 2011


  • Fixed crash when trying to describe an object with nil description.


  • Updated project to Xcode 4. iOS framework / documentation / distribution scripts are now external, run from command-line instead of Xcode.
  • Improved documentation by adding Factory headings pointing from implementing classes back to their factories.

New matcher:

  • stringContainsInOrder matches string containing given list of substrings, in order.

Improved matchers:

  • Changed sameInstance mismatch description to omit address when describing nil.
  • For consistency, changed anyOf and allOf to implicitly wrap non-matcher values in equalTo.

Version 1.4

13 Feb 2011

New matchers:

  • hasEntries matches dictionary containing key-value pairs satisfying a given list of alternating keys and value matchers.


  • Added complete descriptions to macros so they appear in Xcode 4 Quick Help. (Couldn't add arguments to macros without breaking backwards compatibility.)

Improved descriptions:

  • Improved description of hasEntry, removing colon so it doesn't get truncated in Xcode's error display.
  • is no longer says "is ..." in its description, but just lets the inner description pass through.
  • Consistently use articles to begin descriptions, such as "a dictionary containing" instead of "dictionary containing".

Version 1.3

05 Jan 2011

Improved descriptions:

  • Fixed contains and containsInAnyOrder to describe mismatch if item is not a collection.
  • Fixed describedAs and is to use their nested matchers to generate mismatch descriptions.
  • sameInstance is more readable, and includes object memory addresses.
  • If object has a count, hasCount mismatch describes actual count.
  • Don't wrap angle brackets around a description that already has them.
  • Improved readability of several matchers.

Other improvements:

  • instanceOf now guards against nil being passed as the expected type.

Version 1.2

03 Jan 2011


  • Fixed assertThat to describe the diagnosis of the mismatch, not just the mismatched value.

New matchers:

  • hasCount matches collections for which -count satisfies a given matcher.
  • hasCountOf matches collections for which -count equals a given count.
  • empty matches empty collection.


  • Expanded helper class HCInvocationMatcher:
    • New property shortMismatchDescription determines whether mismatch description is short or long. Default is long description.
    • New method -invokeOn: invokes stored invocation on given item.
  • Since nil cannot be directly stored in collections, collection matchers now guard against nil.
  • Expanded BaseDescription's -appendDescriptionOf: to handle all types of values, not just self-describing values.


  • Description's -appendValue: no longer needed; call -appendDescriptionOf: instead. This also means NSObject+SelfDescribingValue is no longer needed.
  • Renamed HCInvocation's helper class method +createInvocationForSelector:onClass: to +invocationForSelector:onClass:
  • New helper function HCRequireNonNilObject should be used in place of HCRequireNonNilString.

Version 1.1.2

28 Dec 2010


  • Fixed crash that occurred when trying to describe the matchers allOf, anyOf and isIn on iOS. Related to -ObjC linker flag.
  • Fix problems introduced in broken release v1.1:
    • Added the new matchers to the master header and to the iOS target.
    • Fixed distribution zip file to preserve symlinks in frameworks.

New matchers:

  • contains matches collections with matching items in order.
  • containsInAnyOrder matches collections with matching items in any order.


  • Changed documentation from HTML to Xcode documentation set. Run make install from the Documentation folder to install.
  • Rearranged documentation modules to make things easier to find.
  • Changed convenience methods to invoke superclass and return id, to support possibility of subclassing matchers.

Version 1.0

26 Oct 2010

First official release, including:

  • Documentation
  • Examples for
    • Cocoa
    • iOS
    • Creating a custom matcher

Before v1.0

07 Oct 2010

  • For iOS: Added OCHamcrestIOS.framework target which provides release builds for both simulator and device into a single framework. Yes, a framework that can be used for iOS development without requiring users to mess with header search paths and link settings. Simply drop the framework into your project and #import <OCHamcrestIOS/OCHamcrestIOS.h> Thanks to: Aaron Jacobs

06 Oct 2010

  • Work around bug in iPhone simulator that causes a test failure to terminate the app. Thanks to: Aaron Jacobs

06 Sep 2010

  • Added static library target and changes for iOS.

01 Dec 2009

  • Added assertThat___ and equalTo___ for all types understood by NSNumber. For example:
    assertThatInt(42, equalToInt(42))

24 Nov 2009

  • Changed assertThat behavior to work more seamlessly with OCUnit: Instead of throwing an exception, it calls the same method as OCUnit's assertion macros to fail the test. As a result, a failing assertThat will not terminate the test, so that the test can record other failures. (Following normal OCUnit behavior, you can instruct the test case to terminate at the first failure by invoking raiseAfterFailure.)
    This change requires that assertThat be called only within subclasses of SenTestCase, which wasn't the case before. You will need to recompile your tests.
    If you need an original-style assertion that can be called outside of a SenTestCase, email your request to

24 Nov 2009

  • Support Xcode 3.2's redesigned Build Results window by removing colons from assertThat description.

17 Oct 2009

  • Added helper class HCInvocationMatcher for building other matchers from NSInvocations. See HCHasDescription for an example.

11 Aug 2009

  • Renamed framework to OCHamcrest.

07 Jul 2009

  • Added support for Mac OS X 10.4 projects.

28 Jan 2009

  • Fixed compiler errors when used with Objective-C++ (.mm files).

24 Jan 2009

  • Added means for matchers to describe mismatches. You can use either matches:describingMismatchTo: to do it one shot, or call describeMismatchOf:To: once you know a particular item does not match.

18 Jul 2008

  • Changed matchers whose description looks similar to a function call so that the description matches the name of the factory function.

13 Apr 2008

  • Initial release