Testing Http Client (MockEngine)

Ktor exposes a MockEngine for the HttpClient. This engine allows simulating HTTP calls without actually connecting to the endpoint. It allows to set a code block, that can handle the request and generates a response.

This engine is defined in the class io.ktor.client.engine.mock.MockEngine in the artifact io.ktor:ktor-client-mock:$ktor_version,io.ktor:ktor-client-mock-jvm:$ktor_version,io.ktor:ktor-client-mock-js:$ktor_version,io.ktor:ktor-client-mock-native:$ktor_version. 

  1. dependencies {
  2.     api "io.ktor:ktor-client-mock:$ktor_version"
  3.     api "io.ktor:ktor-client-mock-jvm:$ktor_version"
  4.     api "io.ktor:ktor-client-mock-js:$ktor_version"
  5.     api "io.ktor:ktor-client-mock-native:$ktor_version"
  6. }
  1. dependencies {
  2.     testImplementation("io.ktor:ktor-client-mock:$ktor_version")
  3.     testImplementation("io.ktor:ktor-client-mock-jvm:$ktor_version")
  4.     testImplementation("io.ktor:ktor-client-mock-js:$ktor_version")
  5.     testImplementation("io.ktor:ktor-client-mock-native:$ktor_version")
  6. }
  1. <project>
  2.     ...
  3.     <dependencies>
  4.         <dependency>
  5.             <groupId>io.ktor</groupId>
  6.             <artifactId>ktor-client-mock</artifactId>
  7.             <version>${ktor.version}</version>
  8.             <scope>test</scope>
  9.         </dependency>
  10.         <dependency>
  11.             <groupId>io.ktor</groupId>
  12.             <artifactId>ktor-client-mock</artifactId>
  13.             <version>${ktor.version}</version>
  14.             <scope>test</scope>
  15.         </dependency>
  16.         <dependency>
  17.             <groupId>io.ktor</groupId>
  18.             <artifactId>ktor-client-mock</artifactId>
  19.             <version>${ktor.version}</version>
  20.             <scope>test</scope>
  21.         </dependency>
  22.         <dependency>
  23.             <groupId>io.ktor</groupId>
  24.             <artifactId>ktor-client-mock</artifactId>
  25.             <version>${ktor.version}</version>
  26.             <scope>test</scope>
  27.         </dependency>
  28.     </dependencies>
  29. </project>

Usage

The usage is straightforward: the MockEngine class has a method addHandler in MockEngineConfig, that receives a block/callback that will handle the request. This callback receives an HttpRequest as a parameter, and must return a HttpResponseData. There are many helper methods to construct the response.

Full API description and list of helper methods could be found here.

A sample illustrating this:

  1. val client = HttpClient(MockEngine) {
  2.     engine {
  3.         addHandler { request ->
  4.             when (request.url.fullUrl) {
  5.                 "https://example.org/" -> {
  6.                     val responseHeaders = headersOf("Content-Type" to listOf(ContentType.Text.Plain.toString()))
  7.                     respond("Hello, world", headers = responseHeaders)
  8.                 }
  9.                 else -> error("Unhandled ${request.url.fullUrl}")
  10.             }
  11.         }
  12.     }
  13. }
  15. private val Url.hostWithPortIfRequired: String get() = if (port == protocol.defaultPort) host else hostWithPort
  16. private val Url.fullUrl: String get() = "${protocol.name}://$hostWithPortIfRequired$fullPath"