Add dependencies

To test a Ktor server application, include the following dependencies in your build script:

• The ktor-server-test-host dependency provides the testing engine:

  testImplementation("io.ktor:ktor-server-test-host:$ktor_version")

  testImplementation "io.ktor:ktor-server-test-host:$ktor_version"

  <dependency> <groupId>io.ktor</groupId> <artifactId>ktor-server-test-host-jvm</artifactId> <version>${ktor_version}</version> </dependency>

• The kotlin-test dependency provides a set of utility functions for performing assertions:

  testImplementation("org.jetbrains.kotlin:kotlin-test:$kotlin_version")

  testImplementation "org.jetbrains.kotlin:kotlin-test:$kotlin_version"

  <dependency> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-test</artifactId> <version>${kotlin_version}</version> </dependency>

Testing overview

You can test a Ktor application using the testApplication {} function and the provided HTTP client. A typical workflow includes the following steps:

1. Define a test using testApplication {}.

2. Configure and run a test instance of your application.

3. Optionally, configure the HTTP client.

4. Use the client to make HTTP requests to your test application and receive responses.

5. Verify responses using assertions from kotlin.test, including status codes, headers, and body content.

The following example tests a simple Ktor application that responds to GET / requests with plain text:

Set up a JUnit test class

Before writing tests for your Ktor application, create a test file and a JUnit test class.

The testApplication {} function is the entry point for server testing in Ktor. It creates an isolated test environment, runs your application without starting a real web server, and provides a preconfigured HTTP client for making requests and asserting responses.

Inside the testApplication {} block, you configure how the test application should behave, such as which modules to load, which routes to expose, how the environment is set up, or which external services are mocked.

The following section describes the available configuration options.

Configure a test application

When configuring a test application, you can:

• Add application modules

• Add routes

• Customize the environment

• Mock external services

Configure a client

The testApplication {} function provides a configured HTTP client through the client property. To customize the client and install additional plugins, use the createClient {} function.

For example, you can install the ContentNegotiation plugin to send JSON data in a POST/PUT request:

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

Make a request

Use the configured client to make requests and receive responses.

The following example tests the /customer endpoint that handles POST requests:

@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")) } }

Assert results

After receiving a response, you can verify the results using assertions from the kotlin.test library:

@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) }

Test POST/PUT requests

Preserve cookies during testing

To preserve cookies between requests, install the HttpCookies plugin to a new client.

In the following example, the reload count increases after each request due to cookies being preserved:

Test HTTPS

To test an HTTPS endpoint, set the request protocol using the URLBuilder.protocol property:

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

Test WebSockets

You can test WebSocket conversations by using the WebSockets client plugin:

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) } } } }

End-to-end testing with HttpClient

You can use the Ktor HTTP client for a full end-to-end testing of your server application.

In the example below, the HTTP client makes a test request to the 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) } }