Ktor Serverでのテスト
必要な依存関係: io.ktor:ktor-server-test-host, org.jetbrains.kotlin:kotlin-test
Ktorは、実際のWebサーバーを起動したりソケットにバインドしたりすることなく、アプリケーション呼び出しを直接実行するテストエンジンを提供します。リクエストは内部で処理されるため、フルサーバーを実行する場合と比較して、テストがより高速かつ高信頼になります。
依存関係の追加
Ktorサーバーアプリケーションをテストするには、ビルドスクリプトに以下の依存関係を含めます。
ktor-server-test-host依存関係はテストエンジンを提供します:kotlintestImplementation("io.ktor:ktor-server-test-host:$ktor_version")groovytestImplementation "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依存関係はアサーションを実行するためのユーティリティ関数セットを提供します:kotlintestImplementation("org.jetbrains.kotlin:kotlin-test:$kotlin_version")groovytestImplementation "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アプリケーションをテストできます。典型的なワークフローには以下のステップが含まれます。
testApplication {}を使用してテストを定義します。- アプリケーションのテストインスタンスを設定して実行します。
- 必要に応じて、HTTPクライアントを設定します。
- クライアントを使用してテストアプリケーションへHTTPリクエストを送信し、レスポンスを受信します。
- ステータスコード、ヘッダー、ボディコンテンツなどを含め、
kotlin.testのアサーションを使用してレスポンスを検証します。
以下の例では、GET / リクエストに対してプレーンテキストで応答するシンプルなKtorアプリケーションをテストします。
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())
}
}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テストクラスを作成します。
- プロジェクト内の
src/test/kotlinディレクトリを見つけるか、作成します。 - 新しいKotlinファイル(例:
ApplicationTest.kt)を作成します。 - テストを含むKotlinクラスを定義します:kotlin
class ApplicationTest { // ここにテスト関数を記述します } @Testアノテーションが付いたテスト関数を追加します。テストの内部でtestApplication {}関数を使用して、テスト環境でアプリケーションを実行します:kotlinclass ApplicationTest { @Test fun testRoot() = testApplication { // ... } }
testApplication {} 関数は、Ktorでのサーバーテストのエントリポイントです。隔離されたテスト環境を作成し、実際のWebサーバーを起動せずにアプリケーションを実行し、リクエストの送信やレスポンスのアサーションを行うための事前設定されたHTTPクライアントを提供します。
testApplication {} ブロック内では、ロードするモジュール、公開するルート、環境のセットアップ方法、モックする外部サービスなど、テストアプリケーションがどのように動作するかを設定します。
次のセクションでは、利用可能な設定オプションについて説明します。
テストアプリケーションの設定
テストアプリケーションを設定する際、以下のことが可能です。
デフォルトでは、設定されたテストアプリケーションは最初のクライアント呼び出し時に起動します。 オプションとして、startApplication() 関数を呼び出して手動でアプリケーションを起動することもできます。 これは、アプリケーションのライフサイクルイベントをテストする必要がある場合に便利です。
アプリケーションモジュールの追加
モジュールは、明示的にロードするか、環境を設定するかのいずれかによって、テストアプリケーションにロードする必要があります。
明示的なモジュールのロード
テストアプリケーションに手動でモジュールを追加するには、application {} ブロックを使用します:
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 {} ブロックを使用してテスト用の設定ファイルを指定します:
@Test
fun testHello() = testApplication {
environment {
config = ApplicationConfig(
"application-custom.conf"
)
}
}この方法は、テスト中にさまざまな環境を模倣したり、カスタム設定を使用したりする必要がある場合に便利です。
アプリケーションインスタンスへのアクセス
application {} ブロック内では、設定中の Application インスタンスにアクセスできます:
testApplication {
application {
val app: Application = this
// ここでアプリケーションインスタンスを操作します
}
}さらに、testApplication スコープは application プロパティを公開しており、これはテストで使用されているのと同じ Application インスタンスを返します。これにより、テストコードからアプリケーションを直接調査または操作できます。
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 エンドポイントを追加します:
fun testHello() = testApplication {
routing {
get("/login-test") {
val session = UserSession("xyzABC123", "abc123")
call.sessions.set(session)
}
}
}完全なテスト例については、auth-oauth-google を参照してください。
環境のカスタマイズ
テストアプリケーションにカスタム環境を設定するには、environment {} 関数を使用します。
例えば、test/resources フォルダから設定ファイルをロードするには:
@Test
fun testHello() = testApplication {
environment {
config = ApplicationConfig(
"application-custom.conf"
)
}
}あるいは、MapApplicationConfig を使用してプログラムから設定プロパティを提供することもできます。これは、アプリケーションが起動する前にアプリケーション設定にアクセスする必要がある場合に役立ちます。
@Test
fun testDevEnvironment() = testApplication {
environment {
config = MapApplicationConfig("ktor.environment" to "dev")
}
}外部サービスのモック
externalServices {} 関数を使用して、外部サービスをシミュレートできます。そのブロック内で、モックしたい各サービスに対して hosts() {} 関数を使用します。hosts() {} ブロック内では、ルートを定義したりプラグインをインストールしたりすることで、モックサービスとして機能する Application を設定できます。
以下の例では、Google API からの JSON レスポンスをシミュレートします:
@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 {} 関数を使用します。
例えば、POST/PUT リクエストでJSONデータを送信するために、ContentNegotiation プラグインをインストールできます:
@Test
fun testPostCustomer() = testApplication {
application {
main()
}
client = createClient {
install(ContentNegotiation) {
json()
}
}
}リクエストの送信
設定されたクライアントを使用して、リクエストを送信し、レスポンスを受信します。
以下の例では、POST リクエストを処理する /customer エンドポイントをテストします:
@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 ライブラリのアサーションを使用して結果を検証できます:
@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() 関数を使用してパラメータをエンコードします:
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())
}
}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/form-data コンテンツタイプを使用してマルチパートフォームデータを構築し、ファイルのアップロードをテストできます:
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()
}
}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() 関数を使用してリクエストボディを指定できます。
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)
}
}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が保持されるため、リクエストごとにリロード回数が増加します:
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())
}
}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 プロパティを使用してリクエストプロトコルを設定します:
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通信をテストできます:
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 に対してテストリクエストを行います:
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 を参照してください。
