Kotlin Wiremock

Here's a handy Kotline library for stubbing WireMock expectations.

Marcin Zioło

Jul. 28, 20 · Tutorial

11.4K Views

WireMock is a popular library for stubbing web services. It runs an HTTP server that acts as an actual web service. We just set up expectations and run the server.

In this tutorial, we will present the kotlin-wiremock library that provides a nice domain-specific language for stubbing WireMock expectations.

Getting Started

The first step is adding dependencies.

Maven

    XML
   
xxxxxxxxxx

<dependency>
    <groupId>com.marcinziolo</groupId>
    <artifactId>kotlin-wiremock</artifactId>
    <version>1.0.0</version>
    <scope>test</scope>
</dependency>

Gradle

    Kotlin
   
xxxxxxxxxx

testImplementation("com.marcinziolo:kotlin-wiremock:version")

And now we can use kotlin-wiremock. Let's see the JUnit 4 example.

    Kotlin
   
xxxxxxxxxx

import com.github.tomakehurst.wiremock.junit.WireMockRule
import io.restassured.module.kotlin.extensions.Then
import io.restassured.module.kotlin.extensions.When
import org.hamcrest.Matchers.equalTo
import org.junit.Rule
import org.junit.Test
import java.net.ServerSocket
class JUnit4ExampleTest {
    val port = findRandomPort()
    val url = "http://localhost:$port"
    @Rule
    @JvmField
    var wiremock: WireMockRule = WireMockRule(port)
    @Test
    fun `url matching`() {
        wiremock.get {
            url like  "/users/.*"
        } returns  {
            header = "Content-Type" to "application/json"
            statusCode = 200
            body = """
            {
              "id": 1,
              "name": "Bob"
            }
            """
        }
        assertBobSuccess()
    }
    private fun assertBobSuccess() {
        When {
            get("$url/users/1")
        } Then {
            statusCode(200)
            body("id", equalTo(1))
            body("name", equalTo("Bob"))
        }
    }
    fun findRandomPort(): Int {
        ServerSocket(0).use { socket -> return socket.localPort }
    }
}

Features

One of the basic features is url matching. Let's see an example: when calling a server with URL equal /users/1, the server returns a JSON body with Bob's response.

    Kotlin
   
          x
         
wiremock.get {
  url equalTo "/users/1"
} returns {
  header = "Content-Type" to "application/json"
  statusCode = 200
  body = """{"id": 1,"name": "Bob"}"""
}

We can also use regular expressions for matching url. Notice that we can use method returnsJson so we don't need to specify the Conte-Type header manually.

    Kotlin
   
xxxxxxxxxx

wiremock.get {
  url like "/users/.*"
} returnsJson {
  body = """{"id": 1,"name": "Bob"}"""
}

Let's see how we can stub the post request. We return bobResponse only when request JSON body fulfills the following criteria:

id key equalTo 1
isAdmin key equalTo true
points equalTo 3.0
data object contains name key which starts with Bob string.

As you can see we have a full spectrum of solutions for mathing the request body. Note that the library gives us the possibility to check value types(string, integer, float, boolean).

    Kotlin
   
xxxxxxxxxx

val bobResponse: SpecifyResponse = { body = """{"id": 1,"name": "Bob"}""" }
wiremock.post {
  url equalTo "/users"
    body contains "id" equalTo 1
    body contains "isAdmin" equalTo true
    body contains "points" equalTo 3.0
    body contains "data.name" like "Bob.*"
} returnsJson bobResponse

We can also check headers and query params:

    Kotlin
   
xxxxxxxxxx

wiremock.post {
    headers contains "User-Agent" like "Firefox.*"
    queryParams contains "page" equalTo "1" 
}

Look how priorities work, when we send Authorization header then the response is 200 otherwise the server replies with 403.

    Kotlin
   
xxxxxxxxxx

wiremock.post {
    url equalTo "/test"
    priority = 2
} returnsJson  {
    statusCode = 403
}
wiremock.post {
    url equalTo "/test"
    headers contains "Authorization"
    priority = 1
} returnsJson  {
    statusCode = 200
}

We can even simulate delays.

    Kotlin
   
xxxxxxxxxx

wiremock.post {
    url equalTo "/users"
} returnsJson {
    delay fixedMs 100
    //or gaussian distribution
    delay medianMs 100 sigma 0.1
}

We can come up with more sophisticated scenarios. The first request returns bobResponse but we set flag toState to Alice. So the second response returns aliceResponse,

    Java
   
xxxxxxxxxx

wiremock.post {
     url equalTo "/users"
 } returnsJson bobResponse and {
     toState = "Alice"
 }
 wiremock.post {
     url equalTo "/users"
     whenState = "Alice"
 } returnsJson aliceResponse and {
     clearState = true
 }

Summary

All features presented in this tutorial can be achieved via wireMock API.

    Java
   
x

stubFor(any(urlPathEqualTo("/everything"))
  .withHeader("Accept", containing("json"))
  .withQueryParam("search_term", equalTo("WireMock"))
  .withRequestBody(matchingJsonPath("$.things[?(@.name =~ /Required.*/i')]"))
  .willReturn(aResponse()
              .withHeader("Content-Type", "text/plain")
              .withBody("Hello world!")));

But doesn't it look way better in Kotlin Wiremock DSL?

    Kotlin
   
xxxxxxxxxx

wiremock.get {
  url equalTo "/everything"
  header contains "Accept" contains "json"
  queryParams contains "search_term" equalTo "WireMock"
  body contains "things.name" like "Required.*"
} returns {
  header = "Content-Type" to "text/plain"
  body = "Hello world"
}

More examples can be found here:

Kotlin (programming language)

Opinions expressed by DZone contributors are their own.