Matchers

A Matcher is the Kotest term for an assertion that performs a specific test. For example, a matcher may test that a double is greater than zero. Or it it may test that a file is not empty.

Kotest currently has approximately 325 matchers split across several modules. Most of these matchers are for standard library types. Others are project specific. Additionally, there are matchers provided by third party libraries.

Kotest matchers are framework agnostic. You can use them with the Kotest framework, or with any other framework. If you are happy with JUnit, you can still use the powerful matchers provided by the kotest assertion modules.

Matchers can be used in two styles:

  • Extension functions like a.shouldBe(b) or a.shouldStartWith("foo")
  • Infix functions like a shouldBe b or a should startWith("foo")

Both styles are supported. The advantage of the extension function style is that the IDE can autocomplete for you, but some people may prefer the infix style as it is slightly cleaner.

Matchers can be negated by using shouldNot instead of should for the infix style. For example, a shouldNot startWith("boo"). For the extension function style, each function has an equivalent negated version, for example, a.shouldNotStartWith("boo").

Kotest Matcher Modules#

These modules provide the core matcher experience. They are hosted in the main Kotest repo, and are released on the same cadence as the Kotest framework.

ModuleDescriptionType
kotest-assertions-coreProvides matchers for standard libary types.Multiplatform
kotest-assertions-jsonProvides matchers for testing json objects.JVM
kotest-assertions-kotlinx-timeProvides matchers for Kotlin's date / time library.Multiplatform
kotest-assertions-sqlProvides matchers for JDBC.JVM
kotest-assertions-ktorProvides matchers for Ktor server test and client libraries.Multiplatform

Kotest External Matcher Modules#

These modules are hosted in the kotest organization but in separate repositories from the main kotest project. They are released on an independent cadence from the Kotest framework. They provide matchers for third party libraries.

ModuleDescriptionType
kotest-assertions-arrowProvides matchers for the Arrow functional programming library.JVM
kotest-assertions-compilerProvides matchers that test for compilable code.JVM
kotest-assertions-klockProviders matchers for Klock.Multiplatform
kotest-assertions-konformProvides matchers for Konform.Multiplatform
kotest-assertions-jsoupProvides matchers JSoup.JVM

Community Provided Matchers#

This is a list of projects that provide Kotest matchers. They are maintained outside of the Kotest organization.

LibraryDescription
Http4kFunctional toolkit for Kotlin HTTP applications
MicronautJVM-based, full-stack framework for building modular, easily testable microservice