Kotest is split into several subprojects which can be used independently. One of these subprojects is the comprehensive assertion / matchers support. These can be used with the Kotest test framework, or with another test framework like JUnit or Spock.
The core functionality of the assertion modules are functions that test state. Kotest calls these types of state assertion functions matchers. There are core matchers and matchers for third party libraries.
There are also many other utilities for writing tests, such as testing for exceptions, functions to help test non-determistic code, inspectors for collections, and soft assertions to group assertions.
Multitude of Matchers
For example, to assert that a variable has an expected value, we can use the
name shouldBe "sam"
There are general purpose matchers, such as
shouldBe as well as matchers for many other specific scenarios,
str.shouldHaveLength(10) for testing the length of a string, and
file.shouldBeDirectory() which test
that a particular file points to a directory. They come in both infix and regular variants.
Assertions can generally be chained, for example:
There are over 350 matchers spread across multiple modules. Read about all the matchers here.
Sometimes a failed assertion does not contain enough information to know exactly what went wrong.
user.name shouldNotBe null
If this failed, you would simply get:
<null> should not equal <null>
Which isn't particularly helpful. We can add extra context to failure messages through the use of clues.
Inspectors allow us to test elements in a collection, and assert the quantity of elements that should be expected to pass (all, none, exactly k and so on). For example
it.city shouldBe "Chicago"
Read about inspectors here
It is easy to add your own matchers by extending the
Matcher<T> interface, where T is the type you wish to match against. Custom matchers can compose existing matchers or be completely standalone.
See a full worked example.