Skip to content
Powerful, elegant and flexible test framework for Kotlin
Kotlin
Branch: master
Clone or download
Kerooker Improve and document ComparableMatchers (#1092)
This commit aims to improve some of the available comparable matchers by adding extension infix functions.

 The new and old functions were documented to improve user's understandability of functions instead of having to navigate through the source code (CTRL + Q in IntelliJ).

 On the `shouldBeEqualComparingTo` function, I chose this name so it is not confusing to `shouldBe` and not ambiguous to `shouldCompareTo`. Although the name is a little big, I don't believe it will be a problem.

 There are no more matchers to be added to `compareTo`. All possible behavior for the compareTo matcher were added.

 Closes #668
Latest commit 54f960a Dec 3, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows Create label.yml Nov 25, 2019
doc Fix typo (#1083) Nov 20, 2019
gradle/wrapper Improve Gradle build (#1025) Oct 1, 2019
kotest-assertions Improve and document ComparableMatchers (#1092) Dec 3, 2019
kotest-core FreeSpecScope String.config test function is not suspend #1085 Nov 25, 2019
kotest-extensions Replace Kotlintest with Kotest (#991) Sep 29, 2019
kotest-plugins/kotest-plugins-pitest Replace Kotlintest with Kotest (#991) Sep 29, 2019
kotest-runner Replace Kotlintest with Kotest (#991) Sep 29, 2019
kotest-samples Replace Kotlintest with Kotest (#991) Sep 29, 2019
kotest-tests Replace Kotlintest with Kotest (#991) Sep 29, 2019
.editorconfig Dot matches all in regex test Sep 4, 2019
.gitignore Replace Kotlintest with Kotest (#991) Sep 29, 2019
.travis.yml Replace Kotlintest with Kotest (#991) Sep 29, 2019
CHANGELOG.md Removed passed tests from log Sep 4, 2019
LICENSE Update LICENSE Mar 22, 2016
README.md Update README.md Nov 28, 2019
all.gpg.enc Added gpg keyring as encrypted file Jan 27, 2019
appveyor.yml AppVeyor: Create %HOME%\.gradle independently of the configuration (#293 Apr 15, 2018
build.gradle Bump Arrow version 0.10.3 (#1081) Nov 14, 2019
gradle.properties Improve Gradle build (#1025) Oct 1, 2019
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
publish.gradle Replace Kotlintest with Kotest (#991) Sep 29, 2019
settings.gradle #1028: Add Jsoup Assertions (#1035) Oct 22, 2019
sksamuel.gpg.enc Added gpg keyring as encrypted file Jan 27, 2019
snapshot_deploy.sh Updated deploy command to use publish Jan 28, 2019

README.md

KotlinTest

Build Status Build status GitHub license

KotlinTest is a flexible and comprehensive testing tool for Kotlin.
Full documentation

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

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:

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

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

dependencies {
  testImplementation 'io.kotlintest:kotlintest-runner-junit5:3.3.2'
}
Android Project (Groovy)
android.testOptions {
    unitTests.all {
        useJUnitPlatform()
    }
}

dependencies {
    testImplementation 'io.kotlintest:kotlintest-runner-junit5:3.3.2'
}

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.kotlintest:kotlintest-runner-junit5:3.3.0")
}

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 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>

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

Currently, in snapshot builds only, our artifacts and packages are using a new name: Kotest. To use them, change every instance of io.kotlintest to io.kotest, and you should be good to go.

You can’t perform that action at this time.