Many of the SVP reviewers weren't happy with the tests that use of jMock, finding them hard to decipher. I think that a subset of the group is fairly representative of your target audience: capable Java developers who've not been exposed to jMock. So what to do (in short order) to ease people in without getting the "I'm not liking this" reaction?

First, I think a stronger warning up front to go read the appendix (and the online docs) is in order. It's tempting to want to plow ahead, figuring out jMock from usage patterns in the tests. Our experience is that this approach doesn't work well.


Comments on the appendix (and a few comments on the online docs):

First, the [...] style of eliding is different from what's used in the book. (I realize it's from the online docs, but I don't like it there, either).


In Creating Mock Objects, the two argument form of mock() raises a "why would I want/need to?' question. You might mention that "turtle2" gives the mock a non-default name that's used when printing failure diagnostics. (It's under-documented online, too.)


In Test with Expectations, we find '{{'. I'm guessing that 95% of Java developers have never encountered instance initializers, and have seen fairly senior developers throw a WTF when first encountering them. It's not the job of the book to teach people Java, but it may do to throw in a short explanation of this obscure but useful language feature.

In digging in to checking() in the online docs, I'm told that it takes an ExpectationBuilder, which isn't linked in the javadoc. It takes a bit of digging to find that an Expectation is a subclass, and that the methods I'm interested in are documented there. That's an understandable gap given Javadoc, but is still a minor frustration.


In Expectations, I find a block of code where part is inexplicably indented. That's puzzling, and I learn later (from the online docs) that it seems to be a convention. That might be worth mentioning.

In the explanation of the example, the second (3) bullet wants to be a (4).

Nit: in the text for 'allowing, ignoring', s/it's there to/they're there to/


In Argument Matchers, I'm initially puzzled by the difference between any() and a()/an(), then find in the 2.5.1 javadoc that a() and and() are deprecated. I suggest leaving them out.


In Actions, is the description of will(returnIterator(c)) correct? Do I really get c, or an iterator that returns only c?
It looks like a single-argument form of will(returnIterator(v1, v2, ..., vn))


In States, the code won't compile. s/state-machine-name/state_machine_name/


At the end, I'm wishing for one complete example of a test using jMock, with explanatory bullets, to tie the pieces together.

Dave