Testing your RESTful services with Groovy, Spock and HTTPBuilder

I like to test the HTTP portion of the RESTful web services I build in isolation. This is because, in the languages I use (Java, Scala), most of the code responsible for taking in HTTP requests and parsing them is very framework specific and simply delegates the actual logic to another part of my application. Ideally I can launch this part of my application in the same way as it is launched in production but with the rest of the application stubbed out.

Recently I've been using Groovy/Spock for these integration tests, here's how for a really simple web service. In this example it's been built with Spring Boot.

	@Controller
	public class ExampleWebAppController {
	@RequestMapping("/exampleendpoint")
	public @ResponseBody Payload exampleEndpoint(@RequestParam(value="input") String input) {
	return new Payload("Something really important: " + input);
	}
	}

view raw ExampleWebAppController.java hosted with ❤ by GitHub

Let's not go into the details of how Spring boot work but it is essentially the same application as in Spring's guide.

The web application has a single path: /exampleendpoint which takes in a single query param: input and returns a JSON object with a single field payload with the value: Something really important: with the input appended.

I want to test that the web service takes in HTTP, takes the query parameter out and builds the JSON correctly. With Groovy/Spock/HTTPBuilder here's how it looks:

	class ExampleWebAppSpecification extends Specification {
	def "Should return 200 & a message with the input appended"() {
	setup:
	def primerEndpoint = new RESTClient( 'http://localhost:8080/' )
	when:
	def resp = primerEndpoint.get([ path: 'exampleendpoint', query : [ input : 'Get a hair cut' ]])
	then:
	with(resp) {
	status == 200
	contentType == "application/json"
	}
	with(resp.data) {
	payload == "Something really important: Get a hair cut"
	}
	}
	}

view raw ExampleWebAppSpecification.groovy hosted with ❤ by GitHub

Let's look at what is going on here:

• In the setup phase we create a RESTClient
• In the exercising phase we make a call out to the web application.
• In the verification phase we check that the response code is 200, the content type is "application/json" and the body is JSON with a single payload field that contains "Something really important: Get a hair cut"

Benefits over writing this in Groovy/Spock over say just using Java/JUnit:

• The HTTP libraries are easier to use with less code
• The assertions are more expressive
• More magic, for instance the second with() block works on a Groovy map that has automagically created

The above example doesn't deal with how to start and stop the web service under test, I left that out as it is very web framework specific. 

What do you need in your build to get this setup? I used Gradle for this example so it is probably easier to just check out the build.gradle, a lot of it can be ignored as it is related to Spring Boot rather than Spock. Here are the important bits:

The plugins:

	apply plugin: 'spring-boot'
	apply plugin: 'java'
	apply plugin: 'groovy'

view raw build.gradle hosted with ❤ by GitHub

And the dependencies:

	compile("org.codehaus.groovy:groovy-all:2.2.0")
	compile("com.fasterxml.jackson.core:jackson-databind")
	testCompile("org.spockframework:spock-core:0.7-groovy-2.0")
	testCompile("org.codehaus.groovy.modules.http-builder:http-builder:0.7+")
	testCompile("net.sf.json-lib:json-lib:2.4+")

view raw build.gradle hosted with ❤ by GitHub

The entire project is here. Happy testing.

Akka: Testing messages sent to an actor's parent

I've blogged previously about testing messages sent back to the sender and to a child actor. The final common scenario I come across is testing actors that send a messages back to its supervisor/parent. If it is in response to a message from the parent you can use the same technique as described in testing messages sent back to the sender.

However, if that is not the case then TestKit has a very simple way you can do it with the TestActorRef and a TestProbe. Any where you have a piece of code that looks like this:

context.parent ! "Any message"

For example:

	class ChildActor extends Actor {
	def receive: Actor.Receive = {
	case "Do something" => {
	// Do something important
	context.parent ! "I was told to do something and I did it"
	}
	}
	}

view raw ChildActor.scala hosted with ❤ by GitHub

Then you can test it by passing a TestProbe to your TestActorRef and using the expect* functions on the TestProbe. So to test the actor above your test will look something like this:

	class ChildActorTest extends TestKit(ActorSystem("ChildActorTest")) with FunSuiteLike with ShouldMatchers {
	test("Should inform parent when told to do something") {
	val parent = TestProbe()
	val underTest = TestActorRef(Props[ChildActor], parent.ref, "ChildActor")
	underTest ! "Do something"
	parent.expectMsg("I was told to do something and I did it")
	}
	}

view raw ChildActorTest.scala hosted with ❤ by GitHub

As you can see the TestActorRef can take an ActorRef to use as a parent when you use the apply method that takes in a Props.

Full code here. Happy testing.

Testing Scala Futures with ScalaTest 2.0

Recently I was writing integration tests for a library that returned futures. I wanted simple synchronous tests.

Fortunately in the latest release of ScalaTest they have added something to do just that: the ScalaFutures trait

Say you have a class that returns a Future, e.g:

	class ClassThatReturnsFutures() {
	def goDoSomething() : Future[String] = {
	future {
	println("I best do this asynchronously")
	"The result"
	}
	}
	}

view raw ClassThatReturnsFutures.scala hosted with ❤ by GitHub

And you want to write a test for this and you want to wait for the future to complete. In regular code you might use a call back or a for comprehension e.g:

	test("Test a asynchronous method synchronously") {
	val underTest = new ClassThatReturnsFutures()
	val futureResult = underTest.goDoSomething()
	futureResult onComplete {
	case Success(value) => value should equal("Something")
	case Failure(exp) => fail(exp)
	}
	}

view raw ClassThatReturnsFuturesTest.scala hosted with ❤ by GitHub

This won't work in a test as the test will finish before the future completes and the assertions are on a different thread.

ScalaFutures to the rescue! Upgrade to ScalaTest 2.0+ and mix in the ScalaFutures trait. Now you can test using whenReady:

	test("Test a asynchronous method synchronously - whenReady") {
	val underTest = new ClassThatReturnsFutures()
	val futureResult = underTest.goDoSomething()
	whenReady(futureResult) { result =>
	result should equal("The result")
	}
	}

view raw ClassThatReturnsFuturesTest.scala hosted with ❤ by GitHub

Or with futureValue:

	test("Test a asynchronous method synchronously - futureResult") {
	val underTest = new ClassThatReturnsFutures()
	val futureResult = underTest.goDoSomething()
	futureResult.futureValue should equal("The result")
	}

view raw ClassThatReturnsFuturesTest.scala hosted with ❤ by GitHub

Happy testing! Full source code here.

Akka: Testing messages sent to child actors

I previously blogged about testing messages sent back to the sender. Another common scenario is testing that an actor sends the correct message to a child. A piece of code that does this might look like:

	class ParentActor extends Actor {
	def receive: Actor.Receive = {
	case msg @ _ => {
	println(s"Received msg, delegating work to a child actor")
	val childActor = context.actorOf(Props[ChildActor])
	childActor ! "Go and do something important!"
	}
	}
	}

view raw ParentActor.scala hosted with ❤ by GitHub

But how do you test drive this kind of code?

	class ParentActorTest extends TestKit(ActorSystem("TestSystem")) with FunSuiteLike {
	test("Should delegate the important work to the client") {
	val underTest = TestActorRef(new ParentActor)
	underTest ! "Go do some work"
	// how do i test this?
	}
	}

view raw ParentActorTest.scala hosted with ❤ by GitHub

I've adopted the approach of removing the responsibility of creating the child from the ParentActor. To do this you can pass in a factory to the ParentActor's constructor that can be replaced for testing. To do this the ParentActor is changed to look like this:

	class ParentActor(childFactory: (ActorRefFactory) => ActorRef) extends Actor {
	def receive: Actor.Receive = {
	case msg @ _ => {
	println(s"Received msg, delegating work to a child actor")
	val childActor = childFactory(context)
	childActor ! "Go and do something important!"
	}
	}
	}

view raw ParentActor.scala hosted with ❤ by GitHub

The ParentActor now takes in a factory function which takes in an ActorFactoryRef and returns a ActorRef. This function is responsible for creating the ChildActor.

childFactory: (ActorRefFactory) => ActorRef

This is then used by the ParentActor as follows:

val childActor = childFactory(context)

You can now inject a TestProbe for testing rather than using a real ActorFactorRef. For example:

	class ParentActorTest extends TestKit(ActorSystem("TestSystem")) with FunSuiteLike {
	test("Should delegate the important work to the client") {
	val testProbeForChild = TestProbe()
	val underTest = TestActorRef(new ParentActor(_ => testProbeForChild.ref))
	underTest ! "Go do some work"
	testProbeForChild.expectMsg("Go and do something important!")
	}
	}

view raw ParentActorTest.scala hosted with ❤ by GitHub

And for the real code you can pass in an anonymous function that uses the ActorRefFactory to actually create a real ChildActor:

	test("Using a real child actor") {
	val underTest = TestActorRef(new ParentActor(actorFactory => actorFactory.actorOf(Props[ChildActor])))
	underTest ! "Go do some work"
	// Can't test this but shows how to crate a ParentActor in production code
	}

view raw ParentActorTest.scala hosted with ❤ by GitHub

Here you can see the ActorFactoryRef (context in Actors implement this interface) is used to create an Actor the same way as the original ParentActor did.

Full source code here.