Testing Server Applications

    Table of contents:

    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

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

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

    1. setBody("name1=value1&name2=value%202")
    1. fun List<Pair<String, String>>.formUrlEncode(): String

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

    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.             HttpHeaders.ContentDisposition,
    13.             ContentDisposition.File
    14.                 .withParameter(ContentDisposition.Parameters.Name, "file")
    15.                 .withParameter(ContentDisposition.Parameters.FileName, "file.txt")
    16.                 .toString()
    17.         ))
    19. }

    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 for more information.

    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.

    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.         val cookieValue = trackedCookies.map { (it.name).encodeURLParameter() + "=" + (it.value).encodeURLParameter() }.joinToString("; ")
    19.         addHeader("Cookie", cookieValue)
    20.         setup()
    21.     }.apply {
    22.         trackedCookies = response.headers.values("Set-Cookie").map { parseServerSetCookieHeader(it) }
    23.     }
    24. }

    Example with dependencies

    See full example of application testing in .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. // ...
    2. dependencies {
    3.     // ...
    4.     testCompile("io.ktor:ktor-server-test-host:$ktor_version")