Testing
Introduction
This document implements a simple org.http4s.HttpRoutes and then
walk through the results of applying inputs, i.e. org.http4s.Request, to the service, i.e. org.http4s.HttpService.
After reading this doc, the reader should feel comfortable writing a unit test using his/her favorite Scala testing library.
Now, let’s define an org.http4s.HttpService.
import cats.syntax.all._
import io.circe._
import io.circe.syntax._
import io.circe.generic.semiauto._
import cats.effect._
import org.http4s._
import org.http4s.circe._
import org.http4s.dsl.io._
import org.http4s.implicits._
case class User(name: String, age: Int)
implicit val UserEncoder: Encoder[User] = deriveEncoder[User]
// UserEncoder: Encoder[User] = io.circe.generic.encoding.DerivedAsObjectEncoder$$anon$1@ed26a3
trait UserRepo[F[_]] {
def find(userId: String): F[Option[User]]
}
def service[F[_]](repo: UserRepo[F])(
implicit F: Effect[F]
): HttpRoutes[F] = HttpRoutes.of[F] {
case GET -> Root / "user" / id =>
repo.find(id).map {
case Some(user) => Response(status = Status.Ok).withEntity(user.asJson)
case None => Response(status = Status.NotFound)
}
}
For testing, let’s define a check function:
// Return true if match succeeds; otherwise false
def check[A](actual: IO[Response[IO]],
expectedStatus: Status,
expectedBody: Option[A])(
implicit ev: EntityDecoder[IO, A]
): Boolean = {
val actualResp = actual.unsafeRunSync()
val statusCheck = actualResp.status == expectedStatus
val bodyCheck = expectedBody.fold[Boolean](
actualResp.body.compile.toVector.unsafeRunSync().isEmpty)( // Verify Response's body is empty.
expected => actualResp.as[A].unsafeRunSync() == expected
)
statusCheck && bodyCheck
}
Let’s define service by passing a UserRepo that returns Ok(user).
val success: UserRepo[IO] = new UserRepo[IO] {
def find(id: String): IO[Option[User]] = IO.pure(Some(User("johndoe", 42)))
}
// success: UserRepo[IO] = repl.MdocSession$App$$anon$3@10eb244e
val response: IO[Response[IO]] = service[IO](success).orNotFound.run(
Request(method = Method.GET, uri = uri"/user/not-used" )
)
// response: IO[Response[IO]] = Map(
// Suspend(org.http4s.HttpRoutes$$$Lambda$8554/1844614425@d4bcc0e),
// cats.data.OptionT$$Lambda$8556/248549016@60a10464,
// StackTrace(
// List(
// cats.effect.internals.IOTracing$.buildFrame(IOTracing.scala:48),
// cats.effect.internals.IOTracing$.buildCachedFrame(IOTracing.scala:39),
// cats.effect.internals.IOTracing$.cached(IOTracing.scala:34),
// cats.effect.IO.map(IO.scala:106),
// cats.effect.IOLowPriorityInstances$IOEffect.map(IO.scala:870),
// cats.effect.IOLowPriorityInstances$IOEffect.map(IO.scala:863),
// cats.data.OptionT.getOrElse(OptionT.scala:99),
// org.http4s.syntax.KleisliResponseOps.$anonfun$orNotFound$1(KleisliSyntax.scala:49),
// org.http4s.server.blaze.Http1ServerStage.$anonfun$raceTimeout$4(Http1ServerStage.scala:368),
// org.http4s.server.blaze.Http1ServerStage$$anon$2.$anonfun$run$1(Http1ServerStage.scala:201),
// cats.effect.internals.IORunLoop$.liftedTree1$1(IORunLoop.scala:114),
// cats.effect.internals.IORunLoop$.cats$effect$internals$IORunLoop$$loop(IORunLoop.scala:114),
// cats.effect.internals.IORunLoop$RestartCallback.signal(IORunLoop.scala:463),
// cats.effect.internals.IORunLoop$RestartCallback.apply(IORunLoop.scala:484),
// cats.effect.internals.IORunLoop$RestartCallback.apply(IORunLoop.scala:422),
// cats.effect.internals.IOShift$Tick.run(IOShift.scala:36),
// java.util.concurrent.ForkJoinTask$RunnableExecuteAction.exec(ForkJoinTask.java:1402),
// java.util.concurrent.ForkJoinTask.doExec(ForkJoinTask.java:289),
// java.util.concurrent.ForkJoinPool$WorkQueue.runTask(ForkJoinPool.java:1056),
// java.util.concurrent.ForkJoinPool.runWorker(ForkJoinPool.java:1692),
// java.util.concurrent.ForkJoinWorkerThread.run(ForkJoinWorkerThread.java:175)
// )
// )
// )
val expectedJson = Json.obj(
("name", Json.fromString("johndoe")),
("age", Json.fromBigInt(42))
)
// expectedJson: Json = JObject(object[name -> "johndoe",age -> 42])
check[Json](response, Status.Ok, Some(expectedJson))
// res0: Boolean = true
Next, let’s define a service with a userRepo that returns None to any input.
val foundNone: UserRepo[IO] = new UserRepo[IO] {
def find(id: String): IO[Option[User]] = IO.pure(None)
}
// foundNone: UserRepo[IO] = repl.MdocSession$App$$anon$4@910feed
val response: IO[Response[IO]] = service[IO](foundNone).orNotFound.run(
Request(method = Method.GET, uri = uri"/user/not-used" )
)
// response: IO[Response[IO]] = Map(
// Suspend(org.http4s.HttpRoutes$$$Lambda$8554/1844614425@409072d5),
// cats.data.OptionT$$Lambda$8556/248549016@13e8fd75,
// StackTrace(
// List(
// cats.effect.internals.IOTracing$.buildFrame(IOTracing.scala:48),
// cats.effect.internals.IOTracing$.buildCachedFrame(IOTracing.scala:39),
// cats.effect.internals.IOTracing$.cached(IOTracing.scala:34),
// cats.effect.IO.map(IO.scala:106),
// cats.effect.IOLowPriorityInstances$IOEffect.map(IO.scala:870),
// cats.effect.IOLowPriorityInstances$IOEffect.map(IO.scala:863),
// cats.data.OptionT.getOrElse(OptionT.scala:99),
// org.http4s.syntax.KleisliResponseOps.$anonfun$orNotFound$1(KleisliSyntax.scala:49),
// org.http4s.server.blaze.Http1ServerStage.$anonfun$raceTimeout$4(Http1ServerStage.scala:368),
// org.http4s.server.blaze.Http1ServerStage$$anon$2.$anonfun$run$1(Http1ServerStage.scala:201),
// cats.effect.internals.IORunLoop$.liftedTree1$1(IORunLoop.scala:114),
// cats.effect.internals.IORunLoop$.cats$effect$internals$IORunLoop$$loop(IORunLoop.scala:114),
// cats.effect.internals.IORunLoop$RestartCallback.signal(IORunLoop.scala:463),
// cats.effect.internals.IORunLoop$RestartCallback.apply(IORunLoop.scala:484),
// cats.effect.internals.IORunLoop$RestartCallback.apply(IORunLoop.scala:422),
// cats.effect.internals.IOShift$Tick.run(IOShift.scala:36),
// java.util.concurrent.ForkJoinTask$RunnableExecuteAction.exec(ForkJoinTask.java:1402),
// java.util.concurrent.ForkJoinTask.doExec(ForkJoinTask.java:289),
// java.util.concurrent.ForkJoinPool$WorkQueue.runTask(ForkJoinPool.java:1056),
// java.util.concurrent.ForkJoinPool.runWorker(ForkJoinPool.java:1692),
// java.util.concurrent.ForkJoinWorkerThread.run(ForkJoinWorkerThread.java:175)
// )
// )
// )
check[Json](response, Status.NotFound, None)
// res1: Boolean = true
Finally, let’s pass a Request which our service does not handle.
val doesNotMatter: UserRepo[IO] = new UserRepo[IO] {
def find(id: String): IO[Option[User]] = IO.raiseError(new RuntimeException("Should not get called!"))
}
// doesNotMatter: UserRepo[IO] = repl.MdocSession$App$$anon$5@7b824948
val response: IO[Response[IO]] = service[IO](doesNotMatter).orNotFound.run(
Request(method = Method.GET, uri = uri"/not-a-matching-path" )
)
// response: IO[Response[IO]] = Map(
// Suspend(org.http4s.HttpRoutes$$$Lambda$8554/1844614425@756b3743),
// cats.data.OptionT$$Lambda$8556/248549016@362ee5e1,
// StackTrace(
// List(
// cats.effect.internals.IOTracing$.buildFrame(IOTracing.scala:48),
// cats.effect.internals.IOTracing$.buildCachedFrame(IOTracing.scala:39),
// cats.effect.internals.IOTracing$.cached(IOTracing.scala:34),
// cats.effect.IO.map(IO.scala:106),
// cats.effect.IOLowPriorityInstances$IOEffect.map(IO.scala:870),
// cats.effect.IOLowPriorityInstances$IOEffect.map(IO.scala:863),
// cats.data.OptionT.getOrElse(OptionT.scala:99),
// org.http4s.syntax.KleisliResponseOps.$anonfun$orNotFound$1(KleisliSyntax.scala:49),
// org.http4s.server.blaze.Http1ServerStage.$anonfun$raceTimeout$4(Http1ServerStage.scala:368),
// org.http4s.server.blaze.Http1ServerStage$$anon$2.$anonfun$run$1(Http1ServerStage.scala:201),
// cats.effect.internals.IORunLoop$.liftedTree1$1(IORunLoop.scala:114),
// cats.effect.internals.IORunLoop$.cats$effect$internals$IORunLoop$$loop(IORunLoop.scala:114),
// cats.effect.internals.IORunLoop$RestartCallback.signal(IORunLoop.scala:463),
// cats.effect.internals.IORunLoop$RestartCallback.apply(IORunLoop.scala:484),
// cats.effect.internals.IORunLoop$RestartCallback.apply(IORunLoop.scala:422),
// cats.effect.internals.IOShift$Tick.run(IOShift.scala:36),
// java.util.concurrent.ForkJoinTask$RunnableExecuteAction.exec(ForkJoinTask.java:1402),
// java.util.concurrent.ForkJoinTask.doExec(ForkJoinTask.java:289),
// java.util.concurrent.ForkJoinPool$WorkQueue.runTask(ForkJoinPool.java:1056),
// java.util.concurrent.ForkJoinPool.runWorker(ForkJoinPool.java:1692),
// java.util.concurrent.ForkJoinWorkerThread.run(ForkJoinWorkerThread.java:175)
// )
// )
// )
check[String](response, Status.NotFound, Some("Not found"))
// res2: Boolean = true
Conclusion
The above documentation demonstrated how to define an HttpService[F], pass Request’s, and then
test the expected Response.
To add unit tests in your chosen Scala Testing Framework, please follow the above examples.
References