Route TestKit

One of Apache Pekko HTTP’s design goals is good testability of the created services. For services built with the Routing DSL Apache Pekko HTTP provides a dedicated testkit that makes efficient testing of route logic easy and convenient. This “route test DSL” is made available with the pekko-http-testkit module.

Dependency

To use Apache Pekko HTTP TestKit, add the module to your project:

sbt

val PekkoVersion = "1.1.2"
val PekkoHttpVersion = "1.1.0"
libraryDependencies ++= Seq(
  "org.apache.pekko" %% "pekko-stream-testkit" % PekkoVersion,
  "org.apache.pekko" %% "pekko-http-testkit" % PekkoHttpVersion
)

Gradle

def versions = [
  PekkoVersion: "1.1.2",
  ScalaBinary: "2.13"
]
dependencies {
  implementation platform("org.apache.pekko:pekko-http-bom_${versions.ScalaBinary}:1.1.0")

  implementation "org.apache.pekko:pekko-stream-testkit_${versions.ScalaBinary}:${versions.PekkoVersion}"
  implementation "org.apache.pekko:pekko-http-testkit_${versions.ScalaBinary}"
}

Maven

<properties>
  <pekko.version>1.1.2</pekko.version>
  <scala.binary.version>2.13</scala.binary.version>
</properties>
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.apache.pekko</groupId>
      <artifactId>pekko-http-bom_${scala.binary.version}</artifactId>
      <version>1.1.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
<dependencies>
  <dependency>
    <groupId>org.apache.pekko</groupId>
    <artifactId>pekko-stream-testkit_${scala.binary.version}</artifactId>
    <version>${pekko.version}</version>
  </dependency>
  <dependency>
    <groupId>org.apache.pekko</groupId>
    <artifactId>pekko-http-testkit_${scala.binary.version}</artifactId>
  </dependency>
</dependencies>

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

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

Java

copysourcepathEnd(() -> 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

copysourceimport org.apache.pekko
import pekko.http.scaladsl.server.Directives._
import pekko.http.scaladsl.server.Route

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

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

Java

copysourceimport org.apache.pekko.http.javadsl.server.AllDirectives;
import org.apache.pekko.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

copysourceimport org.apache.pekko
import pekko.http.scaladsl.model.StatusCodes
import pekko.http.scaladsl.testkit.ScalatestRouteTest
import pekko.http.scaladsl.server._
import Directives._
import org.scalatest.matchers.should.Matchers
import org.scalatest.wordspec.AnyWordSpec

class TestKitFragmentSpec extends AnyWordSpec 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

copysourceimport org.apache.pekko.http.javadsl.model.HttpRequest;
import org.apache.pekko.http.javadsl.model.StatusCodes;
import org.apache.pekko.http.javadsl.server.AllDirectives;
import org.apache.pekko.http.javadsl.server.Route;
import org.apache.pekko.http.javadsl.testkit.JUnitRouteTest;
import org.apache.pekko.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 Apache Pekko 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

copysourceimport scala.concurrent.duration._
import pekko.http.scaladsl.testkit.RouteTestTimeout
import pekko.testkit.TestDuration

implicit val timeout: RouteTestTimeout = RouteTestTimeout(5.seconds.dilated)

Java

copysource@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.

Testing Actor integration

The ScalatestRouteTestJUnitRouteTest still provides a Classic ActorSystemActorSystem, so if you are not using the Classic API you will need to adapt it:

Scala

copysourceimport scala.concurrent.duration._
import scala.util.{ Failure, Success }

import org.apache.pekko
import pekko.{ actor => untyped }
import pekko.actor.testkit.typed.scaladsl.TestProbe
import pekko.actor.typed.{ ActorRef, ActorSystem, Scheduler }
import pekko.actor.typed.scaladsl.AskPattern._
import pekko.http.scaladsl.server.Directives._
import pekko.http.scaladsl.testkit.ScalatestRouteTest
import pekko.util.Timeout

import org.scalatest.matchers.should.Matchers
import org.scalatest.wordspec.AnyWordSpec

object RouteUnderTest {
  case class Ping(replyTo: ActorRef[String])

  // Your route under test, scheduler is only needed as ask is used
  def route(someActor: ActorRef[Ping])(implicit scheduler: Scheduler, timeout: Timeout) = get {
    path("ping") {
      complete(someActor ? Ping.apply)
    }
  }
}

class TestKitWithActorSpec extends AnyWordSpec with Matchers with ScalatestRouteTest {
  import RouteUnderTest._

  // This test does not use the classic APIs,
  // so it needs to adapt the system:
  import pekko.actor.typed.scaladsl.adapter._
  implicit val typedSystem: ActorSystem[_] = system.toTyped
  implicit val timeout: Timeout = Timeout(500.milliseconds)
  implicit val scheduler: untyped.Scheduler = system.scheduler

  "The service" should {
    "return a 'PONG!' response for GET requests to /ping" in {
      val probe = TestProbe[Ping]()
      val test = Get("/ping") ~> RouteUnderTest.route(probe.ref)
      val ping = probe.expectMessageType[Ping]
      ping.replyTo ! "PONG!"
      test ~> check {
        responseAs[String] shouldEqual "PONG!"
      }
    }
  }
}

Java

copysourceimport org.apache.pekko.actor.testkit.typed.javadsl.TestProbe;
import org.apache.pekko.actor.typed.ActorSystem;
import org.apache.pekko.actor.typed.javadsl.Adapter;
import org.apache.pekko.http.javadsl.model.HttpRequest;
import org.apache.pekko.http.javadsl.testkit.JUnitRouteTest;

import org.apache.pekko.http.javadsl.testkit.TestRoute;
import org.apache.pekko.http.javadsl.testkit.TestRouteResult;
import org.junit.Test;

public class TestKitWithActorTest extends JUnitRouteTest {

  @Test
  public void returnPongForGetPing() {
    // This test does not use the classic APIs,
    // so it needs to adapt the system:
    ActorSystem<Void> system = Adapter.toTyped(system());

    TestProbe<MyAppWithActor.Ping> probe = TestProbe.create(system);
    TestRoute testRoute =
        testRoute(new MyAppWithActor().createRoute(probe.getRef(), system.scheduler()));

    TestRouteResult result = testRoute.run(HttpRequest.GET("/ping"));
    MyAppWithActor.Ping ping = probe.expectMessageClass(MyAppWithActor.Ping.class);
    ping.replyTo.tell("PONG!");
    result.assertEntity("PONG!");
  }
}

Integration Testing Routes

Use ~!> to test a route running in full HTTP server mode:

REQUEST ~!> ROUTE ~> check {
  ASSERTIONS
}

Certain routes can only be tested with ~!>, for example routes that use the withRequestTimeout directive.

Examples

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