## EasyMock Class Extension 2.5.2 Readme

Documentation for release 2.5.2 (2009-12-20)
© 2003-2009 OFFIS, Henri Tremblay.

The EasyMock Class Extension allows to generate Mock Objects for classes.

## Requirements

The EasyMock Class Extension requires Java 5 or above, EasyMock 2.5.2, cglib 2.1 or 2.2 (2.0.x also works but cannot mock a class without visible constructor), asm (use the version that matches your cglib version, you can also use cglib-nodep-2.2.jar which includes asm), Objenesis 1.2 and JUnit 4.4 or above to run the tests.

## Usage

To generate Mock Objects for classes and interfaces, use

    import static org.easymock.classextension.EasyMock.*;

instead of

    import static org.easymock.EasyMock.*;

You will then create a mock just like with EasyMock by doing something like this:

    ToMock mock = createMock(ToMock.class);

From now on, you will use your mock just like you use to do with EasyMock. Note that `createNiceMock`, `createStrictMock`, `createStrictControl`, `createControl` and `createNiceControl` methods are also available. The `create...Control()` methods return `org.easymock.classextension.IMocksControl`, an extension of EasyMock's `IMocksControl`. Finally `org.easymock.classextension.EasyMockSupport` provides an implementation of `EasyMockSupport` working with the class extension.

## Advanced

### Partial mocking

Sometimes you may need to mock only some methods of a class and keep the normal behavior of others. This usually happens when you want to test a method that calls some others in the same class. So you want to keep the normal behavior of the tested method and mock the others.

In this case, the first thing to do is to consider a refactoring since most of the time this problem caused by a bad design. If it's not the case or if you can't do otherwise because of some development constraints, here's the solution.

    ToMock mock = createMockBuilder(ToMock.class)
       .addMockedMethod("mockedMethod").createMock();

In this case only the methods added with `addMockedMethod(s)` will be mocked (`mockedMethod()` in the example). The others will still behave as they used to. One exception: abstract methods are conveniently mocked by default.

`createMockBuilder` returns a `IMockBuilder` interface. It contains various methods to easily create a partial mock. Have a look at the javadoc.

Remark: EasyMock provides a default behavior for Object's methods (equals, hashCode, toString). However, for a partial mock, if these methods are not mocked explicitly, they will have their normal behavior instead of EasyMock default's one.

### Self testing

It is possible to create a mock by calling one of its constructor. This can be handy when a class method needs to be tested but the class other methods, mocked. For that you should do something like

    ToMock mock = createMockBuilder(ToMock.class)
       .withConstructor(1, 2, 3); // 1, 2, 3 are the constructor parameters

See the `ConstructorCalledMockTest` for an example.

### Replace default instantiator

For some reason (usually an unsupported JVM), it is possible that EasyMock CE isn't able to create a mock in your environment. Under the hood, class instantiation is implemented with a factory pattern. In case of failure, you can replace the default instantiator with:

- The good old `DefaultClassInstantiator` which works well with Serializable classes and otherwise tries to guess the best constructor and parameters to use.
- You own instantiator which only needs to implement `IClassInstantiator`.

You set this new instantiator using `ClassInstantiatorFactory.setInstantiator()`. You can set back the default one with `setDefaultInstantiator()`.

Important: The instantiator is kept statically so it will stick between your unit tests. Make sure you reset it if needed.

### Serialize a class mock

A class mock can also be serialized. However, since it extends a serializable class, this class might have defined a special behavior using for instance `writeObject`. These methods will still be called when serializing the mock and might fail. The workaround is usually to call a constructor when creating the mock.

Also, de-serializing the mock in a different class loader than the serialization might fail. It wasn't tested.

### OSGi

EasyMock CE jar can be used as an OSGi bundle. It exports `org.easymock.classextension` and `org.easymock.classextension.internal` packages. However, to import the latter, you need to specify the `poweruser` attribute at true (`poweruser=true`). cglib is also exported to allow mocks to work correctly.

## Limitations

EasyMock Class Extension provides a built-in behavior for `equals()`, `toString()` and `hashCode()`. It means that you cannot record your own behavior for these methods. It is coherent with what EasyMock do. This limitation is considered to be a feature that prevents you from having to care about these methods.

Final methods cannot be mocked. If called, their normal code will be executed.

Private methods cannot be mocked. If called, their normal code will be executed. Remember this can occur during partial mocking.

Class instantiation is performed using Objenesis. Supported JVMs are listed here.

In the Advanced section, it was explained how to do partial mocking. One important thing is that private methods are never mocked. So if your method under test is calling some private methods, you will need to test them as well since you cannot mock them.

## Development

### Authors

The EasyMock Class Extension is currently maintained by Henri Tremblay.

It was initially developed by Joel Shellman, Chad Woolley and Henri Tremblay on the files section of Yahoo!Groups.

Thanks to the people who gave feedback or provided patches, including Rodrigo Damazio, Bruno Fonseca, Ben Hutchison and numerous others.

### Release Notes

New in version 2.5.2:

- EasyMockSupport for class extension

New in version 2.5.1:

- Change license from MIT to Apache 2.0

New in version 2.5:

- Incorrectly wrapped exception returned when EasyMock methods receive a parameter that is not a mock
- Stub exception causes NPE (2407137)
- Move to Subversion
- Build entirely with Maven
- Objenesis not embedded anymore
- Add OSGi header to manifest (2774873)
- New IMockBuilder interface to easily perform partial mocking (2822905, 2788098, 2783949)
- Class mocks are now serializable (1963458)

New in version 2.4:

- Add resetToNice/Default/Strict methods (1963442)
- Can make a mock thread-safe (1895644,1953275)
- Fix on bridges calling super (thanks to Barry Kaplan)
- Copyrights updated to 2008

New in version 2.3:

- French documentation
- Be able to call constructor for partial mocking
- Mock Objects can now be named
- Switch to varargs the "mockedMethods" parameter for partial mocking
- Version in jar manifest
- Objenesis 1.1 for Aonix partial support
- Samples updated to JUnit 4
- Update to JUnit 4.4
- Maven pom more complete
- Abstract methods are mocked by default for partial mocks

New in version 2.2.2:

- Use cglib cache. Greatly improve performance and reduce used perm space
- Class instantiation using objenesis for more portability
- Update to JUnit 4.3.1
- Possibility to use your own instantiator

New in version 2.2.1:

- Varargs for record(), replay() and reset()

New in version 2.1:

- Tests migrated to JUnit 4

New in version 2.0:

- New implementation compatible with EasyMock 2