G'day:
One of my tasks @ work is to check out how to test a web service. I started with this yesterday's article: Kotlin: getting the khttp library installed and running… then… getting rid of it and using something else, but that was justa "proof of concept" of making an HTTP call, and examining its results. Today I'm gonna write the actual tests we need for the interface for a web service. Note: I still don't know enough about Ktor to create a web service with it, so I'm gonna fall back to using CFML for that end of things. I'm not gonna bother with the code for that here; the tests will demonstrate whether or not the web service is fulfilling its contract. But I will be TDDing this. Currently I have zero tests and zero code to test. Let's get on with it.
It should return a 200-OK on the root URI on a valid request
fun `It should return a 200-OK on the root URI on a valid request`() {
runBlocking {
HttpClient().use { client ->
val response = client.get(webserviceUrl)
response.status shouldBe HttpStatusCode.OK
}
}
}
NB: I will only comment if there's something note-worthy or not obvious. All tests will initially fail until I implement the relevant bit of the web service, eg:
expected:<200 OK> but was:<404 Not Found> Expected :200 OK Actual :404 Not Found
It should return a 406-NOT-ACCEPTABLE and suggest the expected type if the Accepts header is not application/json
@Test
fun `It should return a 406-NOT-ACCEPTABLE and suggest the expected type if the Accepts header is not application-json`() {
runBlocking {
HttpClient().use { client ->
val response = client.get(webserviceUrl) {
header("Accept", "text/plain")
}
response.status shouldBe HttpStatusCode.NotAcceptable
response.body() as String shouldBe """["application/json"]"""
}
}
}
Note: It's a Kotlin/JVM limitation that I have to use application-json rather than application/json in the method name there. See Why Kotlin does not allow slash in identifiers, which in turn points the reader to Java Virtual Machine Specification › Chapter 4. The class File Format:
4.2.2. Unqualified Names
Names of methods, fields, local variables, and formal parameters are stored as unqualified names. An unqualified name must contain at least one Unicode code point and must not contain any of the ASCII characters . ; [ / (that is, period or semicolon or left square bracket or forward slash).
When I initially just referenced response.body() shouldBe """["application/json"]""" Kotlin was saying "Not enough information to infer type variable", and after some googling I landed on Type checks and casts › "Unsafe" cast operator, which explains that as String thing I have there.
Also note I needed to update the 200-OK test to pass the correct Accept header.
It returns an array of Numbers as a JSON array
This one was a bit trickier, but the docs were reasonably helpful, and I'm pleased with the outcome.
@Test
fun `It returns an array of Numbers as a JSON array`() {
@Serializable
data class Number(val id: Int, val en: String, val mi: String)
runBlocking {
HttpClient() {
install(ContentNegotiation) {
json()
}
}.use { client ->
val response = client.get(webserviceUrl) {
header("Accept", "application/json")
}
response.status shouldBe HttpStatusCode.OK
response.body() as List<Number> shouldBe listOf(
Number(1, "one", "tahi"),
Number(2, "two", "rua"),
Number(3, "three", "toru"),
Number(4, "four", "wha")
)
}
}
}
I had guessed that there'd be a way to deliver objects straight to the app from an HTTP request, and a quick google set me on the right path here, landing me on these docs: Content negotiation and serialization. What's super helpful in these docs as they link through to examples of everything (including the build.gradle.kt file, as I needed to add some dependencies - see further down), eg: ktor-documentation/codeSnippets/snippets/client-json-kotlinx/src/main/kotlin/com/example/Application.kt and ktor-documentation/codeSnippets/snippets/client-json-kotlinx/build.gradle.kts. I just followed those and changed the bits I needed to change.
Steps:
- tell the client that I'm gonna expect it to work out what the content represents (boilerplate).
- Create a data class that the client will use to deserialize the data as. NB: it needs to be tagged as being serializable, because well: that's what we're doing here.
- Specify that type - or in this case a list of that type - as the body value.
Done.
I will admit than initially I thought I had messed-up because instead of getting a "nup, it's not a list of Numbers" in my failing test, I got this monstrousity:
io.ktor.client.call.NoTransformationFoundException: No transformation found: class io.ktor.utils.io.ByteBufferChannel -> class kotlin.collections.List
But it turns out that just means "um… yer request ain't returning JSON". Which it indeed was not. Once I got it to return something (anything) and the correct content-type, I got a more on-point error:
Expected start of the array '[', but had 'EOF' instead at path: $ JSON input: ""
And from there I tweaked the web service to return a coupla wrong things to see how Ktor reported on deserialization failures, and it was all helpful.
All the examples I saw for this was only deserializing one object, so I was slightly cautious as to how to deal with a JSON array, but I took a punt on just specifying response.body() as List<Number>, thinking Ktor's probably clever enough to expect this sort of thing, and - lo - it did. Nice one.
As I mentioned above, I also had to tweak the dependencies and plugins a bit (build.gradle.kts):
plugins {
kotlin("jvm") version "1.7.10"
kotlin("plugin.serialization").version("1.7.10")
application
}
// …
dependencies {
// …
implementation("io.ktor:ktor-client-core:$ktorVersion")
implementation("io.ktor:ktor-client-cio:$ktorVersion")
implementation("io.ktor:ktor-client-content-negotiation:$ktorVersion")
implementation("io.ktor:ktor-serialization-kotlinx-json:$ktorVersion")
// …
}
It will accept a POST request of an object as JSON and return the same object as confirmation, and its URL
This was really straight-forward, having done all the hard-bit in the previous one:
@Test
fun `It will accept a POST request of an object as JSON and return the same object as confirmation, and its URL`() {
val five = Number(5, "five", "rima")
runBlocking {
HttpClient() {
install(ContentNegotiation) {
json()
}
}.use { client ->
val response = client.post(webserviceUrl) {
contentType(ContentType.Application.Json)
setBody(five)
}
response.status shouldBe HttpStatusCode.Created
response.body() as Number shouldBe five
response.headers["Location"] shouldBe "${webserviceUrl}5"
}
}
}
By now there's absolutely nothing "unexpected" in this, I think.
OK that's enough for a Sunday afternoon. This weekend I've managed to work out how to make HTTP requests in my tests, how to set/check headers, response codes and the body of the responses. I've posted an object and received objects back again, letting Ktor handle the (de)serialization.
These tests are only testing the interface of the web webservice, which is fine and an essential part of building a web service. However the next thing on the list is to do end to end tests: check the underlying data store that new objects are being created (cos they absolutely are not at the moment ;-)), and the correct data is being returned, etc. I have no idea how to make a DB call in Kotlin yet. Something for the coming week, I guess.
The code is on GitHub @ /src/test/kotlin/junit/practical/WebServiceTest.kt, and the web stub service I was creating to make the tests pass is this lot: adamcameron/Numbers.cfc.
Righto.
--
Adam
