Skip to content
Powerful, elegant and flexible test framework for Kotlin
Kotlin
Branch: master
Clone or download

Latest commit

Latest commit 32513e1 Apr 3, 2020

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Delete android-test.yml Mar 24, 2020
buildSrc Release 4.0.2 Apr 4, 2020
doc Fix typo in matchers documentation (#1351) Apr 4, 2020
gradle/wrapper Documentation for test filtering via gradle #597 Mar 15, 2020
kotest-assertions Restored opentest4j and junit4 exceptions (#1339) Apr 3, 2020
kotest-core Restored opentest4j and junit4 exceptions (#1339) Apr 3, 2020
kotest-examples Bumped kotlin to 1.3.71 Mar 25, 2020
kotest-extensions Bumped kotlin to 1.3.71 Mar 25, 2020
kotest-fp Allow internal by default #1337 (#1342) Apr 3, 2020
kotest-mpp Exception when getting annotations in gradle < 6 #1232 Mar 10, 2020
kotest-plugins/kotest-plugins-pitest Make JSON and pitest tests work (#1316) Mar 29, 2020
kotest-property Arb.bind produces the same value for property test #1348 (#1350) Apr 3, 2020
kotest-runner Renamed sys prop for kotest.gradle5.compatibility Apr 3, 2020
kotest-samples Remove invocations from config #1165 Feb 9, 2020
kotest-tests Added test for tag to use simple name Apr 3, 2020
.editorconfig Added test for first/last cause in eventually Mar 7, 2020
.gitignore Fixed bug with project conf parallelism, after/before methods, and ma… Feb 23, 2020
CHANGELOG.md Add forEachAsClue extension #939 Jan 17, 2020
LICENSE Update LICENSE Mar 22, 2016
README.md Update README.md Apr 1, 2020
build.gradle.kts Removed android plugin Mar 25, 2020
gradle.properties Disable native.disableCompilerDaemon Mar 25, 2020
gradlew Bump gradle wrapper version 5.6.2 (#1027) Oct 1, 2019
gradlew.bat Bump gradle wrapper version 5.6.2 (#1027) Oct 1, 2019
migration.md Updated docs with kotest details #1209 Feb 16, 2020
nopublish.gradle Trying to not publish test modules Feb 16, 2020
publish-mpp.gradle.kts Feature/discovery (#1271) Mar 9, 2020
settings.gradle.kts Add JUnit4 support again (#1340) Apr 2, 2020

README.md

Kotest

Build Status GitHub

Kotest is a flexible and comprehensive testing tool for Kotlin with multiplatform support. Full documentation

Previously known as Kotlintest - From release 4.0 this project is now known as Kotest

For latest updates see Changelog

Community

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")
  }
})

Kotest comes with several testing styles so you can choose one that fits your needs.

Multitude of Matchers

Use over 300 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({
  "String size" {
    checkAll<String, String> { a, b ->
      (a + b) shouldHaveLength 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 Kotest:

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({
  "should use config".config(timeout = 2.seconds, invocations = 10, threads = 2, tags = setOf(Database, Linux)) {
    // test here
  }
})

And More ...

This page gives you just a short overview of Kotest. There are many more features:

See full documentation.

Use

Kotest is split into two main dependencies. Firstly, the framework which provides the ability to layout tests in one of the spec styles and execute them in JUnit or in Mocha. Secondly, the assertion packages. These are provided separately so you can pick and choose which parts you want to use if you don't want to go all in on Kotest.

The following instructions give you the batteries included setup in gradle or maven.

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 tasks with type Test and then adding the Kotest dependency.

Groovy (build.gradle)
test {
  useJUnitPlatform()
}

dependencies {
  testImplementation 'io.kotest:kotest-runner-junit5-jvm:<version>' // for kotest framework
  testImplementation 'io.kotest:kotest-assertions-core-jvm:<version>' // for kotest core jvm assertions
}
Android Project (Groovy)
android.testOptions {
    unitTests.all {
        useJUnitPlatform()
    }
}

dependencies {
    testImplementation 'io.kotest:kotest-runner-junit5:<version>' // for kotest framework
    testImplementation 'io.kotest:kotest-assertions-core-jvm:<version>' // for kotest core jvm assertions
}

If you are using Gradle+Kotlin, this works for both Android and non-Android projects:

Kotlin (build.gradle.kts)
tasks.withType<Test> {
  useJUnitPlatform()
}

dependencies {
  testImplementation("io.kotest:kotest-runner-junit5-jvm:<version>") // for kotest framework
  testImplementation("io.kotest:kotest-assertions-core-jvm:<version>") // for kotest core jvm assertions
}

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.2</version>
</plugin>

And then add the Kotest JUnit5 runner to your build.

<dependency>
    <groupId>io.kotest</groupId>
    <artifactId>kotest-runner-junit5-jvm</artifactId>
    <version>{version}</version>
    <scope>test</scope>
</dependency>

And for using kotest core jvm assertions add following configurations

<dependency>
    <groupId>io.kotest</groupId>
    <artifactId>kotest-assertions-core-jvm</artifactId>
    <version>{version}</version>
    <scope>test</scope>
</dependency>

Snapshots

If you want to test the latest snapshot build, setup the same way described above, change the version to the current snapshot version and add the following repository to your repositories block:

repositories {
    maven(url = "https://oss.sonatype.org/content/repositories/snapshots/")
}
You can’t perform that action at this time.