We wasted a lot of time on our last integration test on a bug that I think should have been found in unit testing. The problem was that an interface / service we called behaved different than we expected and the unit test didn't find this problem because we mocked that interface for the unit test and our mock was of course based on our mistaken interpretation of what the interface would do. Now I could be a bit angry at our dear coworker who provided the interface, because their description / specification of it (a terse JavaDoc comment) was ambiguous and contributed to our misunderstanding. On the other hand, I thought that the problem could have been avoided if those same coworkers had provided a mock implementation of their interface which we could call in our unit testing. Then the bug would have shown up much earlier and a lot of cursing could have been avoided.

Now, what's the best practice in organizing the creation of mock objects among teams who provide and use shared interfaces? What are your experiences?

  • I hope in all this investigation of blame you included some for yourself for not asking the author if you understanding was correct... One question on your part could have saved all the pain.
    – Walter
    Apr 3, 2011 at 13:21
  • 2
    Walter, thanks for your edits and constructive comment. Your suggestion does not answer the question directly, but is in fact a solution to the original problem I have. Since I find it so hard to ask good questions about one's own understanding, I came up with another idea: we could have asked the other team to review our plan to use their interface and they might have spotted the problem. Apr 4, 2011 at 14:59

2 Answers 2


Ideally, yes.

Anyone who writes code that other people use is not bound to provide anything complementing the code. However, if you want people to use your code (and everyone should always be writing with this mentality), extensive relevant documentation - which may include examples - are extremely useful.

I don't think I've ever read documentation and have thought, "This is stupid; there's way too much documentation." People are naturally gifted at skipping over what they deem unnecessary. We, however, cannot simply mind-read and interpolate the documentation or concepts that have not been explained. So, it's safe to assume: there's no such thing as too much good documentation. It should also assume that the person reading it as a naive infant (i.e. make it as simple as possible).

Examples on how to instantiate and use a class is always helpful. Although, if the code relies too heavily on the documentation to be understood, that is another (separate) issue.

This answer shouldn't be seen as firepower that will justify yelling at your co-worker. It is merely a guideline of what I think is beneficial and should be done. While this is completely useless in your situation (although, I feel your question is basically a rant), the next best thing you can do is lead by example and hope your colleague comes around.

  • 1
    While I have found myself complaining about too much documentation, those instances have been rare (and was taking issue more with the quality that resulted in very long worded and confusing docs).
    – user131
    Apr 3, 2011 at 11:18
  • 1
    @Tim: Thanks, have just edited - I was referring to good documentation. Unfortunately, anyone can write a bunch of rubbish as 'documentation'!
    – J.K.
    Apr 3, 2011 at 11:23

Should the provider of an interface also provide a mock implementation for testing?

No, but the provider should also provide the sourcecode for their unittests. Reading these unittests you will get a good impression how the library should be used. Maybe you can add unittests to the provider-tests in order to specify what you expect from the provider.

There are many mocking tools/framework out there that can implement a fake/stub/mock.

Asking the provider for a mock implementation has no good cost/benefit relation because he cannot know which part of the fake implementation must be nearly identical to the real implementation and which part is just facade.

An other way around this is if the provider uses codecontracts to make sure that the lib is used in the specified way.

  • +1 "There are many Mocking tools/framework out there that can implement a fake/stub/mock."
    – Armand
    Apr 3, 2011 at 12:26
  • Unit Tests: I see two problems in using them as documentation: 1. they only show examples of what the service supports, but won't tell me if a certain use I have in mind is supported. 2. Reading unit tests is just about as demanding / tiring as reading code and I am looking for a solution that saves everybody work. I am looking for something that works automatically, like tests or contracts (which we're also looking into). Apr 4, 2011 at 15:17
  • "Provider cannot know the use of the mock": I am not sure about that. For one thing the mock should check all the preconditions (is the service used right) and it should return some dummy values. Basically all that is needed to unit test a client. Could you elaborate more on what information the provider is missing to do this well? Apr 4, 2011 at 15:21
  • the mock should check all the preconditions: why does the mock need to check if the real lib does this checking. If you have an integration tests with the real lib these tests should lead you to the problem.
    – k3b
    Apr 4, 2011 at 15:40
  • k3b: we want to find bugs as early as possible and integration test can be much later. This was exactly the problem that we had. Well, we're already working to improve the process so that integration tests can happen earlier and more often, but still unit tests should find as many bugs as possible. Apr 4, 2011 at 15:46

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.