class Publisher {

  List<Subscriber> subscribers = []

  int messageCount = 0

  void send(String message){

    subscribers*.receive(message)

    messageCount++

  }

}

interface Subscriber {

  void receive(String message)

}

class PublisherSpec extends Specification {

  Publisher publisher = new Publisher()

}

def subscriber = Mock(Subscriber)

def subscriber2 = Mock(Subscriber)

Subscriber subscriber = Mock()

Subscriber subscriber2 = Mock()

class PublisherSpec extends Specification {

  Publisher publisher = new Publisher()

  Subscriber subscriber = Mock()

  Subscriber subscriber2 = Mock()

  def setup() {

    publisher.subscribers << subscriber // << is a Groovy shorthand for List.add()

    publisher.subscribers << subscriber2

  }

def "should send messages to all subscribers"() {

  when:

  publisher.send("hello")

  then:

  1 * subscriber.receive("hello")

  1 * subscriber2.receive("hello")

}

Let’s take a closer look at the then: block. It contains two interactions, each of which has four distinct parts: a cardinality, a target constraint, a method constraint, and an argument constraint:

The cardinality of an interaction describes how often a method call is expected. It can either be a fixed number or a range:

The target constraint of an interaction describes which mock object is expected to receive the method call:

The method constraint of an interaction describes which method is expected to be called:

When expecting a call to a getter method, Groovy property syntax can be used instead of method syntax:

When expecting a call to a setter method, only method syntax can be used:

The argument constraints of an interaction describe which method arguments are expected:

Argument constraints work as expected for methods with multiple arguments:

When dealing with vararg methods, vararg syntax can also be used in the corresponding interactions:

Sometimes it can be useful to match "anything", in some sense of the word:

Now, when would matching any method call be useful? A good example is strict mocking, a style of mocking where no interactions other than those explicitly declared are allowed:

0 * only makes sense as the last interaction of a then: block or method. Note the use of _ * (any number of calls), which allows any interaction with the auditing component.

So far, we declared all our interactions in a then: block. This often results in a spec that reads naturally. However, it is also permissible to put interactions anywhere before the when: block that is supposed to satisfy them. In particular, this means that interactions can be declared in a setup method. Interactions can also be declared in any "helper" instance method of the same specification class.

When an invocation on a mock object occurs, it is matched against interactions in the interactions' declared order. If an invocation matches multiple interactions, the earliest declared interaction that hasn’t reached its upper invocation limit will win. There is one exception to this rule: Interactions declared in a then: block are matched against before any other interactions. This allows to override interactions declared in, say, a setup method with interactions declared in a then:block.

If a mock has a set of "base" interactions that don’t vary, they can be declared right at mock creation time:

This feature is particularly attractive for Stubbing and with dedicated Stubs. Note that the interactions don’t (and cannot [2]) have a target constraint; it’s clear from the context which mock object they belong to.

Interactions can also be declared when initializing an instance field with a mock:

Interactions sharing the same target can be grouped in a Specification.with block. Similar to Declaring Interactions at Mock Creation Time, this makes it unnecessary to repeat the target constraint:

A with block can also be used for grouping conditions with the same target.

A then: block may contain both interactions and conditions. Although not strictly required, it is customary to declare interactions before conditions:

Read out aloud: "When the publisher sends a 'hello' message, then the subscriber should receive the message exactly once, and the publisher’s message count should be one."

Internally, Spock must have full information about expected interactions before they take place. So how is it possible for interactions to be declared in a then: block? The answer is that under the hood, Spock moves interactions declared in a then: block to immediately before the preceding when: block. In most cases this works out just fine, but sometimes it can lead to problems:

Here we have introduced a variable for the expected argument. (Likewise, we could have introduced a variable for the cardinality.) However, Spock isn’t smart enough (huh?) to tell that the interaction is intrinsically linked to the variable declaration. Hence it will just move the interaction, which will cause a MissingPropertyException at runtime.

One way to solve this problem is to move (at least) the variable declaration to before the when: block. (Fans of Data Driven Testing might move the variable into a where: block.) In our example, this would have the added benefit that we could use the same variable for sending the message.

Another solution is to be explicit about the fact that variable declaration and interaction belong together:

Since an MockingApi.interaction block is always moved in its entirety, the code now works as intended.

Interactions declared in a then: block are scoped to the preceding when: block:

This makes sure that subscriber receives "message1" during execution of the first when: block, and "message2"during execution of the second when: block.

Interactions declared outside a then: block are active from their declaration until the end of the containing feature method.

Interactions are always scoped to a particular feature method. Hence they cannot be declared in a static method,setupSpec method, or cleanupSpec method. Likewise, mock objects should not be stored in static or @Shared fields.

There are two main ways in which a mock-based test can fail: An interaction can match more invocations than allowed, or it can match fewer invocations than required. The former case is detected right when the invocation happens, and causes a TooManyInvocationsError:

To make it easier to diagnose why too many invocations matched, Spock will show all invocations matching the interaction in question (new in Spock 0.7):

According to this output, one of the receive("hello") calls triggered the TooManyInvocationsError. Note that because indistinguishable calls like the two invocations of subscriber.receive("hello") are aggregated into a single line of output, the first receive("hello") may well have occurred before the receive("goodbye").

The second case (fewer invocations than required) can only be detected once execution of the when block has completed. (Until then, further invocations may still occur.) It causes a TooFewInvocationsError:

Note that it doesn’t matter whether the method was not called at all, the same method was called with different arguments, the same method was called on a different mock object, or a different method was called "instead" of this one; in either case, a TooFewInvocationsError error will occur.

To make it easier to diagnose what happened "instead" of a missing invocation, Spock will show all invocations that didn’t match any interaction, ordered by their similarity with the interaction in question (new in Spock 0.7). In particular, invocations that match everything but the interaction’s arguments will be shown first:

Often, the exact method invocation order isn’t relevant and may change over time. To avoid over-specification, Spock defaults to allowing any invocation order, provided that the specified interactions are eventually satisfied:

Here, any of the invocation sequences "hello" "hello" "goodbye", "hello" "goodbye" "hello", and "goodbye""hello" "hello" will satisfy the specified interactions.

In those cases where invocation order matters, you can impose an order by splitting up interactions into multiple then:blocks:

Now Spock will verify that both "hello"'s are received before the "goodbye". In other words, invocation order is enforced between but not within then: blocks.

Besides interfaces, Spock also supports mocking of classes. Mocking classes works just like mocking interfaces; the only additional requirement is to put cglib-nodep-2.2 or higher and objenesis-1.2 or higher on the class path. If either of these libraries is missing from the class path, Spock will gently let you know.

interface Subscriber {

    String receive(String message)

}

subscriber.receive(_) >> "ok"

subscriber.receive(_) >> "ok"

|          |       |     |

|          |       |     response generator

|          |       argument constraint

|          method constraint

target constraint

We have already seen the use of the right-shift (>>) operator to return a fixed value:

To return different values for different invocations, use multiple interactions:

This will return "ok" whenever "message1" is received, and "fail" whenever "message2" is received. There is no limit as to which values can be returned, provided they are compatible with the method’s declared return type.

To return different values on successive invocations, use the triple-right-shift (>>>) operator:

This will return "ok" for the first invocation, "error" for the second and third invocation, and "ok" for all remaining invocations. The right-hand side must be a value that Groovy knows how to iterate over; in this example, we’ve used a plain list.

To compute a return value based on the method’s argument, use the the right-shift (>>) operator together with a closure. If the closure declares a single untyped parameter, it gets passed the method’s argument list:

Here "ok" gets returned if the message is more than three characters long, and "fail" otherwise.

In most cases it would be more convenient to have direct access to the method’s arguments. If the closure declares more than one parameter or a single typed parameter, method arguments will be mapped one-by-one to closure parameters:[3]

This response generator behaves the same as the previous one, but is arguably more readable.

If you find yourself in need of more information about a method invocation than its arguments, have a look atorg.spockframework.mock.IMockInvocation. All methods declared in this interface are available inside the closure, without a need to prefix them. (In Groovy terminology, the closure delegates to an instance of IMockInvocation.)

Sometimes you may want to do more than just computing a return value. A typical example is throwing an exception. Again, closures come to the rescue:

Of course, the closure can contain more code, for example a println statement. It will get executed every time an incoming invocation matches the interaction.

Method responses can be chained:

This will return "ok", "fail", "ok" for the first three invocations, throw InternalError for the fourth invocations, and return ok for any further invocation.

1 * subscriber.receive("message1") >> "ok"

1 * subscriber.receive("message2") >> "fail"

setup:

subscriber.receive("message1") >> "ok"

when:

publisher.send("message1")

then:

1 * subscriber.receive("message1")

A stub is created with the MockingApi.Stub factory method:

Whereas a mock can be used both for stubbing and mocking, a stub can only be used for stubbing. Limiting a collaborator to a stub communicates its role to the readers of the specification.

Like a mock, a stub allows unexpected invocations. However, the values returned by a stub in such cases are more ambitious:

• For primitive types, the primitive type’s default value is returned.

• For non-primitive numerical values (such as BigDecimal), zero is returned.

• For non-numerical values, an "empty" or "dummy" object is returned. This could mean an empty String, an empty collection, an object constructed from its default constructor, or another stub returning default values. See class org.spockframework.mock.EmptyOrDummyResponse for the details.

A stub often has a fixed set of interactions, which makes declaring interactions at mock creation time particularly attractive:

(Think twice before using this feature. It might be better to change the design of the code under specification.)

A spy is created with the MockingApi.Spy factory method:

A spy is always based on a real object. Hence you must provide a class type rather than an interface type, along with any constructor arguments for the type. If no constructor arguments are provided, the type’s default constructor will be used.

You may also create a spy from an instantiated object. This may be useful in cases where you do not have full control over the instatiation of types you are interested in spying. (For example when testing within a Dependency Injection framework such as Spring or Guice.)

Method calls on a spy are automatically delegated to the real object. Likewise, values returned from the real object’s methods are passed back to the caller via the spy.

After creating a spy, you can listen in on the conversation between the caller and the real object underlying the spy:

Apart from making sure that receive gets called exactly once, the conversation between the publisher and the SubscriberImpl instance underlying the spy remains unaltered.

When stubbing a method on a spy, the real method no longer gets called:

Instead of calling SubscriberImpl.receive, the receive method will now simply return "ok".

Sometimes, it is desirable to both execute some code and delegate to the real method:

Here we use callRealMethod() to delegate the method invocation to the real object. Note that we don’t have to pass the message argument along; this is taken care of automatically. callRealMethod() returns the real invocation’s result, but in this example we opted to return our own result instead. If we had wanted to pass a different message to the real method, we could have used callRealMethodWithArgs("changed message").

(Think twice before using this feature. It might be better to change the design of the code under specification.)

Spies can also be used as partial mocks:

All Groovy mocks implement the GroovyObject interface. They support the mocking and stubbing of dynamic methods as if they were physically declared methods:

(Think twice before using this feature. It might be better to change the design of the code under specification.)

Usually, Groovy mocks need to be injected into the code under specification just like regular mocks. However, when a Groovy mock is created as global, it automagically replaces all real instances of the mocked type for the duration of the feature method:[4]

Here, we set up the publisher with two instances of a real subscriber implementation. Then we create a global mock of the same type. This reroutes all method calls on the real subscribers to the mock object. The mock object’s instance isn’t ever passed to the publisher; it is only used to describe the interaction.

Since global mocks have a somewhat, well, global effect, it’s often convenient to use them together with GroovySpy. This leads to the real code getting executed unless an interaction matches, allowing you to selectively listen in on objects and change their behavior just where needed.

(Think twice before using this feature. It might be better to change the design of the code under specification.)

Global mocks support mocking of constructors:

Since we are using a spy, the object returned from the constructor call remains unchanged. To change which object gets constructed, we can stub the constructor:

Now, whenever some code tries to construct a subscriber named Fred, we’ll construct a subscriber named Barney instead.

(Think twice before using this feature. It might be better to change the design of the code under specification.)

Global mocks support mocking and stubbing of static methods:

The same works for dynamic static methods.

When a global mock is used solely for mocking constructors and static methods, the mock’s instance isn’t really needed. In such a case one can just write:

At the end of the day, the Mock(), Stub(), and Spy() factory methods are just canned ways to create mock objects with a certain configuration. If you want more fine-grained control over a mock’s configuration, have a look at the org.spockframework.mock.IMockConfiguration interface. All properties of this interface [5] can be passed as named arguments to the Mock() method. For example:

Here, we create a mock whose default return values match those of a Mock(), but whose invocations aren’t verified (as for a Stub()). Instead of passing ZeroOrNullResponse, we could have supplied our own customorg.spockframework.mock.IDefaultResponse for responding to unexpected method invocations.

To find out whether a particular object is a Spock mock object, use a org.spockframework.mock.MockDetector:

A detector can also be used to get more information about a mock object: