KotlinTest is a flexible and comprehensive testing tool for Kotlin.
Full documentation
For latest updates see Changelog
Community
- Stack Overflow (don't forget to use the tag "kotlintest".)
- KotlinTest channel in the Kotlin Slack
- Contribute
Test with Style
Write simple and beautiful tests with the StringSpec
style:
class MyTests : StringSpec({
"length should return size of string" {
"hello".length shouldBe 5
}
"startsWith should test for a prefix" {
"world" should startWith("wor")
}
})
KotlinTest comes with several testing styles so you can choose one that fits your needs.
Multitude of Matchers
Use over 120 provided matchers to test assertions on many different types:
"substring".shouldContain("str")
user.email.shouldBeLowerCase()
myImageFile.shouldHaveExtension(".jpg")
cityMap.shouldContainKey("London")
The withClue
and asClue
helpers can add extra context to assertions so failures are self explanatory:
withClue("Name should be present") { user.name shouldNotBe null }
data class HttpResponse(val status: Int, body: String)
val response = HttpResponse(200, "the content")
response.asClue {
it.status shouldBe 200
it.body shouldBe "the content"
}
Nesting is allowed in both cases and will show all available clues.
Matchers are extension methods and so your IDE will auto complete. See the full list of matchers or write your own.
Let the Computer Generate Your Test Data
Use property based testing to test your code with automatically generated test data:
class PropertyExample: StringSpec() {
init {
"String size" {
assertAll { a: String, b: String ->
(a + b) should haveLength(a.length + b.length)
}
}
}
Check all the Tricky Cases With Data Driven Testing
Handle even an enormous amount of input parameter combinations easily with data driven tests:
class StringSpecExample : StringSpec({
"maximum of two numbers" {
forall(
row(1, 5, 5),
row(1, 0, 1),
row(0, 0, 0)
) { a, b, max ->
Math.max(a, b) shouldBe max
}
}
})
Test Exceptions
Testing for exceptions is easy with KotlinTest:
val exception = shouldThrow<IllegalAccessException> {
// code in here that you expect to throw an IllegalAccessException
}
exception.message should startWith("Something went wrong")
Fine Tune Test Execution
You can specify the number of invocations, parallelism, and a timeout for each test or for all tests.
And you can group tests by tags or disable them conditionally.
All you need is config
:
class MySpec : StringSpec() {
override val defaultTestCaseConfig = TestCaseConfig(invocations = 3)
init {
"should use config".config(timeout = 2.seconds, invocations = 10, threads = 2, tags = setOf(Database, Linux)) {
// ...
}
}
}
And More ...
This page gives you just a short overview of KotlinTest. There are many more features:
- Test whole collections with Inspectors.
- Write elegant conditions with the matcher DSL:
"hello".shouldHaveSubstring("ell")
. - Reuse test logic for setup or tear down, with Listeners.
- Test asynchronous code with
whenReady
and non-deterministic code witheventually
orcontinually
- Let KotlinTest close resources automatically:
val reader = autoClose(StringReader("xyz"))
- Handle tricky scenarios such as System Environment with extensions
- Use the Spring extension to automatically inject your spring test classes.
- Test Arrow data types with the Arrow extension.
See full documentation.
Use
Gradle
To use in gradle, configure your build to use the JUnit Platform. For Gradle 4.6 and higher this is
as simple as adding useJUnitPlatform()
inside the test
block and then adding the KotlinTest dependency.
test {
useJUnitPlatform()
}
dependencies {
testImplementation 'io.kotlintest:kotlintest-runner-junit5:3.3.2'
}
or with Gradle Kotlin DSL
val test by tasks.getting(Test::class) {
useJUnitPlatform { }
}
dependencies {
testImplementation("io.kotlintest:kotlintest-runner-junit5:3.3.2")
}
or with gradle and Android
android {
...
testOptions {
unitTests.all {
useJUnitPlatform()
}
}
}
dependencies {
testImplementation 'io.kotlintest:kotlintest-runner-junit5:3.3.2'
}
Maven
For maven you must configure the surefire plugin for junit tests.
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.22.1</version>
<dependencies>
<dependency>
<groupId>org.junit.platform</groupId>
<artifactId>junit-platform-surefire-provider</artifactId>
<version>1.3.2</version>
</dependency>
</dependencies>
</plugin>
And then add the KotlinTest JUnit5 runner to your build.
<dependency>
<groupId>io.kotlintest</groupId>
<artifactId>kotlintest-runner-junit5</artifactId>
<version>3.3.2</version>
<scope>test</scope>
</dependency>