Testing JPA code with Mockito answers

Introduction

In JPA when we want to insert an entity in the database we use the EntityManager.persist(..) method. In addition to saving the entity the persist method will also assign a value to the field of the entity annotated with the @Id annotation (according to the configured @GenerationType). This behaviour is convenient but can be a bit tricky to test. To illustrate this lets use the following example.

Defining the problem

Lets say that we have a simple entity that represents a payment:

@Entity
public class Payment {
  @Id
  private Integer id;
  private BigDecimal amount;
  // getters and setters omitted
}

and that we want to test the method that inserts a new payment in to the database:

pubic class PaymentRepository {

  @PersistentContext
  EntityManager entityManager;

  @Inject
  EventRegistry eventRegistry;

  public void savePayment(Payment payment) {
    Preconditions.checkArgument(payment.getId() == null,
      "Must be a new payment");
    entityManager.persist(payment);
    eventRegistry.register(
      new SuccessfulPaymentEvent(payment.getId()));
  }
}

The above method checks if the payment is new, then saves the payment and then raises an appropriate event (SuccessfulPaymentEvent). For this method we would probably want to create two test cases. One when we try to create a payment that already exists and one for the case where the payment is successfully saved.

The first test case is trivial to implement:

@Test(expected=IllegalArgumentException.class)
public void failure_when_payment_exists() {
  PaymentRepository paymentRepo = new PaymentRepository();
  Payment payment = new Payment();
  payment.setId(10);

  paymentRepo.savePayment(payment);
}

In the second test case one of the things we want to verify is that the SuccessfulPaymentEvent is created with the correct payment id. To do so we have to assert that it is not null and also make sure it is the same as the id of the saved payment. This is not straightforward to implement because of the precondition check at the first line of the method. If we didn’t have the precondition then we could implement this using a Mockito ArgumentCaptor and pass a Payment with the id field already set to the savePayment(..) method. To illustrate the problem lets write a failing test and get an idea of what we are trying to achieve.

@Test
public void register_event_when_the_payment_is_successfully_saved() {
  PaymentRepository paymentRepo = new PaymentRepository();
  paymentRepo.entityManager = Mockito.mock(EntityManager.class);
  paymentRepo.eventRegistry = Mockito.mock(EventRegistry.class);
  ArgumentCaptor<SuccessfulPaymentEvent> argument =
    ArgumentCaptor.forClass(SuccessfulPaymentEvent.class);

  Payment payment = new Payment();
  paymentRepo.savePayment(payment);

  Mockito.verify(paymentRepo.entityManager).persist(payment);
  Mockito.verify(paymentRepo.eventRegistry).register(argument.capture());

  Integer paymentId = argument.getValue().getPaymentId();
  Assert.assertNotNull(paymentId); // Fails here!
  Assert.assertEquals(payment.getId(), paymentId);
}

The above test will fail because the paymentId is null in the first assertion of the test. To overcome this obstacle what we have to do is find a way to inject a known id value to the payment object when we pass it to the persist method of EntityManager. We can do this by using another Mockito feature called Answer.

A solution using Mockito

An Answer can be used to specify the action that is executed and the return value that is returned when you interact with a Mockito mock. So for our problem all we have to do is create an Answer that extracts the payment object from arguments of the mock invocation and sets its id to a known value. Then we can use this known value to assert the id of the captured SuccessfulPaymentEvent.

import org.mockito.stubbing.Answer;
import org.mockito.invocation.InvocationOnMock;

public class PaymentIdSetter extends Answer<Void> {

  private Integer paymentId;

  public PaymentIdSetter(Integer paymentId) {
    this.paymentId = paymentId;
  }

  @Override
  public Void answer(InvocationOnMock invocation) throws Throwable {
    Assert.assertEquals(1, invocation.getArguments().length);
    Payment payment = (Payment) invocation.getArguments()[0];
    payment.setId(paymentId);
    return null;
  }
}

Below we change our test case to use the PaymentIdSetter answer.

@Test
public void register_event_when_the_payment_is_successfully_saved() {
  Integer expectedId = 15;
  PaymentRepository paymentRepo = new PaymentRepository();

  paymentRepo.entityManager = Mockito.mock(EntityManager.class);
  Mockito.doAnswer(new PaymentIdSetter(expectedId))
    .when(paymentRepo.entityManager.persist(Matchers.any(Payment.class)));

  paymentRepo.eventRegistry = Mockito.mock(EventRegistry.class);
  ArgumentCaptor<SuccessfulPaymentEvent> argument =
    ArgumentCaptor.forClass(SuccessfulPaymentEvent.class);

  Payment payment = new Payment();
  paymentRepo.savePayment(payment);

  Mockito.verify(paymentRepo.entityManager).persist(payment);
  Mockito.verify(paymentRepo.eventRegistry).register(argument.capture());

  Integer paymentId = argument.getValue().getPaymentId();
  Assert.assertNotNull(paymentId);
  Assert.assertEquals(expectedId, paymentId);
}

Generalizing PaymentIdSetter

The test case required a bit more setup that is usual but it is able to verify the desired expectation. To improve this further we can easily change the PaymentIdSetter to support all the entity classes of our project either by using reflection to set the id value of the entities or by using a common parent interface (or abstract class) with a setId(..) method for our entity classes.

A possible implementation of the common parent interface option is the following:

public interface IdentifiableEntity {
  Integer getId();
  void setId(Integer id);
}
@Entity
public class Payment implements IdentifiableEntity {
  @Id
  private Integer id;
  private BigDecimal amount;

  public void setId(Integer id) {
    this.id = id;
  }

  // other getters and setters omitted
}
public class EntityIdSetter extends Answer<Void> {

  private Integer id;

  public EntityIdSetter(Integer id) {
    this.id = id;
  }

  @Override
  public Void answer(InvocationOnMock invocation) throws Throwable {
    Assert.assertEquals(1, invocation.getArguments().length);
    IdentifiableEntity entity = (IdentifiableEntity) invocation.getArguments()[0];
    entity.setId(id);
    return null;
  }
}

Conclusion

In this post we have seen how using a custom Mockito Answer enables us to effectively test code that invokes the EntityManager.persist(..) method. Of course this mechanism is not only applicable to JPA’s persist method and applies to testing code that calls methods that modify their parameters. JPA just provided us a nice example to explore this technique.

Action composition in Play Framework

In Play Framework controllers consist of methods that create Action objects to handle the incoming requests. For example in the HelloController below the helloWorld and hello methods create actions that return a “hello” message to the client. In this case, the action objects are constructed using the apply factory method of the Action singleton object.

import play.api.mvc.{Controller, Action}

object HelloController extends Controller {

  def helloWorld = Action {
    Ok("Hello World")
  }

  def hello(name: String) = Action {
    Ok(s"Hello $name")
  }
}

Why we need action composition

Let’s suppose that we want to extend the above actions by adding some logging to assist us when debugging. One way to do this is by adding the log statements in each action definition.

import play.api.Logger
import play.api.mvc._

object HelloController extends Controller {

  def helloWorld = Action { request =>
    Logger.debug(s"HTTP request: ${request.method} ${request.uri}")
    Ok("Hello World")
  }

  def hello(name: String) = Action { request =>
    Logger.debug(s"HTTP request: ${request.method} ${request.uri}")
    Ok(s"Hello $name")
  }
}

As you can see from the above code this is a naive approach to implement such feature since it introduces code duplication. Things like logging that are not related to the main concern of a component and are usually scattered in multiple components are very common in programming and are called cross-cutting concerns. In Play Framework one way to separate cross-cutting concerns from the code of actions is using action composition (the other way is filters but we will not cover them in this article).

To extract logging from the helloWorld and hello methods using action composition what we have to do is create another action that does the logging (the cross-cutting concern) and can be composed with other actions that implement the main concern (in our example the actions of helloWorld and hello) returning a new action that contains the logic for the cross-cutting and the main concern. This way the logic for logging is in one place and can easily change.

In Play Framework Actions are usually created using factory objects that implement the ActionFunction trait. The PlayFramework API contains various traits that extend ActionFunction and allow us to customize the created actions in different ways. Those traits are ActionBuilder, ActionFilter, ActionRefiner and ActionTransformer. From those the most generic and the most helpful is ActionBuilder (in fact the Action singleton object, which is the default ActionFunction is an ActionBuilder).

Because the action of the cross-cutting concern must return another action we can think of it like an action factory and implement it using an appropriate ActionFunction provided by the Play Framework. Here we will use the ActionBuilder to implement it.

The ActionBuilder

ActionBuilder is usually our default choice because it provides several factory methods that make action definition easier. To implement ActionBuilder all we have to do is implement the invokeBlock method. This method takes the current request and a block of code as arguments and will get invoked when the Action returned from the ActionBuilder executes.

For example the code Action { Ok } is a call to apply(block: => Result) method of ActionBuilder that passes the { Ok } block of code as an argument and returns an Action[AnyContent]. When this Action executes it will invoke the invokeBlock method of the ActionBuilder with the current request and the { Ok } block as arguments.

With the above information we can implement the LoggedAction as follows:

import scala.concurrent.Future
import play.api.Logger
import play.api.mvc._

object LoggedAction extends ActionBuilder[Request] {

  def invokeBlock[A](
      request: Request[A],
      block: Request[A] => Future[Result]): Future[Result] = {
    Logger.debug(s"HTTP request: ${request.method} ${request.uri}")
    block(request)
  }
}

and then use it in our controller in the same way that we use the play.api.mvc.Action singleton object since they are both ActionBuilder implementations.

object HelloController extends Controller {

  def helloWorld = LoggedAction {
    Ok("Hello World")
  }

  def hello(name: String) = LoggedAction {
    Ok(s"Hello $name")
  }
}

Extending the Request object

When we implemented the LoggedAction all we had to do is add the logging statement before the invocation of the action’s code block. There are cases when this is not enough and we also want add custom information to the request before we pass it to the code block of the action. An example where we would like to do this is user authentication. In user authentication we usually want to verify that the user making the request is an authenticated user and if this is the case add a user-like object to the request so that we don’t have to load the user again in the action’s code.

To add custom information to a request Play Framework provides the WrappedRequest class. As its name implies the WrappedRequest[A] class is a Request[A] that wraps another Request[A]. To define a custom request that also holds the currently logged in user we can use the following code:

import play.api.mvc.{Request, WrappedRequest}
import models.User

class AuthenticatedRequest[A](val user: User, val request: Request[A])
  extends WrappedRequest[A](request)

Then we can use ActionBuilder to define an AuthenticatedAction that checks if the user is authenticated and invokes block with an AuthenitcatedRequest that wraps the current request and has the authenticated user. AuthenticatedAction extends ActionBuilder[AuthenticatedRequest] and not ActionBuilder[Request] because we want the block to have the type AuthenticatedRequest[A] => Future[Result] so that the user property is accessible when we define actions.

import scala.concurrent.Future
import play.api.mvc._
import models.User

object AuthenticatedAction extends ActionBuilder[AuthenticatedRequest] {

  def invokeBlock[A](
      request: Request[A],
      block: AuthenticatedRequest[A] => Future[Result]): Future[Result] = {
    request.session.get("username")
      .flatMap(User.findByUsername(_))
      .map(user => block(new AuthenticatedRequest(user, request)))
      .getOrElse(Future.successful(Results.Forbidden))
  }
}

We can easily use our AuthenticatedAction in our controllers since it is an ActionBuilder. The request parameter of the code block is of type AuthenticatedRequest and so the code of the action can access the user property.

object HelloController extends Controller {

  def helloUser = AuthenticatedAction { request =>
    Ok(s"Hello ${request.user.firstName}")
  }
}

The ActionRefiner

Because changing the incoming request (to add custom information or to modify it in any way) is very common Play Framework provides three ActionFunction extensions to do it more easily. The main ActionFunction to do this is ActionRefiner and the other two are ActionTransformer and ActionFilter.

An ActionRefiner[R, P] will either return immediately a result of type R or call its action block with a request of type P. To implement an action refiner all we have to do is implement its refine method. For example we can implement AuthenitcatedAction with an ActionRefiner as follows:

object AuthenticatedAction
  extends ActionBuilder[AuthenticatedRequest]
  with ActionRefiner[Request, AuthenticatedRequest] {

  def refine[T](request: Request[T]): Future[Either[Result, AuthenticatedRequest[T]]] = {
    val result = request.session.get("username")
      .flatMap(User.findByUsername(_))
      .map(user => new AuthenticatedRequest[T](user, request))
      .toRight(left = Results.Forbidden)
    Future.successful(result)
  }
}

The refine method returns the result Forbidden in the case where the user is not authenticated or in the case where the user is authenticated it transforms the incoming request to an AuthenticatedRequest. The transformed request will be passed as an argument in the action’s code block.

In the above code example you probably see something that seems odd. The AuthenticatedAction extends both ActionBuilder and ActionRefiner. This is because ActionRefiner does not provide any convenient factory methods to create actions. We can create actions using a plain ActionRefiner but it requires some boilerplate code. ActionRefiner provides us with a useful workflow (to wrap the incoming request under some conditions) and an extension point (the refine method) to lets us specify the specifics. On the other hand ActionBuilder provides no workflow but gives us a handful of useful methods to define actions. The two can be mixed as in the above example so we end up writing less code.

The ActionTransformer

ActionTransformer is an extension to ActionRefiner that always transforms the incoming request. To implement a transformer we implement its transform method returning the transformed request that will be passed in the action’s code block.

An example of an ActionTransformer might be in a chat system where we want for each request to find a chat room and if one does not exist then create it.

object ChatAction
  extends ActionBuilder[ChatRequest]
  with ActionTransformer[Request, ChatRequest] {

  def transform[A](request: Request[A]): Future[ChatRequest[A]] = {
    Future.successful(new ChatRequest(getOrCreateChatRoom(), request))
  }

  private def getOrCreateChatRoom(): ChatRoom = ???
}

The ActionFilter

ActionFilter is the other extension of ActionRefiner and allows us to filter certain requests preventing the action from being executed. To do this we have to implement the filter method and return a Some[Result].

For example if we wanted to check and make sure that the request is using SSL before calling the action to handle the request we could do it with an action filter as follows:

object CheckSSLAction
  extends ActionBuilder[Request]
  with ActionFilter[Request] {

  def filter[A](request: Request[A]): Future[Option[Result]] = {
    val result = request.headers.get("X-Forwarded-Proto") match {
      case Some(proto) if proto == "https" => None
      case _ => Some(Results.Forbidden)
    }
    Future.successful(result)
  }
}

The andThen combinator

So far we have seen how easy it is to define various ActionFunctions that separate cross-cutting concerns from the code of controller actions. But what if we have requirements to support multiple cross-cutting concerns in a single action. For example what if an action needs to execute only when the request is over SSL and when the user is authenticated. Is there a way to combine the action functions that we have already created instead of defining a new one?

Fortunately the ActionFunction trait has a very useful method called andThen that allows us to combine two ActionFunction. To implement the above example we can use the following code:

object Actions {
  val SSLAndAuthAction = CheckSSLAction andThen AuthenticatedAction
}

Summary

  • Use ActionBuilder when you want to add before/after logic in your actions.
  • Use ActionRefiner when you want to add custom information to a request under some conditions.
  • Use ActionTransformer when you want to always add custom information to a request.
  • Use ActionFilter when you want to filter requests under some condition and immediately return a result.
  • Always mix ActionRefiner, ActionTransformer and ActionFilter to ActionBuilder so you can use factory methods to easily construct your actions.
  • Use the andThen combinator to compose multiple ActionFunctions together.

A Scala implementation of Circuit Breaker

In this post I’ll describe how to use sse-breaker, a small library that implements the Circuit Breaker stability design pattern in Scala.

Before mentioning any sse-breaker specifics lets quickly define what is a Circuit Breaker. A Circuit Breaker is a software component that keeps track of the error rate of various operations and when the rate is high it prevents those operation from executing by failing-fast.

In sse-breaker the Circuit Breaker is implemented as an executor. To use it you create a CircuitExecutor instance and call its apply[T](op: =>T):T method passing the code that you would like to execute in the closure. Depending on the Circuit Breaker’s state (if errors have occurred recently) the executor will execute the requested operation or it will throw an OpenCircuitException.

For example lets say that we are developing a web application that uses the Twitter API. Obviously we wouldn’t want any capacity problems at Twitter (or any other site) to prevent our pages from rendering fast. To protect our application we could wrap any calls to the Twitter API with a Circuit Breaker.

To do this in sse-breaker we could use the following code:

class TwitterGateway(twitter: Twitter) {

  private val failfast = new CircuitExecutor("twitter-breaker")

  def getTimeline: List[Status] = failfast {
    twitter.getFriendsTimeline
  }

  def search(q: Query): QueryResult = failfast {
    twitter.search(q)
  }
}

In the above code we’ve created a CircuitExecutor, named twitter-breaker, with the default configuration and wrapped the calls to the Twitter API. By default if five exceptions are thrown within a minute the Circuit Breaker will go into the open state and further requests to execute any operation, for the next 10 minutes, will throw an OpenCircuitException instead of executing the operation.

For more information see the homepage of sse-breaker.

Catching Throwable in Scala

Because of Scala‘s pattern matching syntax it is really convenient to catch Throwable instead of Exception or any other exception type. Instead of writing:

try {
  iMayHaveIllegalState.doSomething()
} catch {
  case e: IllegalStateException => e.printStackTrace()
}

we can simply write:

try {
  iMayHaveIllegalState.doSomething()
} catch {
  case e => e.printStackTrace()
}

You might be tempted to use the above code in your programs since it is shorter but if catching Throwable in Java is evil then catching Throwable in Scala is ten times more evil.

To illustrate this we will use a small example. Lets say that we want to write a method that takes a sequence of strings and tries to find if it contains a string that represents an even number. Furthermore if any of the strings cannot get converted into an integer then we assume that the input is invalid and return false.

A possible implementation is the following:

def containsEven(nums: String*): Boolean = {
  try {
    for (i <- nums) {
      if (i.toInt % 2 == 0)
        return true
    }
  } catch { case e => () }
  false
}

From the above implementation we would expect that containsEven("1", "3") should return false and that containsEven("2", "3") should return true. Unfortunately this is not the case and regardless of the input our method always returns false. This is because in the catch block we used a pattern that catches Throwable with the expression case e => ... instead of the longer but more correct pattern case e: NumberFormatException => ... that only catches NumberFormatException. To understand why this is the cause of the bug we need to understand how Scala implements non-local return from closures.

The for loop in the above code is actually a method call to the the foreach method of the nums object (that is an instance of scala.Seq) passing the body of the for loop as a closure in the foreach method. The code inside the for loop is actually the apply(..) method of the closure (a scala.Function1 in our case). Since that code belongs in another method normally a return statement present in that code would signal the return of that method.

This is not the case for Scala’s closures and when a return statement is present in a closure, the closure instead of returning at the point of invocation it also triggers the return of the enclosing method. This behavior is called non-local return and it is essential for creating control-flow abstractions using closures.

Because the JVM does not have native support for non-local return Scala implements it by throwing a Throwable. When a closure contains a return statement then that closure when executed instead of returning normally it throws a Throwable of type scala.runtime.NonLocalReturnControl that contains the returned value of the closure. The NonLocalReturnControl is then caught at the enclosing method and closure’s returned value is returned from the enclosing method. This is why when we try to define a closure that contains a return statement outside of a method the compiler will complain with an error because it cannot find where to generate the catch block for the NonLocalReturnControl thrown from the closure.

With the knowledge of how non-local return is implemented in Scala, we can now see that in the containsEven method the NonLocalReturnControl that gets thrown from the return true statement in the for loop gets caught by our case e => () pattern and gets ignored. So regardless of the input containsEven will always return false. To fix this we must simply catch NumberFormatException and not Throwable.

def containsEven(nums: String*): Boolean = {
  try {
    for (i <- nums) {
      if (i.toInt % 2 == 0)
        return true
    }
  } catch { case e: NumberFormatException => () }
  false
}

Catching Throwable can be a source of frequent bugs because even with the knowledge of how non-local return is implemented it is very likely that you will miss a closure with non-local return and introduce a bug. Furthermore Scala implements and other control structures by throwing Throwable like break and continuations making it even harder.

In the rare case when you absolutely need to catch Throwable the correct way to do it is the following:

import scala.util.control.ControlThrowable

try {
  codeThatMayThrowThrowable()
} catch {
  case e: ControlThrowable => throw e
  case e => handleThrowable(e)
}

In the above code we re-throw a Throwable if it is used for control-flow and handle all others. The scala.util.control.ControlThrowable is the Throwable that is extended by all throwables that are used for control flow in Scala.

Don’t use vars inside singleton objects

Scala enables immutability and functional programming but it does not dictate it. As easy it is to create immutable state via a val it is equally easy to create mutable state via a var. IMHO this is a good thing since the programmer is free to choose the programming style to use according to the problem at hand.

One of Scala’s unique features is singleton objects. Singleton objects are an implementation of the Singleton design pattern inside the language and they allow Scala to abandon static methods and provide a more uniform view of the world where everything is an object.

Singleton objects despite all their benefits they make one bad practice very convenient to do. It is very easy to forget that an object (that is not defined inside a class or trait) is actually a global static and thus a var inside that object is actually global mutable state.

This is not a Scala weakness and I believe it is more a weakness of the programmer to come up with the right design given his unfamiliarity with the Scala constructs. When we start using a new programming language because we are re-evaluating our view of programming certain bad practices that we might never used in our previous language temporarily become more tempting.

One example of global mutable state in a top-level singleton object that I saw recently is in Squeryl. Squeryl is an ORM that has a really slick API and IMHO could become a viable alternative to the major Java ORMs for Scala.

I was reading Squeryl’s documentation and I got really excited about using it in a small project but then I saw the SessionFactory object and my excitement turned into disappointment. Below I have a small fragment from the SessionFactory‘s code:

object SessionFactory {

  var concreteFactory: Option[()=>Session] = None

  var externalTransactionManagementAdapter: Option[()=>Session] = None

  def newSession: Session = {
    /* Code that uses concreteFactory... */
  }
}

As you can see from the above code the SessionFactory has two vars that hold functions that create ORM sessions. I have to say that I am at least uncomfortable with an ORM that relies on global mutable state for that functionality.

Lets try to enumerate some of the disadvantages of Squeryl’s current design:

  1. Since the concreteFactory and externalTransactionManagementAdapter can be changed from anywhere in the program it is difficult to reason about our code.
  2. The API of SessionFactory is not thread-safe. For example if a thread changes concreteFactory then another thread reading that variable does not have a guarantee that will see the latest version.
  3. Since the configuration for creating a Session is in a static variable this means that we cannot have a multi-threaded application that uses two different configurations.
  4. As a consequence of the above we cannot deploy Squeryl as an OSGi bundle and use it from multiple applications.
  5. Since we depend on global state, our code is more difficult to test because we need to reset that state after every test.
  6. Furthermore we cannot run our tests in parallel.

Lots of bad stuff for two innocent vars…

Update: Maxime Lévesque, the author of Squeryl, wrote in a comment that Squeryl also provides a mechanism for working with sessions that does not rely on static state and that the mechanism described in this article is optional and provided for convenience. So my analysis above is not true and would only be valid if Squeryl didn’t provide an alternative mechanism.

In conclusion:

  • Putting a var inside an object might be convenient but as each instance of global mutable state it can lead to a lot of trouble.
  • Just because you moved to a new programming language doesn’t mean that your old practices are now unnecessary.