ReleaseNotes - mockito - Project Hosting on Google Code

- warning this might make your code not compiling but it's quite unlikely. You probably always want return the correct type when stubbing so please don't curse Mockito and fix your code in case this feature breaks compilation.

when(foo.get()).thenReturn(compilerChecksTypeHere);

Minor fixes

See issues tracker: http://code.google.com/p/mockito/issues/list?q=label:Release1.7%20status:Fixed&can=1

Setting default return values on mock creation

This feature was invented by Dan North and should be helpful when dealing with legacy code. For example, you can create a mock that returns 'SmartNulls' by default (e.g. unless stubbed). If your code under test tries to use the SmartNull it will throw an exception saying something along these lines: 'You've got a NullPointerException here <clickable stack trace element> because you forgot to stub this method: <another clickable stack trace element>'

Foo mock = (Foo.class, RETURNS_SMART_NULLS);

//calling unstubbed method here:
Stuff stuff = mock.getStuff();

//using object returned by unstubbed call:
stuff.doSomething();
   
//Above doesn't yield NullPointerException this time!
//Instead, SmartNullPointerException is thrown. 
//Exception's cause links to unstubbed mock.getStuff() - just click on the stack trace.

Mockito 2.0 mocks will probably return SmartNulls by default.

Shorthand API for consecutive stubbing

when(foo.get())
  .thenReturn("one", "two", "three");

when(foo.get())
  .thenThrow(new NullPointerException(), new RuntimeException());

Better errors when framework misused

When one misuses the framework (for example: verify(mock.foo()) instead of verify(mock).foo()) then he gets earlier error. Since 1.7, framework is validated also on mock creation.

Changed in 1.6 (21-10-2008)

API change:

//instead of:

stub(mock.getStuff()).toReturn("stuff");

//please use:

when(mock.getStuff()).thenReturn("stuff");

Many users found stub() confusing therefore stub() has been deprecated in favor of when(). We discussed this API change on the mailing list (for example here

If you're an existing user then sorry for making your code littered with deprecation warnings. This change was required to make Mockito better. How to fix deprecation warnings? Typically it's just few minutes of search & replace job:

stub replace with: when(
.toReturn( replace with: .thenReturn(
.toThrow( replace with: .thenThrow(
.toAnswer( replace with: .thenAnswer(

Fixed problem with @Mock annotation not resolved properly in IDE ( issue 21 ). This change may also require some clean up of deprecated code. Typically, the quickest way to fix deprecation warnings is some search & replace job: search: import org.mockito.MockitoAnnotations.Mock; and replace with: import org.mockito.Mock;

Added junit runners (MockitoJunit44Runner and MockitoJunitRunner) that automatically initialize annotated mocks ( issue 23 )

New feature: when arguments are different the exception now allows using the comparison window ( issue 22 ).

Fixed mock creation logic so that there no problems when running with maven ( issue 24 )

Fixed ArrayEquals exception ( issue 20 ) thanks to report by Ward Bryon

Added performance tweak ( issue 19 ) thanks to patch by Roberto Tyley

Removed 'final' on Mockito class ( issue 18 )

Fixed issue 25

Changed in 1.5 (26-07-2008)

1. Stubbing methods with generic Answer interface:

   stub(mock.someMethod(anyString())).toAnswer(new Answer() {
       Object answer(InvocationOnMock invocation) {
           Object[] args = invocation.getArguments();
           Object mock = invocation.getMock();
           return "called with arguments: " + args;
       }});

Useful for adding side effects or in some other non-trivial scenarios. Should be used carefully and occasionally. Adds more power and flexibility to the framework. As usual: with the great power comes the great responsibility :) Thanks to John Hampton Jr for contributing a patch.

2. Syntax modification:

   //Instead of:
   stubVoid(mock).toThrow(ex).on().someVoidMethod();

   //Since 1.5 you do:
   doThrow(ex).when(mock).someVoidMethod();

stubVoid() has been deprecated so a bit of clean up in your code is required (unless you don't care about compiler warnings). However, there should not be too much of a hassle since stubbing voids is pretty rare.

Syntax modification was required to make things more readable, more consistent and to solve one corner case (more reading here)

doThrow() functionality was completed by doAnswer(), doNothing(), doReturn() methods. Please refer to docs for more information.

3. Spying on real objects

In rare scenarios we would like to use real objects but still take advantage of verify() and stub() methods. Spying on real objects is associated with controversial partial mocking feature. We discussed it here

   List list = new LinkedList();
   List spy = spy(list);

   //wow, I can stub it!
   stub(spy.size()).toReturn(100);

   //wow, I can use it and add real elements to the list!
   spy.add("one");

   //wow, I can verify it!
   verify(spy).add("one);

Enough of wows, this feature should be used carefully and occasionally. With the great power...

4. Started including cglib and asm in mockito-core.

There were few problems with cglib: no latest release in maven central blocking our release; problems when upgrading from mockito 1.4->1.5 due to conflicting versions of cglib on classpath. To fix those problems we decided to include cglib and asm inside mockito-core. Libraries are included with renamed packages (JarJar task feature) so there should be no problems with conflicting versions any more. Thanks to Ola Bini for this idea.

5. Fixed issue 11 related to using mockito in eclipse container (e.g. Run as plugin test)

6. Fixed issue 14 related to multiple threads playing with the same mock instances.

7. Javadoc enhancements based on always welcome users' feedback.

Changed in 1.4

Added new stubbing feature: different return values for consecutive method calls (like mocking iterators). This feature is to be used judiciously. Mocking iterators can be avoided by preferring Iterables/collections which results in simpler and cleaner code.

stub(mock.getStuff())
  .toReturn(1)
  .toReturn(2)
  .toThrow(new RuntimeException());

Changed anyX() matchers to treat nulls as a valid 'anything' value.

Added few handy matchers: anyCollection(), anyList(), anyMap().

Started using cglib 2.2 stable.

Fixed issue 13 (anyObject() matcher with varargs problem).

Added more descriptive exception message based on reported typical misuse (Added comment that the user might forget to call initMocks() when annotation @Mock is used).

Javadoc enhancements based on comments.

Changed in 1.3

Started using cglib 2.1.3 to sort out maven dependencies.

Started using field names of annotated (@Mock) mocks for printing failed interactions. That gives better readability and also promotes good names for fields. For example following mock:

  @Mock private LinkedList listOfArticles;

  //in case of verification error, will be printed like that: 

  "Wanted but not invoked: listOfArticles.clear();"

  //In previous version, it would be like that:

  "Wanted but not invoked: LinkedList.clear();"

To be more consistent with previous feature, invocations are printed with lowercase first letter. For example if you happened to mock a LinkedList then the verification error will show linkedList.clear() instead of LinkedList.clear().

Tuned verification messages when arguments don't match. Arguments are automatically broken to vertical list if printed invocation is too long.

Default return values for primitive wrapper classes are now consistent with primitives. E.g: an int method returns 0 but an Integer method also return 0 instead of null.

Enabled stubbing toString() because 'why not' and it may be useful for debugging purposes

Exposed configuration of default return values to enable custom 'mocking style'. Helpful for legacy code. For more information read this thread or look at examples here or here.

Fixed issue with reporting errors related to issue #7

Added some examples to the test code, e.g. using JUnit runner to take advantage on @Mock annotation and avoid infamous base class for tests.

Javadoc changes to reflect feedback from users