Testing with mock objects

You can use any Java mocking framework with ScalaTest, or ScalaMock, a Scala mocking alternative. ScalaTest provides
just enough syntax sugar for the three most popular Java mocking frameworks—JMock, EasyMock, and Mockito—to remove
boilerplate and clarify the client code. But other
than this minor syntax sugar, the libraries are used from Scala as they are in Java. This enables people familiar with
a particular framework to get going quickly and enhances readability for combined Java/Scala projects using a common
mocking framework. ScalaMock, the native Scala mocking framework, has been designed to integrate easily into ScalaTest suites.

Function mocks

Function mocks are created with mockFunction. The following, for example, creates a mock
function taking a single Int argument and returning a String:

val m = mockFunction[Int, String]

You can then set expectations set on the mock function. For example, here's how you'd state that you
expect your mock to be called once with the argument 42, and that when called like that
it should return the string "Forty two":

m expects (42) returning "Forty two" once

Proxy mocks

Proxy mocks can only be used to mock Scala traits and Java interfaces. (To mock classes, singleton/companion
objects etc., please use generated mocks.)
To use proxy mocks, mix org.scalamock.ProxyMockFactory into your test suite.
Proxy mocks are created with mock. The following, for example, creates a mock that implements
all the Turtle trait (interface):

val m = mock[Turtle]

You can then set expectations on each of the methods within those traits. Here's an example:

By default, an expectation accepts any arguments and a single call. The following two statements are equivalent:

m expects 'forward withArgs (*) once
m expects 'forward

As a convenience, proxy mocks also support the stubs method. The following two statements are equivalent:

m expects 'forward anyNumberOfTimes
m stubs 'forward

Generated mocks

Generated mocks rely on the ScalaMock compiler plugin.
Classes that are going to be mocked need to be declared with the org.scalamock.annotation.mock
annotation. To mock a class together with its companion object, use
org.scalamock.annotation.mockWithCompanion. To mock a standalone singleton object, use
org.scalamock.annotation.mockObject.

In addition to MockFactory, your test class also needs to mix in GeneratedMockFactory.

Expectations

You can specify expectations about the arguments with which a function or method is called and
how many times it will be called. In addition, you can instruct a mock to return a particular value or throw
an exception when that expectation is met.

Arguments

To specify expected arguments for a functional mock, use expects. To specify expected
arguments for a proxy mock, use withArgs or withArguments.

If no expected arguments are given, mocks accept any arguments.

To specify arguments that should simply be tested for equality, provide the expected arguments
as a tuple:

m expects ("this", "that")

ScalaMock currently supports two types of generalized matching: wildcards and epsilon
matching.

Wildcards

Wildcard values are specified with an * (asterisk). For example:

m expects ("this", *)

will match any of the following:

m("this", 42)
m("this", 1.0)
m("this", null)

Epsilon matching

Epsilon matching is useful when dealing with floating point values. An epsilon match is
specified with the ~ (tilde) operator:

m expects (~42.0)

will match:

m(42.0)
m(42.0001)
m(41.9999)

but will not match:

m(43.0)
m(42.1)

Repeated parameters

If you're using generated mocks, you need do nothing special to set expectations on methods
that take repeated parameters. If you're using proxy mocks you will need to use
the ** operator. For example, given:

Return value

You can instruct a mock to return a specific value with returns or returning:

m1 returns 42
m2 expects ("this", "that") returning "the other"

If no return value is specified, functional mocks return null.asInstanceOf[R], where R is the
return type (which equates to 0 for Int, 0.0 for Doubleetc.).

If no return value is specified, proxy mocks return null. This works correctly for most return
types, but not for methods returning primitive types (Int, Doubleetc.), where returning
null leads to a NullPointerException. So you will need to explicitly specify a return value
for such methods. (This restriction may be lifted in the future.)

You can return a computed value (or throw a computed exception) with onCall, for example:

If you wish to highlight which statements are setting expectations on the mock (versus
which ones are actually using the mock), you can place them in an expecting
clause, provided by this trait, like this:

Using an expecting clause is optional, because it does nothing but visually indicate
which statements are setting expectations on mocks. (Note: this trait also provides the lastCall
method, which just calls expectLastCall.)

Once you've set expectations on the mock objects, you must invoke replay on
the mocks to indicate you are done setting expectations, and will start using the mock.
After using the mock, you must invoke verify to check to make sure the mock
was used in accordance with the expectations you set on it. Here's how that looks when you
use the EasyMock API directly:

The whenExecuting method will pass the mockCollaborator to
replay, execute the passed function (your code that uses the mock), and
call verify, passing in the mockCollaborator. If you want to
use multiple mocks, you can pass multiple mocks to whenExecuting.

To summarize, here's what a typical test using EasyMockSugar looks like:

An alternative approach is to place your mock objects in a MockObjects holder object referenced
from an implicit val, then use the overloaded variant of whenExecuting that
takes an implicit MockObjects parameter. Here's how that would look:

The expecting method will create a new Expectations object, pass it into
the function you provide, which sets the expectations. After the function returns, the expecting
method will pass the Expectations object to the checking
method of its internal Mockery context.

The expecting method passes an instance of class
org.scalatest.mock.JMockExpectations to the function you pass into
expectations. JMockExpectations extends org.jmock.Expectations and
adds several overloaded withArg methods. These withArg methods simply
invoke corresponding with methods on themselves. Because with is
a keyword in Scala, to invoke these directly you must surround them in back ticks, like this:

oneOf (mockCollaborator).documentAdded(`with`("Document"))

By importing the members of the passed JMockExpectations object, you can
instead call withArg with no back ticks needed:

oneOf (mockCollaborator).documentAdded(withArg("Document"))

Once you've set expectations on the mock objects, when using the JMock API directly, you use the mock, then invoke
assertIsSatisfied on the Mockery context to make sure the mock
was used in accordance with the expectations you set on it. Here's how that looks: