What Benefits Are There in the New, Improved OCHamcrest? 

Many of you already use OCHamcrest, the matcher library I initially ported from Java back in 2008. I’m writing today to announce OCHamcrest 5.0.0, and to explain what you’ll get out of upgrading.

But first, what does it mean to jump from v4.3.2 to v5.0.0?

Semantic Versioning

OCHamcrest uses Semantic Versioning. A change in the major version number (in this case, going from 4.x to 5.x) doesn’t necessarily mean there’s a shiny new feature. Rather, it communicates that I’ve made changes that may break backwards compatibility for you.

In other words, the major version change isn’t marketing. It means that if you’re currently using OCHamcrest, dropping in v5.0.0 may require changes in your code. I say “may” because it depends on your code. Most of you should be able to upgrade without any changes. (But I’m going to urge you to make a simple global edit of the HC_SHORTHAND define.)

I bump the major version number when I delete any public APIs. The following are gone:

• Replace equalToBool with isTrue / isFalse
• Rename containsString to containsSubstring
• Rename assertThatAfter / futureValueOf to assertWithTimeout / thatEventually
• Replace HC_testFailureHandlerChain() with [HCTestFailureReporterChain reporterChain]

These APIs were already marked as deprecated, so if you see any warnings about deprecated code, your code isn’t ready for v5.0.0. Clean those up first.

But hey, if I’m breaking backwards compatibility anyway, I may as well take advantage of the opportunity to introduce a bigger change…

No More #define HC_SHORTHAND

Because Objective-C lives in a C world, there are no custom namespaces. We use package prefixes to avoid stepping on each other’s toes. Apple says, “Your own classes should use three letter prefixes.” OCHamcrest actually violates this by using the two-letter prefix HC for its classes. This was either because I didn’t know about Apple’s recommendation when I started, or they hadn’t spelled it out yet.

Prefixes are necessary for anything in the global namespace. Among other things, this applies to functions—which OCHamcrest makes extensive use. For example, the factory function that creates an HCIsEqual object is HC_equalTo. (I did use a three-letter prefix HC_ with that unusual underscore for OCHamcrest functions.)

The matcher assertion

HC_assertThat(actual, HC_equalTo(expected))

works, but the prefixes make it less appealing than the Java version. So I decided to offer an optional “shorthand” version. A #define HC_SHORTHAND before importing OCHamcrest.h created replacement macros so that we Objective-C folks can also write

assertThat(actual, equalTo(expected))

But things are changing, and it’s time to switch things around…

What you need to do:

If there are places where you have worked to avoid name clashes by not defining HC_SHORTHAND before importing OCHamcrest.h, you must now explicitly #define HC_DISABLE_SHORT_SYNTAX before the #import. (Hat tip to Quick for illustrating how to do this.)

What you ought to do:

Leaving #defines that are no longer useful clutters your code. I’d replace all occurrences of #define HC_SHORTHAND (followed by newline) with nothing, to delete these lines.

Why?

We are shifting away from a world where a #define can affect the contents of an imported header. Modules and @import aren’t yet available to custom frameworks, but they beckon. To get there and still keep short syntax, I am making short syntax the default.

Matchers That Take Objective-C Literals

When I first wrote OCHamcrest, Objective-C only had string literals. So any matchers that took variable-length lists were comma-separated, ending with nil. And for numeric types, there’s an entire set of assertThat<Type> and equalTo<Type>, such as assertThatInt and equalToInt.

Again, times have changed. The older assertThats and numeric matchers are still there, but I don't use them anymore. I use NSNumber literals like @123, or box primitive variables into NSNumbers like @(value). That is, instead of

I use

That much came for free when Objective-C added NSNumber literals. But support for variable-length lists as literals required new matchers. So in OCHamcrest 5.0.0, nearly all matchers with variable-length lists have new “In” variants that that take collection literals.

What you can do:

Let's take anyOf as an example. It basically takes multiple matchers and “or's” them together. You can continue to use the nil-terminated

But now you can say anyOfIn and specify an array literal:

There is one matcher that takes an NSDictionary instead, and that's hasEntriesIn. With the old hasEntries, you specify a variable-length list of alternating keys and their value matchers:

But now you can specify it more naturally:

Finally, you should know that describedAs doesn’t have a "describedAsIn" variant.

Better Argument Handling

So far, I’ve mentioned two facets of my original design for OCHamcrest: short names for factory functions, and variable-length lists terminated with nil.

I implemented the short names with macros. But at the time, I didn’t know how to combine macros with variable-length arguments. So I punted, and did this:

No argument handling, just straight replacement of text. But this introduced a problem. HC_assertThat takes two arguments, the actual value and a matcher. I once tried to handle these as macro arguments:

But this didn’t work well, especially with matchers that took variable-length lists. The preprocessor didn’t know what to make of those extra commas. So I backed off and kept assertThat as a simple substitution macro:

Fast-forward to OCHamcrest 5.0.0. In the process of writing the new “In” matchers (and having the old variadic matchers call their “In” variants), I learned more about variadic arguments and was able to get them working on macros. This gives you better hinting as you enter OCHamcrest expressions:

Better Help

Apple’s support for HeaderDoc has waxed and waned. Xcode used to display documentation on commented macros, but this hasn’t worked for some time. But by converting most macros to inline functions, the documentation is restored. Moreover, I’ve updated all the documentation to be more precise. For example:

Unfortunately, matchers with nil-terminated arguments are still macros, so Xcode doesn’t show their documentation. Of course, it’s all there in the headers, so you can see them that way. Or you can begin adopting the “In” matchers which have full documentation.

OCHamcrest remains valuable for me, and I hope you find it helpful. Besides these, what changes would you like to see? Do you have a matcher wish-list? Leave a comment below.