public void testVoteForRemoval() {
        mock.documentAdded("Document");   // expect document addition
        // expect to be asked to vote for document removal, and vote for it
        expect(mock.voteForRemoval("Document")).andReturn((byte) 42);
        mock.documentRemoved("Document"); // expect document removal
        replay(mock);
        classUnderTest.addDocument("Document", new byte[0]);
        assertTrue(classUnderTest.removeDocument("Document"));
        verify(mock);
    }

    public void testVoteAgainstRemoval() {
        mock.documentAdded("Document");   // expect document addition
        // expect to be asked to vote for document removal, and vote against it
        expect(mock.voteForRemoval("Document")).andReturn((byte) -42);
        replay(mock);
        classUnderTest.addDocument("Document", new byte[0]);
        assertFalse(classUnderTest.removeDocument("Document"));
        verify(mock);
    }

戻り値の型はコンパイル時にチェックされます。例えば、 以下のコードは与えられた戻り値の型とメソッドの戻り値の型が一致していないので コンパイルされません。

    expect(mock.voteForRemoval("Document")).andReturn("wrong type");

戻り値設定用のオブジェクトを取得するのには、expect(T value)を 呼び出す代わりにexpectLastCall()を使用することも出来ます。 つまり、以下のコードの代わりに

    expect(mock.voteForRemoval("Document")).andReturn((byte) 42);

次のように指定することもできるのです。

    mock.voteForRemoval("Document");
    expectLastCall().andReturn((byte) 42);

コンパイル時に型チェックが出来ないので、このような型指定の仕方は 一行が長くなりすぎるときに限定すべきです。

例外の取扱い

例外(より正確にはThrowable)がスローされるように指定するには、 expectLastCall() と expect(T value) が返すオブジェクトの andThrow(Throwable throwable) メソッドを使用します。 このメソッドは記録状態の時に、例外をスローしたいメソッドの呼出しをモックオブジェクトに対して 行ったあとに呼び出さなければなりません。

チェック対象外の例外(つまり、RuntimeException, Error およびそれらのサブクラス)をスローすることもできます。チェック対象例外は、その例外が 実際に対象メソッドのthrows句に指定されている場合のみ指定できます。

実行時の戻り値や例外の生成

前もって期待される戻り値や例外を指定するのではなく、 実際のメソッド呼出しの実行時に戻り値や例外を生成したい時もあるでしょう。 EasyMock2.2からは、expectLastCall()とexpect(T value) が返すオブジェクトはandAnswer(IAnswer answer)メソッドを提供します。 このメソッドの引数にIAnswerインタフェースの実装を渡すことで、 戻り値や例外を生成することが出来ます。

IAnswer コールバックの内部で、モックに渡された引数は EasyMock.getCurrentArguments() を通じて利用できます。 これを利用すると、パラメータの順序変更のようなリファクタリングによってテストが 壊れる可能性があるので注意が必要です。

同じメソッド呼出しに対する振る舞いの変更

times, andReturn, および andThrow メソッドを繋げて使用することによって、 一つのメソッドに対する振る舞いを変更することも可能です。 例えば、次の例ではvoteForRemoval("Document")を以下のように 定義しています。

• 最初の3つの呼出しに対して42を返す。
• その次の4つの呼出しに対してはRuntimeExceptionをスローする。
• 一度-42を返す。

    expect(mock.voteForRemoval("Document"))
        .andReturn((byte) 42).times(3)
        .andThrow(new RuntimeException(), 4)
        .andReturn((byte) -42);

呼出し回数のチェックの緩和

呼出し回数のチェックに幅を持たせるために、times(int count) の代わりに使える、以下のメソッドが用意されています。

times(int min, int max)

min と max の間の回数呼出しが行われることを期待します。

atLeastOnce()

少なくとも一回呼出しが行われることを期待します。

anyTimes()

任意の回数呼出しが行われることを期待します。

呼出し回数が指定されていない場合は、1回呼出しが行われることが期待されます。 もしこのことを明示的に宣言したい場合は、 once()またはtimes(1)を使用できます。

厳密なモック

EasyMock.createMock()から返されるモックオブジェクトは、 メソッドの呼出し順序をチェックしません。 メソッドの呼出し順序をチェックする厳密なモックオブジェクトを作りたいときは、 EasyMock.createStrictMock()を使用してください。

厳密なモックオブジェクトに対して期待しないメソッドが呼び出された場合、 例外メッセージとしてその時点で期待されていたメソッド呼出しに続き、 最初に期待に反した実際のメソッド呼出しが表示されます。 verify(mock)は全てのまだ実行されていない期待されるメソッド呼出しを 表示します。

呼出し順序チェックの有効化と無効化

一部のメソッド呼出しだけ呼出し順序のチェックを有効にしたモックオブジェクトを作成する 必要があることがあります。記録フェーズでcheckOrder(mock, true)を呼び出すことによって、 呼出し順序チェックを有効化し、checkOrder(mock, false)を呼び出すことで無効化 することができます。

厳密なモックオブジェクトと普通のモックオブジェクトの間には2つの違いがあります。

1. 厳密なモックオブジェクトは、作成後に呼出し順序チェックが有効化される。
2. 厳密なモックオブジェクトは、リセット後に呼出し順序チェックが有効化される(モックオブジェクトの再利用を参照)。

Argument Matcher を使用した柔軟な期待値の設定。

実際のメソッド呼出しを期待されるメソッド呼出しと照合するとき、参照型の 引数はデフォルトではequals()メソッドを使用して比較されます。 このことが問題になることがあります。 例えば、以下のような期待について考えてみましょう。

String[] documents = new String[] { "Document 1", "Document 2" };
expect(mock.voteForRemovals(documents)).andReturn(42);

もしメソッドが同じ内容を持つ別の配列を引数として呼び出されたら、 equals()メソッドは二つの配列をオブジェクトIDによって 比較するので、例外が発生してしまいます。

java.lang.AssertionError: 
  Unexpected method call voteForRemovals([Ljava.lang.String;@9a029e):
    voteForRemovals([Ljava.lang.String;@2db19d): expected: 1, actual: 0
    documentRemoved("Document 1"): expected: 1, actual: 0
    documentRemoved("Document 2"): expected: 1, actual: 0
	at org.easymock.internal.MockInvocationHandler.invoke(MockInvocationHandler.java:29)
	at org.easymock.internal.ObjectMethodsFilter.invoke(ObjectMethodsFilter.java:44)
	at $Proxy0.voteForRemovals(Unknown Source)
	at org.easymock.samples.ClassUnderTest.listenersAllowRemovals(ClassUnderTest.java:88)
	at org.easymock.samples.ClassUnderTest.removeDocuments(ClassUnderTest.java:48)
	at org.easymock.samples.ExampleTest.testVoteForRemovals(ExampleTest.java:83)
    ...

この呼出しに対しては配列の等価性のみが必要であることを指定するために、 EasyMockクラスから静的インポートされたaryEqメソッドが 使用できます。

String[] documents = new String[] { "Document 1", "Document 2" };
expect(mock.voteForRemovals(aryEq(documents))).andReturn(42);

(訳注:aryEqメソッドを呼び出すことによってその引数に対してArgument Matcherが設定されます) もし、メソッド呼出しのなかで Argument Matcher を使用したいなら、全ての引数に対して matcherを指定しなければなりません。

一連の前もって定義された Argument Matcherが利用できます。

eq(X value)

期待される値と実際の値が等しい時にマッチします。 全てのプリミティブ型とオブジェクトに対して利用できます。

anyBoolean(), anyByte(), anyChar(), anyDouble(), anyFloat(), anyInt(), anyLong(), anyObject(), anyShort()

任意の値にマッチします。すべてのプリミティブ型とオブジェクトに対して利用できます。

eq(X value, X delta)

指定された差分の範囲内で、実際の値が指定された値に等しいときマッチします。 float と doubleに対して利用できます。

aryEq(X value)

Arrays.equals()を使用し、指定された値が実際の値と等しいかどうか判定します。プリミティブ型とオブジェクトの配列に対して利用できます。

isNull()

実際の値がnullのときマッチします。オブジェクトに対して使用できます。

notNull()

実際の値がnullでないときマッチします。オブジェクトに対して使用できます。

same(X value)

指定されたオブジェクトが実際のオブジェクトと同じときマッチします。オブジェクトに対して利用できます。

isA(Class clazz)

実際の値が指定されたクラスのインスタンスだった場合、または指定されたクラスを継承または実装していた場合マッチします。 オブジェクトに対して使用できます。

lt(X value), leq(X value), geq(X value), gt(X value)

それぞれ実際の値が指定された値未満/以下/以上/より大きい場合にマッチします。 すべての数字のプリミティブ型に対して利用できます。

startsWith(String prefix), contains(String substring), endsWith(String suffix)

それぞれ、実際の値が、指定された値で始まる/を含む/で終わる場合にマッチします。文字列に対して利用できます。

matches(String regex), find(String regex)

実際の値が指定された正規表現にマッチするときにマッチします。文字列に対して利用できます。

and(X first, X second)

実際の値がfirst と second の両方にマッチするときマッチします。全てのプリミティブ型とオブジェクトに対して利用できます。

or(X first, X second)

実際の値がfirst and secondのいずれかにマッチするときにマッチします。全てのプリミティブ型とオブジェクトに対して利用できます。

not(X value)

実際の値がvalueにマッチしないときにマッチします。

独自のArgument Matcherを定義する。

独自のArgument Matcherを定義したくなるときがあります。 例えば、エラーメッセージと例外の型の両方が等しいときマッチするArgument Matcherが必要だったとしましょう。 それは以下のように使用できるべきです。

    IllegalStateException e = new IllegalStateException("Operation not allowed.")
    expect(mock.logThrowable(eqException(e))).andReturn(true);

これを実現するためには2つのステップが必要です。1つめは新しいArgument Matcherを定義すること、 2つめはスタティクメソッドeqExceptionを宣言することです。

新しいArgument Matcherを定義するには、インタフェースorg.easymock.IArgumentMatcherを実装します。 このインタフェースは2つのメソッドを含みます。matches(Object actual)は実際の引数が指定された 引数にマッチするかどうかチェックします。appendTo(StringBuffer buffer)はArgument Matcherの 文字列表現を与えられたStringBufferに追加します。実装はわかりやすいものです。

import org.easymock.IArgumentMatcher;

public class ThrowableEquals implements IArgumentMatcher {
    private Throwable expected;

    public ThrowableEquals(Throwable expected) {
        this.expected = expected;
    }

    public boolean matches(Object actual) {
        if (!(actual instanceof Throwable)) {
            return false;
        }
        String actualMessage = ((Throwable) actual).getMessage();
        return expected.getClass().equals(actual.getClass())
                && expected.getMessage().equals(actualMessage);
    }

    public void appendTo(StringBuffer buffer) {
        buffer.append("eqException(");
        buffer.append(expected.getClass().getName());
        buffer.append(" with message \"");
        buffer.append(expected.getMessage());
        buffer.append("\"")");

    }
}

eqExceptionメソッドは指定されたThrowableを使ってこのArgument Matcherを生成し、 reportMatcher(IArgumentMatcher matcher)メソッドによってEasyMockにそのArgumentMatcherの ことを伝え、メソッド呼出しの中でこのメソッドを使えるように戻り値を返さなければなりません。 (多くの場合、0, null または falseを返します。) 最初の試作品は次のようになります。

public static Throwable eqException(Throwable in) {
    EasyMock.reportMatcher(new ThrowableEquals(in));
    return null;
}

しかしながら、これはlogThrowableメソッドが、Throwableを引数として受け取る 既に例示された使い方をされて、RuntimeExceptionのようなより特化された 例外が要求されない場合のみうまく動きます。後者の場合、我々のコードサンプルはコンパイルできなく なるでしょう(以下を参照)。

    IllegalStateException e = new IllegalStateException("Operation not allowed.")
    expect(mock.logThrowable(eqException(e))).andReturn(true);

この場合、Java 5.0が助けになります。eqExceptionの引数と戻り値をThrowable として定義する代わりに、Throwableを拡張するジェネリック型を定義するのです。

public static <T extends Throwable> T eqException(T in) {
    reportMatcher(new ThrowableEquals(in));
    return null;
}

モックオブジェクトの再利用

モックオブジェクトはreset(mock)メソッドによってリセットされます。

メソッドのスタブ的振る舞いの使用

モックオブジェクトをあるメソッド呼出しに応答させたいが、何回呼び出されたか、いつ呼び出されたか、それとも 全く呼び出されなかったのかはチェックしたくない場合があります。 このスタブ的振る舞いはandStubReturn(Object value)、メソッドを使用して定義できます。 andStubThrow(Throwable throwable)、 andStubAnswer(IAnswer answer) および asStub()の各メソッドを使用して定義できます。 以下のコードはモックオブジェクトをvoteForRemoval("Document")に対しては42を1回返し、 その他の引数に対しては-1を返すように設定します。

    expect(mock.voteForRemoval("Document")).andReturn(42);
    expect(mock.voteForRemoval(not(eq("Document")))).andStubReturn(-1);

上品なモック

createMock()が返すモックオブジェクトのデフォルトの振る舞いは全てのメソッドが予期しない メソッド呼出しに対してAssertionErrorをスローする、というものです。 もし、全てのメソッド呼出しを許可し、適切な空の値(0、 null または false)を返す 「上品な」モックオブジェクトを好むのであれば、代わりにcreateNiceMock()を使ってください。

Objectのメソッド

Objectの3つのメソッド(equals()、 hashCode() および toString()) の振る舞いは、EasyMockが作ったモックオブジェクトについては たとえそれがMockObjectが実装しているインターフェースの一部だったとしても 変更できません。

複数のモックにまたがったメソッド呼出しのチェック

今まではEasyMockクラスのスタティックメソッドによって設定される単一のモックオブジェクトのみを見てきました。 しかし、実はそれらのスタティックメソッドの多くは、裏でモックオブジェクトを制御する単一のオブジェクトに処理を委譲している のです。この制御オブジェクトはIMocksControlインタフェースを実装したオブジェクトです。

従って、以下のコードの代わりに、

    IMyInterface mock = createStrictMock(IMyInterface.class);
    replay(mock);
    verify(mock); 
    reset(mock);

以下の同等のコードを使用することができます。

    IMocksControl ctrl = createStrictControl();
    IMyInterface mock = ctrl.createMock(IMyInterface.class);
    ctrl.replay();
    ctrl.verify(); 
    ctrl.reset();

IMocksControlによって複数のモックオブジェクトを生成することが可能になり、複数のモックにまたがってメソッド呼出しの順序を チェックすることが可能になります。例えば、IMyInterfaceインタフェースに対して2つのモックオブジェクトをセットアップ するとしましょう。そしてまず、mock1.a()とmock2.a()を順番に、次にmock1.c() とmock2.c()を任意の回数、最後にmock2.b() と mock1.b()を順に実行することを 期待します。この設定を行うコードは以下のようになります。

    IMocksControl ctrl = createStrictControl();
    IMyInterface mock1 = ctrl.createMock(IMyInterface.class);
    IMyInterface mock2 = ctrl.createMock(IMyInterface.class);

    mock1.a();
    mock2.a();

    ctrl.checkOrder(false);

    mock1.c();
    expectLastCall().anyTimes();     
    mock2.c();
    expectLastCall().anyTimes();     

    ctrl.checkOrder(true);

    mock2.b();
    mock1.b();

    ctrl.replay();

後方互換性

EasyMock 2 は互換性レイヤーを含んでいるため、Java1.5用の EasyMock 1.2を使ったテストは 変更なしに動作するでしょう。既知の唯一の違いは、エラーが発生したときに現れます。 エラーメッセージとスタックトレースはすこし変更され、エラーはJUnitのAssertionFailedError の代わりにJavaのAssertionErrorとして報告されるようになりました。

EasyMock2.1 は EasyMock 2.2 では複雑過ぎるということで削除された コールバック機能を含んでます。EasyMock 2.2からはIAnswerインタフェースが コールバック機能を提供しています。

EasyMockの開発

EasyMock 1.0は OFFIS のTammo Freeseによって 開発されました。EasyMockの開発は、他の開発者や企業の貢献を可能にするため、 現在 SourceForgeでホスティングされています。

フィードバックをくださった方々に感謝します。 Nascif Abousalh-Neto, Dave Astels, Francois Beausoleil, George Dinwiddie, Shane Duan, Wolfgang Frech, Steve Freeman, Oren Gross, John D. Heintz, Dale King, Brian Knorr, Dierk Koenig, Chris Kreussling, Robert Leftwich, Patrick Lightbody, Johannes Link, Rex Madden, David McIntosh, Karsten Menne, Stephan Mikaty, Ivan Moore, Ilja Preuss, Justin Sampson, Richard Scott, Joel Shellman, Shaun Smith, Marco Struck, Ralf Stuckert, Victor Szathmary, Henri Tremblay, Bill Uetrecht, Frank Westphal, Chad Woolley, Bernd Worsch, 他、多くの方々。

新しいバージョンについてはEasyMock のホームページを 確認し、バグレポートや提案を EasyMock Yahoo!Group. まで送ってください。EasyMock Yahoo!Groupに参加したいならメッセージを easymock-subscribe@yahoogroups.com まで送ってください。

EasyMock Version 2.2 (2006年4月17日)

2.1からの変更:

• 期待されたメソッド呼出しに対する応答が andAnswer(IAnswer answer) と andStubAnswer(IAnswer answer)に よって実行時に生成できるようになりました。
• callback(Runnable runnable) は削除されました。代わりに、 andAnswer(IAnswer answer) と andStubAnswer(IAnswer answer) を使うようにしてください。
• replay(), verify() および reset() は複数のモックオブジェクトを 引数として受け付けることができるようになりました。

2.0からの変更:

• モックオブジェクトに渡された引数がEasyMock.getCurrentArguments()を通して コールバックから利用できるようになりました。
• http://groups.yahoo.com/group/easymock/message/558で報告されたバグを修正しました。
• 未使用のArgument Matcherが指定された場合、早期に失敗すようになりました。

1.2からの変更:

• 柔軟で、リファクタリングに対して安全なArgument Matcherがサポートされました。
• 単一のモックオブジェクトに対してはモック制御オブジェクトが不要になりました。
• スタブ的振る舞いはデフォルトの振る舞いを置き換えました。
• 一つ以上のモックに対する呼出し順序のチェックと、順序チェックの有効化/無効化がサポートされました。
• コールバックがサポートされました。
• EasyMockは junit.framework.AssertionFailedErrorの代わりにjava.lang.AssertionErrorを スローするようになりました。従って、テスティングフレームワークに依存しなくなり、JUnit 3.8.x, JUnit 4および TestNGが使用できるようになりました。
• 古いAPIを非推奨としました。