DEV Community: Stephen Samuel

Kotest Release 4.3

Stephen Samuel — Sun, 11 Oct 2020 19:44:47 +0000

The Kotest team is pleased to announce the release of Kotest 4.3.0.

This blog covers some of the new features added in this release.
For the full list, see the changelog.

New and improved data driven testing

Kotest has improved its data driven testing support, directly integrating into the framework. This means it will now automatically generate individual test case entries.

As an example, lets test a function that returns true if the input values are valid pythagorean triples.

fun isPythagTriple(a: Int, b: Int, c: Int): Boolean = a * a + b * b == c * c

We start by writing a data class that will hold each row - a set of inputs.

data class PythagTriple(val a: Int, val b: Int, val c: Int)

Next we invoke the function forAll inside a test case, passing in one or more of these data classes, and a
lambda that performs some test logic for a given row.

context("Pythag triples tests") {
    forAll(
       PythagTriple(3, 4, 5),
       PythagTriple(6, 8, 10),
       PythagTriple(8, 15, 17),
       PythagTriple(7, 24, 25)
    ) { (a, b, c) ->
        isPythagTriple(a, b, c) shouldBe true
    }
}

Kotest will automatically generate a test case for each input row, as if you had manually written a seperate test case for each.

For full documentation click here.

EnabledIf annotation on specs

It can be useful to avoid instantiating a spec entirely, and often we can do that via test tags. But if you want to do this with some bespoke code, then the annotation EnabledIf has been added.

Annotate a spec with EnabledIf, passing in a class that extends from EnabledCondition and that condition will be invoked at runtime to determine if the spec should be instantiated. The EnabledCondition implementation must have a zero arg constructor.

For example, lets make a condition that only executes a test if it is midnight.

class EnabledIfMidnight : EnabledCondition {
   override fun enabled(specKlass: KClass<out Spec>): Boolean = LocalTime.now().hour == 0
}

And then attach that to a spec:

@EnabledIf(EnabledIfMidnight::class)
class EnabledIfTest : FunSpec() {
   init {
      test("tis midnight when the witches roam free") {
        // test here
      }
   }
}

TestCase severity

Test case can be conditionally executed via test tags, and now also by severity levels. The levels are BLOCKER, CRITICAL, NORMAL, MINOR, and TRIVIAL.

We can mark each test case with a severity level:

class MyTest : FunSpec() {
   init {
      test("very very important").config(severity = TestCaseSeverityLevel.CRITICAL) {
        // test here
      }
   }
}

Say we only want to execute tests that are CRITICAL or higher, we can execute with the system property kotest.framework.test.severity=CRITICAL

This can be useful if we have a huge test suite and want to run some tests first in a seperate test run.

By default, all tests are executed.

Disabling source references

Whenever a test case is created, Kotest creates a stack trace so that it can link back to the test case. The stack trace contains the filename and line number which the Intellij Plugin uses to create links in the test window. It calls these the sourceref.

If you have 1000s of tests and are encountering some slowdown when executing the full suite via gradle, you can now disable
the generation of these sourcerefs by setting the system property kotest.framework.sourceref.disable=true

Generally speaking, this is only of use if you have a huge test suite and mostly aimed at CI builds.

Make engine dependency free

A test framework is one of the lowest levels of dependences in an ecosystem. As Kotest is used by many Kotlin libraries, a clash can occur if Kotest and your project are using the same dependencies but with different versions.

It is beneficial then if Kotest has as few dependencies as possible. To this aim, 4.3.0 has seen the dependencies for the Kotest framework reduced to just Classgraph (to scan for specs), Mordant (for console output), and opentest4j.

Matchers return 'this' for easy chaining

In the opinion of this author, Kotest has the most comprehensive assertion support for Kotlin. Now they just became more convienient, by allowing you to chain assertions together if you wish.

So, instead of

val employees: List<Employee> = ...
employees.shouldBeSorted()
employees.shouldHaveSize(4)
employees.shouldContain(Employee("Sam", "Chicago"))

You can now do

val employees: List<Employee> = ...
employees.shouldBeSorted()
         .shouldHaveSize(4)
         .shouldContain(Employee("Sam", "Chicago"))

Of course, this is entirely optional.

Property test module for kotlinx datetime

Kotest's expansive property test library now includes generators for the incubating kotlinx datetime library.

Add the module kotest-property-datetime to your build. These generators are available for JVM and JS.

For example:

forAll(Arb.datetime(1987..1994)) { date ->
   isValidStarTrekTngSeason(date) shouldBe true
}

Option to strip whitespace from test names

If you like to define test names over multiple lines, Kotest will now strip out leading, trailing and repeated whitespace from test names.

For example, the following spec:

class MySpec : StringSpec() {
  init {
   """this is a
      test spanning multiple lines""" { }
  }
}

Would normally be output as

this is a      test spanning multiple lines

By setting the configuration object removeTestNameWhitespace to true, this would instead by output as

this is a test spanning multiple lines

Thanks

Huge thanks to all who contributed to this release:

AJ Alt, Alex Facciorusso, Ashish Kumar Joy, J Phani Mahesh, Jasper de Vries, Javier Segovia Córdoba,
Josh Graham, KeremAslan, Leonardo Colman, Michał Sikora, Mitchell Yuwono, Neenad Ingole, Rick Busarow,
SergKhram, Sergei Khramkov, crazyk2, sksamuel

Testing Kotlin/JS with Kotest

Stephen Samuel — Sun, 20 Sep 2020 19:17:03 +0000

One of the areas Kotlin has focused on in recent releases is with multi-platform support. Kotlin code, the Kotlin standard library and other supported dependencies can be compiled into ES5 Javascript.

When targeting platforms that are not JVM based, our options for testing are reduced. The two best known Java testing frameworks (JUnit and TestNG) are JVM specific and won't work when we compile to Javascript. Instead, in this short article I will show how it is possible to use Kotest to test against Kotlin/JS.

Firstly, I will assume you already have a project setup with javascript support. If not, then follow this guide.

This means you will end up a structure that contains a main source folder and a test sources folder as is usual, with the koltin-js standard library added.

Let's add a basic Javascript function that validates US social security numbers. This will be the function that we want to test with Kotest.

Inside the source root, we create a file called ssn.kt that contains the following code:

import kotlin.js.RegExp

private val socialRegex = RegExp("^\\d{3}-\\d{2}-\\d{4}$")

fun validateSocial(ssn: String): Boolean {
   return socialRegex.test(ssn) && !ssn.contains("0") && !ssn.startsWith("666")
}

You'll notice we are using the kotlin.js.RegExp class. This is a Kotlin wrapper around the built in Javascript regular expression support. This is one of the nice touches about Kotlin's multi-platform support - it allows you to use platform specific functions, rather than going down lowest common denominator path of only allowing functions that work on all platforms.

There are some basic rules when it comes to validating SSN numbers. The general format is a 3 digit area code, a 2 digit group code, and a 4 digit serial number. Our function requires hyphens between these sets of numbers.

Additionally, no number can be zero, and 666 is not valid as an area code.

Setting up the build for Kotest

To begin testing, we need to add the appropriate Kotest dependencies. These are kotest-framework-engine-js and kotest-framework-api-js for the test framework, and kotest-assertions-core-js for the assertions library. Note that the assertions library is optional, in case you want to use assertions from another library.

If you are not using coroutines already, you will need to bring in the kotlinx-coroutines-core-js dependency in as well.

So, your build file should contain something similar to this:

kotlin {

   js {
      browser()
   }

   sourceSets {
      test {
         dependencies {
            implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core-js:1.3.9'
            implementation 'io.kotest:kotest-assertions-core-js:4.2.5'
            implementation 'io.kotest:kotest-framework-api-js:4.2.5'
            implementation 'io.kotest:kotest-framework-engine-js:4.2.5'
         }
      }
   }
}

Writing a Test

To begin writing our tests, we create a Spec. A spec is the name Kotest uses for a class that contains test definitions. These are just regular classes that extend one of the Kotest spec styles. For Javascript we must choose one of the simpler specs - FunSpec in this case.

import io.kotest.core.spec.style.FunSpec
import io.kotest.matchers.shouldBe

class SsnTest : FunSpec({

   test("a SSN should be invalid when it contains a zero in any position") {
      validateSocial("543-23-5013") shouldBe false
      validateSocial("043-23-5313") shouldBe false
      validateSocial("313-03-5310") shouldBe false
   }
})

Nested inside the constructor lambda block is our first test case. We check that if a zero appears inside the SSN then it is not valid.

Executing this test is just a matter of invoking the gradle test task, either at the command line, or from within intelliJ. The Kotlin/JS plugin for gradle will take care of downloading Mocha and/or Karma depending on whether the project is Browser and/or NodeJS based.

And, if all goes well, you should see something like this:

Let's round out our test suite, by adding tests to confirm the 666 rule, and that inputs must be in the required 3-2-4 format.

import io.kotest.core.spec.style.FunSpec
import io.kotest.matchers.shouldBe

class SsnTest : FunSpec({

   test("a SSN should be invalid when it contains a zero in any position") {
      validateSocial("543-23-5013") shouldBe false
      validateSocial("043-23-5313") shouldBe false
      validateSocial("313-03-5310") shouldBe false
   }

   test("a SSN should be invalid when it starts with 666") {
      validateSocial("666-23-1234") shouldBe false
   }

   test("a SSN should be in the required format") {
      validateSocial("123-45-6789") shouldBe true
      validateSocial("123-45-678") shouldBe false
      validateSocial("12-45-6789") shouldBe false
      validateSocial("1234-56-678") shouldBe false
      validateSocial("123456789") shouldBe false
      validateSocial("123-456789") shouldBe false
      validateSocial("12345-6789") shouldBe false
      validateSocial("") shouldBe false
   }

})

Coroutines and Promises

The interop of Kotest and Javascript doesn't stop there. Every test in Kotest is executed inside of a coroutine, so we can test suspend functions directly. Internally these are mapped to Javascript Promises.

We're going to test a function that uses the Ktor HTTP client to connect to a public API to fetch a picture of a dog.

Firstly, add implementation 'io.ktor:ktor-client-js:1.4.0' to your main source. Then create a new file called http.kt which contains the following function:

import io.ktor.client.HttpClient
import io.ktor.client.engine.js.Js
import io.ktor.client.request.get
import io.ktor.client.statement.HttpResponse
import io.ktor.client.statement.readText

private val client = HttpClient(Js)

suspend fun fetch(): Dog {
   val resp = client.get<HttpResponse>("https://dog.ceo/api/breeds/image/random")
   return JSON.parse<Dog>(resp.readText())
}

data class Dog(val message: String, val status: String)

This fetch function invokes the API, returning an instance of Dog, parsed from the returned Json. Notice the use of the JSON.parse function which is part of the Kotlin/JS std library. There is no error handling here since this is just a simple example of suspendable functions in action.

The next part is of course to write the test:

import io.kotest.core.spec.style.FunSpec
import io.kotest.matchers.string.shouldEndWith

class DogTest : FunSpec({
   test("fetching a dog using JS promises") {
      fetch().message.shouldEndWith(".jpg")
   }
})

As you can see, testing a suspend function is as easy as testing the validateSocial function from earlier.

And just to prove that the test is indeed waiting for the response to complete, we can add an incorrect assertion to see the test fail.

import io.kotest.core.spec.style.FunSpec
import io.kotest.matchers.string.shouldEndWith

class DogTest : FunSpec({
   test("fetching a dog using JS promises") {
      fetch().message.shouldEndWith(".jpg2")
   }
})

That's how simple it is to use Kotest for Javascript tests. Kotlin/Javascript interop is still somewhat new and so there are some restrictions that you may run across.

The full project can be found here.

Boilerplate free config in Kotlin using Hoplite

Stephen Samuel — Tue, 06 Aug 2019 14:04:55 +0000

TL;DR: Loading Yaml, Json, etc config files into Kotlin data classes without boilerplate and with error checking with Hoplite.

Hello Kotliners!

For those of us who like to develop in a more functional way and avoid using Spring, we find ourselves looking for a way to handle configuration in our apps.

The most basic way is to use a java Properties file and use key=value pairs, or we may choose to use the popular Lightbend Config library and write config in their Json superset called Hocon. Whatever we choose we end up writing code like the following:

val jdbcUrl = config.getString("jdbc.url")

In other words, pulling the value out of the config by referencing the key. The config values may be extracted when they are needed at the call point, or we may choose to place all the config values into some central object and pass that about. Either way, there's no guarantee the key we reference actually exists until the config is required.

Even worse, if the value inside the config is not compatible with the target type, we may run into a conversion problem. We've all been bitten by a typo where we had :8080 as our port number only to find out 10 minutes into deployment we get a number format exception.

Some libraries may support marshalling automatically to some basic types, like doubles and bools, but often go no further than the basic primitives and collections.

Using Data Classes

Rather than pulling config out by key, we should push config into classes.

We start by declaring a data class (including nested classes).

data class Database(val host: String, val port: Int, val database: String)
data class WebServer(val resources: Path, val port: Int, val timeout: Duration) 
data class Config(val env: String, val db: Database, val server: WebServer)

Next we write our config, in either Yaml, Json, Toml, Hocon, or Java Props. I'll use Yaml here, in a file called staging.yaml

env: staging

db:
  host: staging.wibble.com
  port: 3306
  database: userprofiles

server:
  port: 8080
  resources: /var/www/web
  timeout: 10s

Finally, we use the ConfigLoader class to marshall the config directly into our config classes.

val cfg = ConfigLoader().loadConfigOrThrow<Config>("/staging.yaml")

Now the cfg instance is a fully inflated version of the configuration file, with all values converted into the defined types.

Note: The files should be on the classpath. We can load from files outside the classpath instead if we wish by using instances of Path.

Easy Errors

As we mentioned at the start, one of the biggest problems with config is when things go wrong. With Hoplite, errors are beautifully displayed as soon as the config is marshalled.

Let's use the same config as before, but this time with a file with a bunch of errors:

envvv: staging

db:
  host: staging.wibble.com
  port: .3306
  databas: userprofiles

server:
  port: localhost
  resources: /var/www/web
  timeout: 10ty

Using this file, gives the following error output:

Exception in thread "main": Error loading config because:

    - Could not instantiate 'com.example.Config' because:

        - 'env': Missing from config

        - 'db': - Could not instantiate 'com.example.Database' because:

            - 'host': Missing from config

            - 'port': Could not decode .3306 into a Int (/foo.yml:4:8)

            - 'database': Missing from config

        - 'server': - Could not instantiate 'com.example.WebServer' because:

            - 'port': Could not decode localhost into a Int (/foo.yml:8:8)

            - 'timeout': Required type java.time.Duration could not be decoded from a String value: 10ty (/foo.yml:10:11)

You can see how easy it is to debug this file - detailed error messages showing the exact key, plus where possible the line number and file name is included. The errors include values that could not be converted to a number, missing values, and erroneous formats for a Duration.

Supported Types

Hoplite supports many different types out of the box - batteries included as the cool kids say. These are your usual primitive types, collections, enums, dates, durations, BigDecimal, BigInteger, UUID, files, paths and so on. In addition the data types from Arrow - NonEmptyList, Tuples and Option are supported as well.

It's also very easy to add support for custom types if you wish. Just implement the Decoder interface and add this via a service loader.

There's plenty more to Hoplite, so I'll point you to the official docs for further reading.