quick_start.mdx

id	title	sidebar_label
quickstart	Quick Start	Quick Start

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Kotest is divided into several, stand alone, subprojects, each of which can be used independently:

• Test framework
• Assertions library
• Property testing

You can decide to go all in on Kotest, and use all three together, or you can choose to one or more modules in conjuction with other projects. For example, you could use the assertions library with JUnit, or you could use the test framework with another assertions library like assertj.

This page gives setup instructions for various combinations of projects and targets.

:::note Kotest is a multi-platform project. If you are unfamilar with this, then Kotlin compiles to different targets - JVM, JS, Native, iOS and so on. If you are doing server side or android development then you want the modules that end with JVM, such as kotest-property-jvm. :::

Test Framework

The Kotest test framework is supported on JVM, Android and Javascript.

<Tabs defaultValue="JVM/Gradle" values={[ {label: 'JVM/Gradle', value: 'JVM/Gradle'}, {label: 'JVM/Maven', value: 'JVM/Maven'}, {label: 'Kotlin/JS', value: 'JS'}, {label: 'Android', value: 'Android'}, {label: 'Multiplatform', value: 'Multiplatform'}, ]}>

Kotest on the JVM uses the JUnit Platform gradle plugin. For Gradle 4.6 and higher this is as simple as adding useJUnitPlatform() inside the tasks with type Test and then adding the Kotest junit5 runner dependency.

If you are using Gradle + Groovy then:

test {
   useJUnitPlatform()
}

Or if you are using Gradle + Kotlin then:

tasks.withType<Test> {
   useJUnitPlatform()
}

And then the dependency:

testImplementation 'io.kotest:kotest-runner-junit5:$version'

Add the following dependency to your commonTest dependencies block:

implementation 'io.kotest:kotest-framework-engine:$version'

Alternatively, add the dependency to the Javascript specific target.

kotlin {
   targets {
      js {
         browser()
         nodejs()
      }
   }
   sourceSets {
      val jsTest by getting {
         dependencies {
            implementation("io.kotest:kotest-framework-engine:$version")
         }
      }
   }
}

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 dependencies section.

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

:::info Currently, only JVM tests are officially supported in Kotest. Experimental support for instrumented and Robolectric tests is currently under work.

The following steps enable Kotest to be used for unit and integration tests, where the Android framework is not needed or is mocked that usually reside in the src/test folder of your module. :::

Kotest on Android uses the JUnit Platform gradle plugin. This requires configuring the android test options block in your build file and then adding the Kotest junit5 runner dependency.

android.testOptions {
   unitTests.all {
      useJUnitPlatform()
   }
}

dependencies {
   testImplementation 'io.kotest:kotest-runner-junit5:version'
}

To configure the test framework for both JS and JVM, you just combine copy the steps for JVM and JS.

Assertions Library

The core assertions library framework is supported on all targets. Submodules are supported on the platforms that applicable. For example, the JDBC matchers only work for JVM since JDBC is a Java library.

<Tabs defaultValue="JVM/Gradle" values={[ {label: 'JVM/Gradle', value: 'JVM/Gradle'}, {label: 'JVM/Maven', value: 'JVM/Maven'}, {label: 'Multiplatform', value: 'Multiplatform'}, ]}>

Add the following dependency to your build:

testImplementation 'io.kotest:kotest-assertions-core:$version'

Add the following dependency to your build.

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

Add the following dependency to your commonTest dependencies block:

implementation 'io.kotest:kotest-assertions-core:$version'

Alternatively, add the dependency to a specific target. For example, we could add to the Javascript target only.

kotlin {
   targets {
      js {
         browser()
         nodejs()
      }
   }
   sourceSets {
      val jsTest by getting {
         dependencies {
            implementation("io.kotest:kotest-assertions-core:$version")
         }
      }
   }
}

Property Testing

The property test framework is supported on all targets.

<Tabs defaultValue="JVM/Gradle" values={[ {label: 'JVM/Gradle', value: 'JVM/Gradle'}, {label: 'JVM/Maven', value: 'JVM/Maven'}, {label: 'Multiplatform', value: 'Multiplatform'}, ]}>

Add the following dependency to your build:

testImplementation 'io.kotest:kotest-property:$version'

Add the following dependency to your build.

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

Add the following dependency to your commonTest dependencies block:

implementation 'io.kotest:kotest-property:$version'

Alternatively, add the dependency to a specific target. For example, we could add to the Javascript target only.

kotlin {
   targets {
      js {
         browser()
         nodejs()
      }
   }
   sourceSets {
      val jsTest by getting {
         dependencies {
            implementation("io.kotest:kotest-property:$version")
         }
      }
   }
}

Snapshots

Snapshot are automatically published on each commit to master. 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:

https://oss.sonatype.org/content/repositories/snapshots