Testing Server Applications

Ktor is designed to allow the creation of applications that are easily testable. And of course,Ktor infrastructure itself is well tested with unit, integration, and stress tests.In this section, you will learn how to test your applications.

Table of contents:

TestEngine

Ktor has a special kind engine TestEngine, that doesn’t create a web server, doesn’t bind to sockets and doesn’t doany real HTTP requests. Instead, it hooks directly into internal mechanisms and processes ApplicationCall directly. This allows for fast test execution at the expense of maybe missing some HTTP processing details. It’s perfectly capable of testing application logic, but be sure to set up integration tests as well.

A quick walkthrough:

  • Add ktor-server-test-host dependency to the test scope
  • Create a JUnit test class and a test function
  • Use withTestApplication function to setup a test environment for your Application
  • Use the handleRequest function to send requests to your application and verify the results

Building post/put bodies

application/x-www-form-urlencoded

When building the request, you have to add a Content-Type header:

  1. addHeader(HttpHeaders.ContentType, ContentType.Application.FormUrlEncoded.toString())

And then set the bodyChannel, for example, by calling the setBody method:

  1. setBody("name1=value1&name2=value%202")

Ktor provides an extension method to build a form urlencoded out of a List of key/value pairs:

  1. fun List<Pair<String, String>>.formUrlEncode(): String

So a complete example to build a post request urlencoded could be:

  1. val call = handleRequest(HttpMethod.Post, "/route") {
  2.    addHeader(HttpHeaders.ContentType, ContentType.Application.FormUrlEncoded.toString())
  3.    setBody(listOf("name1" to "value1", "name2" to "value2").formUrlEncode())
  4. }

multipart/form-data

When uploading big files, it is common to use the multipart encoding, which allows sendingcomplete files without preprocessing. Ktor’s test host provides a setBody extension methodto build this kind of payload. For example:

  1. val call = handleRequest(HttpMethod.Post, "/upload") {
  2.     val boundary = "***bbb***"
  4.     addHeader(HttpHeaders.ContentType, ContentType.MultiPart.FormData.withParameter("boundary", boundary).toString())
  5.     setBody(boundary, listOf(
  6.         PartData.FormItem("title123", { }, headersOf(
  7.             HttpHeaders.ContentDisposition,
  8.             ContentDisposition.Inline
  9.                 .withParameter(ContentDisposition.Parameters.Name, "title")
  10.                 .toString()
  11.         )),
  12.         PartData.FileItem({ byteArrayOf(1, 2, 3).inputStream().asInput() }, {}, headersOf(
  13.             HttpHeaders.ContentDisposition,
  14.             ContentDisposition.File
  15.                 .withParameter(ContentDisposition.Parameters.Name, "file")
  16.                 .withParameter(ContentDisposition.Parameters.FileName, "file.txt")
  17.                 .toString()
  18.         ))
  19.     ))
  20. }

Defining configuration properties in tests

In tests, instead of using an application.conf to define configuration properties,you can use the MapApplicationConfig.put method:

  1. withTestApplication({
  2.     (environment.config as MapApplicationConfig).apply {
  3.         // Set here the properties
  4.         put("youkube.session.cookie.key", "03e156f6058a13813816065")
  5.         put("youkube.upload.dir", tempPath.absolutePath)
  6.     }
  7.     main() // Call here your application's module
  8. })

HttpsRedirect feature

The HttpsRedirect changes how testing is performed.Check the testing section of the HttpsRedirect feature for more information.

Testing several requests preserving sessions/cookies

You can easily test several requests in a row keeping the Cookie information among them. By using the cookiesSession method.This method defines a session context that will hold cookies, and exposes a CookieTrackerTestApplicationEngine.handleRequestextension method to perform requests in that context.

For example:

  1. @Test
  2. fun testLoginSuccessWithTracker() = testApp {
  3.     val password = "mylongpassword"
  4.     val passwordHash = hash(password)
  5.     every { dao.user("test1", passwordHash) } returns User("test1", "test1@test.com", "test1", passwordHash)
  7.     cookiesSession {
  8.         handleRequest(HttpMethod.Post, "/login") {
  9.             addHeader(HttpHeaders.ContentType, ContentType.Application.FormUrlEncoded.toString())
  10.             setBody(listOf("userId" to "test1", "password" to password).formUrlEncode())
  11.         }.apply {
  12.             assertEquals(302, response.status()?.value)
  13.             assertEquals("http://localhost/user/test1", response.headers["Location"])
  14.             assertEquals(null, response.content)
  15.         }
  17.         handleRequest(HttpMethod.Get, "/").apply {
  18.             assertTrue { response.content!!.contains("sign out") }
  19.         }
  20.     }
  21. }

Note: cookiesSession is not included in Ktor itself, but you can add this boilerplate to use it:

  1. fun TestApplicationEngine.cookiesSession(
  2.     initialCookies: List<Cookie> = listOf(),
  3.     callback: CookieTrackerTestApplicationEngine.() -> Unit
  4. ) {
  5.     callback(CookieTrackerTestApplicationEngine(this, initialCookies))
  6. }
  8. class CookieTrackerTestApplicationEngine(
  9.     val engine: TestApplicationEngine,
  10.     var trackedCookies: List<Cookie> = listOf()
  11. )
  13. fun CookieTrackerTestApplicationEngine.handleRequest(
  14.     method: HttpMethod,
  15.     uri: String,
  16.     setup: TestApplicationRequest.() -> Unit = {}
  17. ): TestApplicationCall {
  18.     return engine.handleRequest(method, uri) {
  19.         val cookieValue = trackedCookies.map { (it.name).encodeURLParameter() + "=" + (it.value).encodeURLParameter() }.joinToString("; ")
  20.         addHeader("Cookie", cookieValue)
  21.         setup()
  22.     }.apply {
  23.         trackedCookies = response.headers.values("Set-Cookie").map { parseServerSetCookieHeader(it) }
  24.     }
  25. }

Example with dependencies

See full example of application testing in ktor-samples-testable.Also, most ktor-samples modules provideexamples of how to test specific functionalities.

In some cases we will need some services and dependencies. Instead of storing them globally, we suggest youto create a separate function receiving the service dependencies. This allows you to pass different(potentially mocked) dependencies in your tests:

test.kt

  1. class ApplicationTest {
  2.     class ConstantRandom(val value: Int) : Random() {
  3.         override fun next(bits: Int): Int = value
  4.     }
  6.     @Test fun testRequest() = withTestApplication({
  7.         testableModuleWithDependencies(
  8.             random = ConstantRandom(7)
  9.         )
  10.     }) {
  11.         with(handleRequest(HttpMethod.Get, "/")) {
  12.             assertEquals(HttpStatusCode.OK, response.status())
  13.             assertEquals("Random: 7", response.content)
  14.         }
  15.         with(handleRequest(HttpMethod.Get, "/index.html")) {
  16.             assertFalse(requestHandled)
  17.         }
  18.     }
  19. }

module.kt

  1. fun Application.testableModule() {
  2.     testableModuleWithDependencies(
  3.         random = SecureRandom()
  4.     )
  5. }
  7. fun Application.testableModuleWithDependencies(random: Random) {
  8.     routing {
  9.         get("/") {
  10.             call.respondText("Random: ${random.nextInt(100)}")
  11.         }
  12.     }
  13. }

build.gradle

  1. // ...
  2. dependencies {
  3.     // ...
  4.     testCompile("io.ktor:ktor-server-test-host:$ktor_version")
  5. }