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:

sbt

libraryDependencies += "com.typesafe.akka" %% "akka-http-testkit" % "10.0.15"

Gradle

dependencies {
  compile group: 'com.typesafe.akka', name: 'akka-http-testkit_2.12', version: '10.0.15'
}

Maven

<dependency>
  <groupId>com.typesafe.akka</groupId>
  <artifactId>akka-http-testkit_2.12</artifactId>
  <version>10.0.15</version>
</dependency>

Usage

REQUEST ~> ROUTE ~> check {
  ASSERTIONS
}

status shouldEqual 200

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 calling the Route.seal() method. The Route.seal() method applies the logic of the in-scope ExceptionHandler and RejectionHandler passed as method arguments to all exceptions and rejections coming back from the route, and translates them to the respective HttpResponseHttpResponse.

Note that explicit call on the 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:

Scala

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

Java

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:

Scala

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
  }
}

Java

import akka.http.javadsl.server.AllDirectives;
import akka.http.javadsl.server.Route;

public class MyAppFragment extends AllDirectives {

    public Route createRoute() {
        return
                pathEnd(() ->
                        get(() ->
                                complete("Fragments of imagination")
                        )
                );
    }

}

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:

Scala

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
      }
    }
  }
}

Java

import akka.http.javadsl.model.HttpRequest;
import akka.http.javadsl.model.StatusCodes;
import akka.http.javadsl.server.AllDirectives;
import akka.http.javadsl.server.Route;
import akka.http.javadsl.testkit.JUnitRouteTest;
import akka.http.javadsl.testkit.TestRoute;
import org.junit.Test;

public class TestKitFragmentTest extends JUnitRouteTest {
    class FragmentTester extends AllDirectives {
        public Route createRoute(Route fragment) {
            return
                    pathPrefix("test", () ->
                            fragment
                    );
        }
    }

    TestRoute fragment = testRoute(new MyAppFragment().createRoute());
    TestRoute testRoute = testRoute(new FragmentTester().createRoute(fragment.underlying()));

    @Test
    public void testFragment() {
        testRoute.run(HttpRequest.GET("/test"))
                .assertStatusCode(200)
                .assertEntity("Fragments of imagination");

        testRoute.run(HttpRequest.PUT("/test"))
                .assertStatusCode(StatusCodes.METHOD_NOT_ALLOWED);
    }
}

Accounting for Slow Test Systems

The timeouts you consciously defined on your lightning fast development environment might be too tight for your, most probably, high-loaded Continuous Integration server, invariably causing spurious failures. To account for such situations, timeout durations can be scaled by a given factor on such environments. Check the Akka DocsAkka Docs for further information.

Increase Timeout

The default timeout when testing your routes using the testkit is 1 second3 seconds second. Sometimes, though, this might not be enough. In order to extend this default timeout, to say 5 seconds, just add the following implicit in scope:

Scala

import scala.concurrent.duration._
import akka.http.scaladsl.testkit.RouteTestTimeout
import akka.testkit.TestDuration

implicit val timeout = RouteTestTimeout(5.seconds dilated)

Java

@Override
public FiniteDuration awaitDuration() {
    return FiniteDuration.create(5, TimeUnit.SECONDS);
}

Remember to configure the timeout using dilated if you want to account for slow test systems.

Examples

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