Skip to content

在 Ktor Server 中進行測試 ​

必要的相依性: io.ktor:ktor-server-test-host, org.jetbrains.kotlin:kotlin-test

Ktor 提供了一個測試引擎,可以直接執行應用程式呼叫,而無需啟動真正的 Web 伺服器或繫結至 socket。請求會在內部進行處理,相較於執行完整的伺服器,這使得測試速度更快且更可靠。

新增相依性 ​

若要測試 Ktor 伺服器應用程式,請在組建指令碼中加入以下相依性:

  • ktor-server-test-host 相依性提供測試引擎:

    kotlin
    testImplementation("io.ktor:ktor-server-test-host:$ktor_version")
    groovy
    testImplementation "io.ktor:ktor-server-test-host:$ktor_version"
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-server-test-host-jvm</artifactId>
        <version>${ktor_version}</version>
    </dependency>
  • kotlin-test 相依性提供了一組用於執行斷言的公用函式:

    kotlin
    testImplementation("org.jetbrains.kotlin:kotlin-test:$kotlin_version")
    groovy
    testImplementation "org.jetbrains.kotlin:kotlin-test:$kotlin_version"
    xml
    <dependency>
        <groupId>org.jetbrains.kotlin</groupId>
        <artifactId>kotlin-test</artifactId>
        <version>${kotlin_version}</version>
    </dependency>

對於 Native 伺服器測試,請將這些構件加入 nativeTest 原始碼集中。

測試總覽 ​

您可以使用 testApplication {} 函式以及所提供的 HTTP 用戶端來測試 Ktor 應用程式。一般的工作流程包含以下步驟:

  1. 使用 testApplication {} 定義測試。
  2. 配置並執行應用程式的測試執行個體。
  3. (選用)配置 HTTP 用戶端。
  4. 使用該用戶端向您的測試應用程式發送 HTTP 請求並接收回應。
  5. 使用來自 kotlin.test 的斷言驗證回應,包括狀態碼、標頭與內文內容。

以下範例測試一個對 GET / 請求回應純文字的簡易 Ktor 應用程式:

kotlin
package com.example

import io.ktor.client.request.*
import io.ktor.client.statement.*
import io.ktor.http.*
import io.ktor.server.application.*
import io.ktor.server.testing.*
import kotlin.test.*

class ApplicationTest {
    @Test
    fun testRoot() = testApplication {
        application {
            module()
        }
        val response = client.get("/")
        assertEquals(HttpStatusCode.OK, response.status)
        assertEquals("Hello, world!", response.bodyAsText())
    }
}
kotlin
package com.example

import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun main(args: Array<String>): Unit = io.ktor.server.netty.EngineMain.main(args)

fun Application.module() {
    routing {
        get("/") {
            call.respondText("Hello, world!")
        }
    }
}

如需完整的程式碼範例,請參閱 engine-main。

設定 JUnit 測試類別 ​

在為 Ktor 應用程式撰寫測試之前,請先建立測試檔案和 JUnit 測試類別。

    1. 在專案中尋找或建立 src/test/kotlin 目錄。
    2. 建立新的 Kotlin 檔案(例如 ApplicationTest.kt)。
    3. 定義一個將包含測試的 Kotlin 類別:
      kotlin
      class ApplicationTest {
          // 測試函式置於此處
      }
    4. 新增一個帶有 @Test 註解的測試函式。在測試內部,使用 testApplication {} 函式在測試環境中執行應用程式:
      kotlin
       class ApplicationTest {
           @Test
           fun testRoot() = testApplication {
               // ...
           }
       }

testApplication {} 函式是 Ktor 中伺服器測試的進入點。它會建立一個隔離的測試環境,在不啟動真實 Web 伺服器的情況下執行應用程式,並提供預先配置的 HTTP 用戶端,用於發送請求與斷言回應。

在 testApplication {} 區塊內部,您可以配置測試應用程式的行為,例如載入哪些模組、公開哪些路由、如何設定環境,或是模擬哪些外部服務。

下一節將說明可用的配置選項。

配置測試應用程式 ​

配置測試應用程式時,您可以:

預設情況下,已配置的測試應用程式會在第一次用戶端呼叫時啟動。 (選用)您可以呼叫 startApplication() 函式手動啟動應用程式。 如果您需要測試應用程式的生命週期事件,這會很有用。

新增應用程式模組 ​

必須透過明確載入或配置環境的方式,將模組載入至測試應用程式中。

明確載入模組 ​

若要手動將模組新增至測試應用程式,請使用 application {} 區塊:

kotlin
package com.example

import io.ktor.client.request.*
import io.ktor.client.statement.*
import io.ktor.http.*
import io.ktor.server.application.Application
import io.ktor.server.testing.*
import kotlin.test.*

class ApplicationTest {
    @Test
    fun testModule1() = testApplication {
        application {
            module1()
            module2()
        }
        val response = client.get("/module1")
        assertEquals(HttpStatusCode.OK, response.status)
        assertEquals("Hello from 'module1'!", response.bodyAsText())
    }

    @Test
    fun testAccessApplicationInstance() = testApplication {
        lateinit var configuredApplication: Application

        application {
            configuredApplication = this
        }

        startApplication()

        // 存取 application 屬性
        val app: Application = application

        // 斷言它是同一個執行個體
        assertSame(configuredApplication, app)
    }
}

從組態檔載入模組 ​

若要從組態檔載入模組,請使用 environment {} 區塊為測試指定組態檔:

kotlin
@Test
fun testHello() = testApplication {
    environment {
        config = ApplicationConfig(
            "application-custom.conf"
        )
    }
}

當您需要在測試期間模擬不同環境或使用自訂配置設定時,此方法非常實用。

存取應用程式執行個體 ​

在 application {} 區塊內部,您可以存取正在配置的 Application 執行個體:

kotlin
testApplication {
    application {
        val app: Application = this
        // 在此處與應用程式執行個體進行互動
    }
}

此外,testApplication 作用域公開了 application 屬性,該屬性會傳回測試所使用的同一個 Application 執行個體。這允許您直接從測試程式碼檢查應用程式或與其互動。

kotlin
package com.example

import io.ktor.client.request.*
import io.ktor.client.statement.*
import io.ktor.http.*
import io.ktor.server.application.Application
import io.ktor.server.testing.*
import kotlin.test.*

class ApplicationTest {
    @Test
    fun testModule1() = testApplication {
        application {
            module1()
            module2()
        }
        val response = client.get("/module1")
        assertEquals(HttpStatusCode.OK, response.status)
        assertEquals("Hello from 'module1'!", response.bodyAsText())
    }

    @Test
    fun testAccessApplicationInstance() = testApplication {
        lateinit var configuredApplication: Application

        application {
            configuredApplication = this
        }

        startApplication()

        // 存取 application 屬性
        val app: Application = application

        // 斷言它是同一個執行個體
        assertSame(configuredApplication, app)
    }
}

在呼叫 startApplication() 或發送第一個用戶端請求之前存取 application 屬性會傳回 Application 執行個體,但此時應用程式可能尚未啟動。

新增路由 ​

您可以使用 routing {} 區塊將路由新增至測試應用程式。這種方法非常適合用於在不載入完整模組的情況下測試路由,或是新增測試專用的端點。

以下範例新增了 /login-test 端點,用於在測試中初始化使用者工作階段:

kotlin
fun testHello() = testApplication {
    routing {
        get("/login-test") {
            val session = UserSession("xyzABC123", "abc123")
            call.sessions.set(session)
        }
    }
}

如需完整的測試範例,請參閱 auth-oauth-google。

自訂環境 ​

若要為測試應用程式配置自訂環境,請使用 environment {} 函式。

例如,從 test/resources 資料夾載入組態檔:

kotlin
@Test
fun testHello() = testApplication {
    environment {
        config = ApplicationConfig(
            "application-custom.conf"
        )
    }
}

或者,您可以透過程式設計方式使用 MapApplicationConfig 來提供配置屬性。當您需要在應用程式啟動前存取應用程式配置時,這很有用。

kotlin
@Test
fun testDevEnvironment() = testApplication {
    environment {
        config = MapApplicationConfig("ktor.environment" to "dev")
    }
}

模擬外部服務 ​

您可以使用 externalServices {} 函式來模擬外部服務。在其區塊內,針對每個要模擬的服務使用 hosts() {} 函式。在 hosts() {} 區塊中,您可以透過定義路由和安裝外掛程式,來配置一個作為模擬服務的 Application。

以下範例模擬來自 Google API 的 JSON 回應:

kotlin
@Test
fun testHello() = testApplication {
    externalServices {
        hosts("https://www.googleapis.com") {
            install(
                io.ktor.server.plugins.contentnegotiation
                    .ContentNegotiation
            ) {
                json()
            }
            routing {
                get("oauth2/v2/userinfo") {
                    val info =
                        UserInfo("1", "JetBrains", "", "")
                    call.respond(info)
                }
            }
        }
    }
}

如需完整的測試範例,請參閱 auth-oauth-google。

配置用戶端 ​

testApplication {} 函式透過 client 屬性提供已配置的 HTTP 用戶端。若要自訂用戶端並安裝其他外掛程式,請使用 createClient {} 函式。

例如,您可以安裝 ContentNegotiation 外掛程式,以在 POST/PUT 請求中傳送 JSON 資料:

kotlin
@Test
fun testPostCustomer() = testApplication {
    application {
        main()
    }
    client = createClient {
        install(ContentNegotiation) {
            json()
        }
    }
}

發送請求 ​

使用配置好的用戶端來發送請求並接收回應。

以下範例測試處理 POST 請求的 /customer 端點:

kotlin
@Test
fun testPostCustomer() = testApplication {
    application {
        main()
    }
    client = createClient {
        install(ContentNegotiation) {
            json()
        }
    }
    val response = client.post("/customer") {
        contentType(ContentType.Application.Json)
        setBody(Customer(3, "Jet", "Brains"))
    }
}

如需完整的測試範例,請參閱 json-kotlinx。

斷言結果 ​

收到回應後,您可以使用來自 kotlin.test 程式庫的斷言來驗證結果:

kotlin
@Test
fun testPostCustomer() = testApplication {
    application {
        main()
    }
    client = createClient {
        install(ContentNegotiation) {
            json()
        }
    }
    val response = client.post("/customer") {
        contentType(ContentType.Application.Json)
        setBody(Customer(3, "Jet", "Brains"))
    }
    assertEquals("Customer stored correctly", response.bodyAsText())
    assertEquals(HttpStatusCode.Created, response.status)
}

測試 POST/PUT 請求 ​

傳送表單資料 ​

若要在測試請求中傳送表單資料,請使用 header() 與 setBody() 函式設定 Content-Type 標頭及請求內文。

鍵/值配對 ​

若要在 POST 請求中傳送鍵/值表單參數,請將 Content-Type 標頭設為 application/x-www-form-urlencoded,並使用 formUrlEncode() 函式對參數進行編碼:

kotlin
package formparameters

import io.ktor.client.request.*
import io.ktor.client.statement.*
import io.ktor.http.*
import io.ktor.server.testing.*
import kotlin.test.*

class ApplicationTest {
    @Test
    fun testPost() = testApplication {
        application {
            main()
        }
        val response = client.post("/signup") {
            header(HttpHeaders.ContentType, ContentType.Application.FormUrlEncoded.toString())
            setBody(listOf("username" to "JetBrains", "email" to "example@jetbrains.com", "password" to "foobar", "confirmation" to "foobar").formUrlEncode())
        }
        assertEquals("The 'JetBrains' account is created", response.bodyAsText())
    }
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.html.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import kotlinx.html.*

fun Application.main() {
    routing {
        post("/signup") {
            val formParameters = call.receiveParameters()
            val username = formParameters["username"].toString()
            call.respondText("The '$username' account is created")
        }
    }
}

如需完整的程式碼範例,請參閱 post-form-parameters。

Multipart 表單資料 ​

您可以使用 multipart/form-data 內容類型來建置 multipart 表單資料並測試檔案上傳:

kotlin
package uploadfile

import io.ktor.client.request.*
import io.ktor.client.request.forms.*
import io.ktor.client.statement.*
import io.ktor.http.*
import io.ktor.server.testing.*
import org.junit.*
import java.io.*
import kotlin.test.*
import kotlin.test.Test

class ApplicationTest {
    @Test
    fun testUpload() = testApplication {
        application {
            main()
        }
        val boundary = "WebAppBoundary"
        val response = client.post("/upload") {
            setBody(
                MultiPartFormDataContent(
                    formData {
                        append("description", "Ktor logo")
                        append("image", File("ktor_logo.png").readBytes().toString(), Headers.build {
                            append(HttpHeaders.ContentType, "image/png")
                            append(HttpHeaders.ContentDisposition, "filename=\"ktor_logo.png\"")
                        })
                    },
                    boundary,
                    ContentType.MultiPart.FormData.withParameter("boundary", boundary)
                )
            )
        }
        assertEquals("Ktor logo is uploaded to 'uploads/ktor_logo.png'", response.bodyAsText(Charsets.UTF_8))
    }

    @After
    fun deleteUploadedFile() {
        File("uploads/ktor_logo.png").delete()
    }
}
kotlin
package uploadfile

import io.ktor.server.application.*
import io.ktor.http.content.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import io.ktor.util.cio.*
import io.ktor.utils.io.*
import java.io.File

fun Application.main() {
    routing {
        post("/upload") {
            var fileDescription = ""
            var fileName = ""
            val multipartData = call.receiveMultipart(formFieldLimit = 1024 * 1024 * 100)

            multipartData.forEachPart { part ->
                when (part) {
                    is PartData.FormItem -> {
                        fileDescription = part.value
                    }

                    is PartData.FileItem -> {
                        fileName = part.originalFileName as String
                        val file = File("uploads/$fileName")
                        part.provider().copyAndClose(file.writeChannel())
                    }

                    else -> {}
                }
                part.dispose()
            }

            call.respondText("$fileDescription is uploaded to 'uploads/$fileName'")
        }
    }
}

如需完整的程式碼範例,請參閱 upload-file。

傳送 JSON 資料 ​

若要在 POST/PUT 請求中序列化與反序列化 JSON 資料,請在新的用戶端中安裝 ContentNegotiation 外掛程式。

在請求內部,您可以使用 contentType() 函式指定 Content-Type 標頭,並使用 setBody() 函式指定請求內文。

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.client.request.*
import io.ktor.client.statement.*
import io.ktor.http.*
import io.ktor.serialization.kotlinx.json.*
import io.ktor.server.testing.*
import kotlin.test.*

class CustomerTests {
    @Test
    fun testPostCustomer() = testApplication {
        application {
            main()
        }
        client = createClient {
            install(ContentNegotiation) {
                json()
            }
        }
        val response = client.post("/customer") {
            contentType(ContentType.Application.Json)
            setBody(Customer(3, "Jet", "Brains"))
        }
        assertEquals("Customer stored correctly", response.bodyAsText())
        assertEquals(HttpStatusCode.Created, response.status)
    }
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.plugins.contentnegotiation.*
import io.ktor.http.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import io.ktor.serialization.kotlinx.json.*
import kotlinx.serialization.*
import kotlinx.serialization.json.*
import io.ktor.server.util.getValue

@Serializable
data class Customer(val id: Int, val firstName: String, val lastName: String)

    install(ContentNegotiation) {
        json(Json {
            prettyPrint = true
            isLenient = true
        })
    }

        post("/customer") {
            val customer = call.receive<Customer>()
            customerStorage.add(customer)
            call.respondText("Customer stored correctly", status = HttpStatusCode.Created)
        }
    }

如需完整的範例,請參閱 json-kotlinx。

在測試期間保留 Cookie ​

若要在多次請求之間保留 Cookie,請在新的用戶端中安裝 HttpCookies 外掛程式。

在以下範例中,由於 Cookie 得以保留,重新載入計數會在每次請求後遞增:

kotlin
package cookieclient

import io.ktor.client.plugins.cookies.*
import io.ktor.client.request.*
import io.ktor.client.statement.*
import io.ktor.server.testing.*
import kotlin.test.*

class ApplicationTest {
    @Test
    fun testRequests() = testApplication {
        application {
            main()
        }
        val client = createClient {
            install(HttpCookies)
        }

        val loginResponse = client.get("/login")
        val response1 = client.get("/user")
        assertEquals("Session ID is 123abc. Reload count is 1.", response1.bodyAsText())
        val response2 = client.get("/user")
        assertEquals("Session ID is 123abc. Reload count is 2.", response2.bodyAsText())
        val response3 = client.get("/user")
        assertEquals("Session ID is 123abc. Reload count is 3.", response3.bodyAsText())
        val logoutResponse = client.get("/logout")
        assertEquals("Session doesn't exist or is expired.", logoutResponse.bodyAsText())
    }
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import io.ktor.server.sessions.*
import io.ktor.util.*
import kotlinx.serialization.Serializable

@Serializable
data class UserSession(val id: String, val count: Int)

fun Application.main() {
    install(Sessions) {
        val secretEncryptKey = "00112233445566778899aabbccddeeff".hexToByteArray()
        val secretSignKey = "6819b57a326945c1968f45236589".hexToByteArray()
        cookie<UserSession>("user_session") {
            cookie.path = "/"
            cookie.maxAgeInSeconds = 10
            transform(SessionTransportTransformerEncrypt(secretEncryptKey, secretSignKey))
        }
    }
    routing {
        get("/login") {
            call.sessions.set(UserSession(id = "123abc", count = 0))
            call.respondRedirect("/user")
        }

        get("/user") {
            val userSession = call.sessions.get<UserSession>()
            if (userSession != null) {
                call.sessions.set(userSession.copy(count = userSession.count + 1))
                call.respondText("Session ID is ${userSession.id}. Reload count is ${userSession.count}.")
            } else {
                call.respondText("Session doesn't exist or is expired.")
            }
        }

如需完整的範例,請參閱 session-cookie-client.

測試 HTTPS ​

若要測試 HTTPS 端點,請使用 URLBuilder.protocol 屬性來設定請求協定:

kotlin
package com.example

import io.ktor.client.request.*
import io.ktor.client.statement.*
import io.ktor.http.*
import io.ktor.server.testing.*
import kotlin.test.*

class ApplicationTest {
    @Test
    fun testRoot() = testApplication {
        application {
            module()
        }
        val response = client.get("/") {
            url {
                protocol = URLProtocol.HTTPS
            }
        }
        assertEquals("Hello, world!", response.bodyAsText())
    }
}

如需完整的範例,請參閱 ssl-engine-main。

測試 WebSocket ​

您可以使用 WebSockets 用戶端外掛程式來測試 WebSocket 對話:

kotlin
package com.example

import io.ktor.client.plugins.websocket.*
import io.ktor.websocket.*
import io.ktor.server.testing.*
import kotlin.test.*

class ModuleTest {
    @Test
    fun testConversation() {
        testApplication {
            application {
                module()
            }
            val client = createClient {
                install(WebSockets)
            }

            client.webSocket("/echo") {
                val greetingText = (incoming.receive() as? Frame.Text)?.readText() ?: ""
                assertEquals("Please enter your name", greetingText)

                send(Frame.Text("JetBrains"))
                val responseText = (incoming.receive() as Frame.Text).readText()
                assertEquals("Hi, JetBrains!", responseText)
            }
        }
    }
}

使用 HttpClient 進行端到端測試 ​

您可以使用 Ktor HTTP 用戶端對伺服器應用程式進行完整的端到端測試。

在下方的範例中,HTTP 用戶端會向 TestServer 發送測試請求:

kotlin
import e2e.TestServer
import io.ktor.client.*
import io.ktor.client.call.*
import io.ktor.client.request.*
import io.ktor.client.statement.*
import kotlinx.coroutines.runBlocking
import org.junit.Assert.assertEquals
import org.junit.Test

class EmbeddedServerTest: TestServer() {
    @Test
    fun rootRouteRespondsWithHelloWorldString(): Unit = runBlocking {
        val response: String = HttpClient().get("http://localhost:8080/").body()
        assertEquals("Hello, world!", response)
    }
}

如需完整的端到端測試範例,請參閱 embedded-server 與 e2e。