Specifying invocations

Specifying invocations

The trickiest part of the design of stubs and scenario is the definition of invocations, i.e. the mock and the method for which the stub or expectation applies.

##Overview Basically, this specification consists in:

• Specifying the invoked mock, either with when (when the invoked method returns a value) or of (when the method is void)
• Specifying the invoked method
• Defining the arguments that will help Lmock identifying whether an invocation matches this specification or not

So the overall structure of such item is: ...when|of(MOCK).METHOD(ARGUMENTS).

For example:

import static com.vmware.lmock.masquerade.Schemer.*;

  ...
  // No arguments in the invoked method.
  willReturn(true).when(myList).isEmpty();
  // Define a specific value for the argument
  willInvoke(1).of(myList).add("hello world);
  // The same, but any invocation of add will match as long as the argument
  // is not the null string.
  willInvoke(1).of(myList).add(aNonNullOf(String.class));
  ...

From the previous example, you may notice that the possibilities for specifying the expected arguments is pretty large. You may:

• Precisely define the value of every argument (an exact invocation)
• Or remain vague in the specification of arguments (e.g. "any string", "any non null string", etc.), using with clauses.

The main restriction in this framework is that you cannot mix the two types of argument specifications. Either all the arguments are precisely defined (e.g. of(myList).set(0, "hello world")) or all of them are defined using with clauses (e.g. of(myList).set(with(0), anyOf(String.class)).

##"With" clauses

Such a clause allows to define a range of potential matching arguments. It can be:

• aNonNullOf(class): any object of a specified class (or interface), except null
• anyOf(class): any object of the specified class (or interface), or null
• with(value): an object exactly equal to the specified value
• with(checker): an object validated by a built-in checker

##Checkers

A checker is the equivalent of a Matcher in Jmock, it allows you to plug your own tests to validate an argument to an invocation.

To design your own checker, you must:

• Define the class of objects validated by this checker (getRelatedClass)
• Implement the validation of a value (valueIsCompatibleWith)

Before defining your own checker, you may first check that there is no such implementation in Lmock, by browsing the package com.vmware.lmock.checker. Right now, Lmock supplies checkers for:

• All the java primitive types (byte, character, double, float, integer, long, short)
• Enumerations
• Strings (including support to regular expressions)
• Threads

Otherwise, you may get inspiration from the following example to write your own one.

import com.vmware.lmock.checker.Checker;
...
public class MyTest {
  // This checker verifies that a user object (defined by a first and a last name)
  // matches an expected first and last name.
  class UserChecker implements Checker<User> {
    private final String firstName, lastName;

    UserChecker(String firstName, String lastName) {
      this.firstName = firstName;
      this.lastName = lastName;
    }

    // Matches if and only if the first and the last name match.
    public boolean valueIsCompatibleWith(User value) {
      return firstName.equals(value.firstName()) && lastName.equals(value.lastName());
    }
    public Class<?> getRelatedClass() {
      return User.class;
    }
  }
  ...
  public void test() {
    begin();
    willInvoke(1).of(userDao).persist(with(new UserChecker("john", "doe")));
    ...
    end();
  }
  ...
}