Ktor provides a special testing engine that doesn't create a web server, doesn't bind to sockets, and doesn't make any real HTTP requests. Instead, it hooks directly into internal mechanisms and processes an application call directly. This results in quicker tests execution compared to running a complete web server for testing.
Add dependencies
To test a server Ktor application, you need to include the following artifacts in the build script:
Use the testApplication function to set up a configured instance of a test application running locally.
Use the Ktor HTTP client instance inside a test application to make a request to your server, receive a response, and make assertions.
The code below demonstrates how to test the most simple Ktor application that accepts GET requests made to the / path and responds with a plain text response.
To test an application, its modules should be loaded to testApplication. Loading modules to testApplication depends on the way used to create a server: by using a configuration file or in code using the embeddedServer function.
Add modules automatically
If you have the application.conf or application.yaml configuration file in the resources folder, testApplication loads all modules and properties specified in the configuration file automatically. To disable the automatic loading of specific modules, you need to:
You can add routes required only in a test application. The example below shows how to add the /login-test endpoint used to initialize a user session in tests:
To build a custom environment for a test application, use the environment function. For example, to use a custom configuration for tests, you can create a custom configuration file in the test/resources folder and load it using the config property:
Another way to specify configuration properties is using MapApplicationConfig. This might be useful if you want to access application configuration before the application starts. The example below shows how to pass MapApplicationConfig to the testApplication function using the config property:
@Test
fun testDevEnvironment() = testApplication {
environment {
config = MapApplicationConfig("ktor.environment" to "dev")
}
}
Mock external services
Ktor allows you to mock external services using the externalServices function. Inside this function, you need to call the hosts function that accepts two parameters:
The hosts parameter accepts URLs of external services.
The block parameter allows you to configure the Application that acts as a mock for an external service. You can configure routing and install plugins for this Application.
The sample below shows how to use externalServices to simulate a JSON response returned by Google API:
The testApplication provides access to an HTTP client with default configuration using the client property. If you need to customize the client and install additional plugins, you can use the createClient function. For example, to send JSON data in a test POST/PUT request, you can install the ContentNegotiation plugin:
fun testPostCustomer() = testApplication {
val client = createClient {
install(ContentNegotiation) {
json()
}
}
}
Step 3: Make a request
To test your application, use the configured client to make a request and receive a response. The example below shows how to test the /customer endpoint that handles POST requests:
fun testPostCustomer() = testApplication {
val client = createClient {
install(ContentNegotiation) {
json()
}
}
val response = client.post("/customer") {
contentType(ContentType.Application.Json)
setBody(Customer(3, "Jet", "Brains"))
}
}
Step 4: Assert results
After receiving a response, you can verify the results by making assertions provided by the kotlin.test library:
To send form data in a test POST/PUT request, you need to set the Content-Type header and specify the request body. To do this, you can use the header and setBody functions, respectively. The examples below show how to send form data using both x-www-form-urlencoded and multipart/form-data types.
x-www-form-urlencoded
A test below from the post-form-parameters example shows how to make a test request with form parameters sent using the x-www-form-urlencoded content type. Note that the formUrlEncode function is used to encode form parameters from a list of key/value pairs.
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 testPost() = testApplication {
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")
}
}
}
multipart/form-data
The code below demonstrates how to build multipart/form-data and test file uploading. You can find the full example here: upload-file.
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 java.io.File
fun Application.main() {
routing {
var fileDescription = ""
var fileName = ""
post("/upload") {
val multipartData = call.receiveMultipart()
multipartData.forEachPart { part ->
when (part) {
is PartData.FormItem -> {
fileDescription = part.value
}
is PartData.FileItem -> {
fileName = part.originalFileName as String
val fileBytes = part.streamProvider().readBytes()
File("uploads/$fileName").writeBytes(fileBytes)
}
else -> {}
}
part.dispose()
}
call.respondText("$fileDescription is uploaded to 'uploads/$fileName'")
}
}
}
Send JSON data
To send JSON data in a test POST/PUT request, you need to create a new client and install the ContentNegotiation plugin that allows serializing/deserializing the content in a specific format. Inside a request, you can specify the Content-Type header using the contentType function and the request body using setBody. The example below shows how to test the /customer endpoint that handles POST requests.
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.*
@Serializable
data class Customer(val id: Int, val firstName: String, val lastName: String)
fun Application.main() {
install(ContentNegotiation) {
json(Json {
prettyPrint = true
isLenient = true
})
}
routing {
post("/customer") {
val customer = call.receive<Customer>()
customerStorage.add(customer)
call.respondText("Customer stored correctly", status = HttpStatusCode.Created)
}
}
}
Preserve cookies during testing
If you need to preserve cookies between requests when testing, you need to create a new client and install the HttpCookies plugin. In a test below from the session-cookie-client example, reload count is increased after each request since cookies are preserved.
import io.ktor.client.plugins.cookies.*
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 testRequests() = testApplication {
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.*
data class UserSession(val id: String, val count: Int)
fun Application.main() {
install(Sessions) {
val secretEncryptKey = hex("00112233445566778899aabbccddeeff")
val secretSignKey = hex("6819b57a326945c1968f45236589")
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.")
}
}
get("/logout") {
call.sessions.clear<UserSession>()
import io.ktor.client.plugins.websocket.*
import io.ktor.server.application.*
import io.ktor.websocket.*
import io.ktor.server.testing.*
import kotlin.test.*
class ModuleTest {
@Test
fun testConversation() {
testApplication {
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
Apart from a testing engine, you can use the Ktor HTTP client for 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)
}
}