<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>EasyMock Class Extension 1.2 Readme</title>
<link rel="stylesheet" href="easymock.css" />
</head>
<body><div class="bodywidth">
<h2>EasyMock Class Extension 1.2 Readme</h2>
<p>Documentation for release 1.2 (August 15 2005)<br />
© 2003-2004 <a href="http://www.offis.de">OFFIS</a>.
</p>
<p>
The EasyMock Class Extension allows to generate
Mock Objects for classes.
</p>
<h2>
Requirements
</h2>
<p>The EasyMock Class Extension requires
<a href="http://java.sun.com">Java 1.3.1 or above</a>,
<a href="http://www.easymock.org">EasyMock 1.2</a>,
<a href="http://www.junit.org">JUnit 3.8.1</a>,
<a href="http://cglib.sourceforge.net">cglib 2.1.0</a>
(2.0.x also works but cannot mock a class without visible constructor) and
<a href="http://forge.objectweb.org/projects/asm">asm</a>
(use the version that matches your cglib version, you can also use cglib-nodep-2.1 which includes asm)
</p>
<h2>
Usage
</h2>
<p>
To generate Mock Objects for classes and interfaces,
import<br/>
<code>org.easymock.classextension.MockClassControl</code><br/>
instead of<br/>
<code>org.easymock.MockControl</code>.
</p>
<p>
You will then create a mock by doing something like this:
<pre>
MockControl ctrl = MockClassControl.createControl(ToMock.class);
ToMock mock = (ToMock) ctrl.getMock();
</pre>
</p>
<p>
From now on, you will use your mock just like you use to do with
EasyMock. Note that <code>createNiceControl</code> and
<code>createStrictControl</code> methods are also available.
</p>
<h2>
Advanced
</h2>
<p>
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.
</p>
<p>
In this case, the first thing to do is to consider a refactoring since
most of the time this problem occurs because of a bad design. If it's not
the case of if you can't do otherwise because of some development constraints,
here's the solution.
<pre>
MockControl ctrl = MockClassControl.createControl(ToMock.class,
new Method[] { ToMock.class.getDeclaredMethod("mockedMethod", null) } );
</pre>
</p>
<p>
In this case only the methods passed to <code>createControl</code> will be
mocked (<code>mockedMethod()</code> in the example). The others will still
behave as they used to.
<h2>
Limitations
</h2>
<p>
EasyMock Class Extension provides a built-in behavior for <code>equals()</code>,
<code>toString()</code> and <code>hashCode()</code>. It means that you cannot
record your own behavior for these methods. It is coherent with
<a href="http://www.easymock.org/Documentation.html#Object_Methods">what
EasyMock do</a>. This limitation is considered as a feature
that prevents you from having to care about these methods.
</p>
<p>
Final methods cannot be mocked. If called, their normal code will be executed.
</p>
<p>
Currently, only Sun JVM 1.4 or more are really well supported. By that I mean that
you can mock any kind of classes. No constructor will be called to create the mock.
</p>
<p>
If you are using Sun JVM 1.3 or another JVM vendor for your tests
a constructor needs to be called on the mocked class. Here's how it works:
<ul>
<li>Empty constructor is first called</li>
<li>If no empty constructor, first constructor of the class is called</li>
<li>Default values are provided for primitive type arguments</li>
<li>Nice mocks are provided for object and interface arguments</li>
<li>A final class argument will be directly instantiated (not mocked)</li>
<li>Mocked arguments will also need to be instantiated like the currently mocked class</li>
<li>A class with only private constructors cannot be instantiated</li>
<li>Code in the constructor will be executed and might crash. In this case the class is not mockable</li>
<li>The ability to provide it's own arguments to instantiate the class is not supported anymore</li>
</ul>
</p>
<p>
There is one exception to the previous rule. If the class is Serializable the behavior is the exact same
as for Sun JVM 1.4.
</p>
<p>
In the <a href="#Advanced">Advanced section</a>, 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.
</p>
<h2>
Authors
</h2>
<p>
The EasyMock Class Extension has been developed
by Joel Shellman, Henri Tremblay, and Chad Woolley
on the files section of Yahoo!Groups.
</p>
</div>
</body>
</html>
