Route TestKit

One of Akka HTTP’s design goals is good testability of the created services. For services built with the Routing DSL Akka HTTP provides a dedicated testkit that makes efficient testing of route logic easy and convenient. This “route test DSL” is made available with the akka-http-testkit module. To use it include the following dependency:

"com.typesafe.akka" %% "akka-http-testkit" % "10.0.7"

Usage

Here is an example of what a simple test with the routing testkit might look like using the built-in support for scalatest and specs2:

ScalaTest

import org.scalatest.{ Matchers, WordSpec }
import akka.http.scaladsl.model.StatusCodes
import akka.http.scaladsl.testkit.ScalatestRouteTest
import akka.http.scaladsl.server._
import Directives._

class FullTestKitExampleSpec extends WordSpec with Matchers with ScalatestRouteTest {

  val smallRoute =
    get {
      pathSingleSlash {
        complete {
          "Captain on the bridge!"
        }
      } ~
      path("ping") {
        complete("PONG!")
      }
    }

  "The service" should {

    "return a greeting for GET requests to the root path" in {
      // tests:
      Get() ~> smallRoute ~> check {
        responseAs[String] shouldEqual "Captain on the bridge!"
      }
    }

    "return a 'PONG!' response for GET requests to /ping" in {
      // tests:
      Get("/ping") ~> smallRoute ~> check {
        responseAs[String] shouldEqual "PONG!"
      }
    }

    "leave GET requests to other paths unhandled" in {
      // tests:
      Get("/kermit") ~> smallRoute ~> check {
        handled shouldBe false
      }
    }

    "return a MethodNotAllowed error for PUT requests to the root path" in {
      // tests:
      Put() ~> Route.seal(smallRoute) ~> check {
        status shouldEqual StatusCodes.MethodNotAllowed
        responseAs[String] shouldEqual "HTTP method not allowed, supported methods: GET"
      }
    }
  }
}

specs2

import org.specs2.mutable.Specification
import akka.http.scaladsl.model.StatusCodes
import akka.http.scaladsl.testkit.Specs2RouteTest
import akka.http.scaladsl.server._
import Directives._

class FullSpecs2TestKitExampleSpec extends Specification with Specs2RouteTest {

  val smallRoute =
    get {
      pathSingleSlash {
        complete {
          "Captain on the bridge!"
        }
      } ~
      path("ping") {
        complete("PONG!")
      }
    }

  "The service" should {

    "return a greeting for GET requests to the root path" in {
      // tests:
      Get() ~> smallRoute ~> check {
        responseAs[String] === "Captain on the bridge!"
      }
    }

    "return a 'PONG!' response for GET requests to /ping" in {
      // tests:
      Get("/ping") ~> smallRoute ~> check {
        responseAs[String] === "PONG!"
      }
    }

    "leave GET requests to other paths unhandled" in {
      // tests:
      Get("/kermit") ~> smallRoute ~> check {
        handled should beFalse
      }
    }

    "return a MethodNotAllowed error for PUT requests to the root path" in {
      // tests:
      Put() ~> Route.seal(smallRoute) ~> check {
        status === StatusCodes.MethodNotAllowed
        responseAs[String] === "HTTP method not allowed, supported methods: GET"
      }
    }
  }
}

The basic structure of a test built with the testkit is this (expression placeholder in all-caps):

REQUEST ~> ROUTE ~> check {
  ASSERTIONS
}

In this template REQUEST is an expression evaluating to an HttpRequest instance. In most cases your test will, in one way or another, extend from RouteTest which itself mixes in the akka.http.scaladsl.client.RequestBuilding trait, which gives you a concise and convenient way of constructing test requests. [1]

ROUTE is an expression evaluating to a Route. You can specify one inline or simply refer to the route structure defined in your service.

The final element of the ~> chain is a check call, which takes a block of assertions as parameter. In this block you define your requirements onto the result produced by your route after having processed the given request. Typically you use one of the defined “inspectors” to retrieve a particular element of the routes response and express assertions against it using the test DSL provided by your test framework. For example, with scalatest, in order to verify that your route responds to the request with a status 200 response, you’d use the status inspector and express an assertion like this:

status shouldEqual 200

The following inspectors are defined:

[1] If the request URI is relative it will be made absolute using an implicitly available instance of DefaultHostInfo whose value is “http://example.com” by default. This mirrors the behavior of akka-http-core which always produces absolute URIs for incoming request based on the request URI and the Host-header of the request. You can customize this behavior by bringing a custom instance of DefaultHostInfo into scope.

Testing sealed Routes

The section above describes how to test a “regular” branch of your route structure, which reacts to incoming requests with HTTP response parts or rejections. Sometimes, however, you will want to verify that your service also translates Rejections to HTTP responses in the way you expect.

You do this by wrapping your route with the akka.http.scaladsl.server.Route.seal. The seal wrapper applies the logic of the in-scope ExceptionHandler and RejectionHandler to all exceptions and rejections coming back from the route, and translates them to the respective HttpResponse.

Note that explicit call on the akka.http.scaladsl.server.Route.seal method is needed in test code, but in your application code it is not necessary. As described in Sealing a Route, your application code only needs to bring implicit rejection and exception handlers in scope.

Testing Route fragments

Since the testkit is request-based, you cannot test requests that are illegal or impossible in HTTP. One such instance is testing a route that begins with the pathEnd directive, such as routeFragment here:

pathEnd {
  get {
    complete {
      "Fragments of imagination"
    }
  }
}

You might create a route such as this to be able to compose it into another route such as:

import akka.http.scaladsl.server.Directives._
import akka.http.scaladsl.server.Route

object RouteFragment {
  val route: Route = pathEnd {
    get {
      complete("example")
    }
  }
}

object API {
  pathPrefix("version") {
    RouteFragment.route
  }
}

However, it is impossible to unit test this Route directly using testkit, since it is impossible to create an empty HTTP request. To test this type of route, embed it in a synthetic route in your test, such as testRoute in the example above.

This is what the full working test looks like:

import org.scalatest.{Matchers, WordSpec}
import akka.http.scaladsl.model.StatusCodes
import akka.http.scaladsl.testkit.ScalatestRouteTest
import akka.http.scaladsl.server._
import Directives._

class TestKitFragmentSpec extends WordSpec with Matchers with ScalatestRouteTest {

  val routeFragment =
      pathEnd {
        get {
          complete {
            "Fragments of imagination"
          }
        }
      }

  // Synthetic route to enable pathEnd testing
  val testRoute = {
    pathPrefix("test") {
      routeFragment
    }
  }

  "The service" should {
    "return a greeting for GET requests" in {
      // tests:
      Get("/test") ~> testRoute ~> check {
        responseAs[String] shouldEqual "Fragments of imagination"
      }
    }

    "return a MethodNotAllowed error for PUT requests to the root path" in {
      // tests:
      Put("/test") ~> Route.seal(testRoute) ~> check {
        status shouldEqual StatusCodes.MethodNotAllowed
      }
    }
  }
}

Examples

A great pool of examples are the tests for all the predefined directives in Akka HTTP. They can be found here.