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
- Infix functions like
a shouldBe bor
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,
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.
|kotest-assertions-core||Provides matchers for standard libary types.||Multiplatform|
|kotest-assertions-json||Provides matchers for testing json objects.||JVM|
|kotest-assertions-kotlinx-time||Provides matchers for Kotlin's date / time library.||Multiplatform|
|kotest-assertions-sql||Provides matchers for JDBC.||JVM|
|kotest-assertions-ktor||Provides 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.
|kotest-assertions-arrow||Provides matchers for the Arrow functional programming library.||JVM|
|kotest-assertions-compiler||Provides matchers that test for compilable code.||JVM|
|kotest-assertions-klock||Providers matchers for Klock.||Multiplatform|
|kotest-assertions-konform||Provides matchers for Konform.||Multiplatform|
|kotest-assertions-jsoup||Provides matchers JSoup.||JVM|
Community Provided Matchers
This is a list of projects that provide Kotest matchers. They are maintained outside of the Kotest organization.
|Http4k||Functional toolkit for Kotlin HTTP applications|
|Micronaut||JVM-based, full-stack framework for building modular, easily testable microservice|