Test Kotlin projects with Maven

Kotlin integrates seamlessly with the Maven ecosystem, allowing you to use industry-standard tools to verify your backend applications. In this guide, you'll learn how to create tests with JUnit and use Maven plugins to run unit and integration tests.

Create tests with JUnit

JUnit is the standard testing framework for Kotlin backend development. While Kotlin supports multiple JUnit versions, most modern projects should use JUnit 6.

To create a test in Kotlin using JUnit, use the @Test annotation from the kotlin.test or JUnit package.

Add dependency

The kotlin-test library is the easiest way to start. It provides a common set of assertions and automatically pulls in the necessary JUnit artifacts.

JUnit 5 and later

For all new projects, use the kotlin-test-junit5 artifact. It provides full support for JUnit, including features like nested tests and parallel execution. Kotlin/JVM supports the latest stable JUnit version, JUnit 6.

Update your pom.xml file as follows:

<dependencies>
    <dependency>
        <groupId>org.jetbrains.kotlin</groupId>
        <artifactId>kotlin-test-junit5</artifactId>
        <version>2.3.21</version>
        <scope>test</scope>
    </dependency>
</dependencies>

JUnit 4

If you'd like to use an earlier version of JUnit, for example, for a legacy project, use the kotlin-test-junit artifact that utilizes JUnit 4:

<!-- pom.xml -->
<dependencies>
    <dependency>
        <groupId>org.jetbrains.kotlin</groupId>
        <artifactId>kotlin-test-junit</artifactId>
        <version>2.3.21</version>
        <scope>test</scope>
    </dependency>
</dependencies>

Write unit tests

Unit tests verify isolated parts of your code, such as individual functions or classes. By convention, unit tests are named with the *Test suffix. For example:

import kotlin.test.Test
import kotlin.test.assertEquals

class OrderServiceTest {
    @Test
    fun `calculate total should sum item prices`() {
        val service = OrderService()
        val result = service.calculateTotal(listOf(10.0, 25.0))
        assertEquals(35.0, result)
    }
}

Write integration tests

Integration tests verify interaction between components, like a service and a database. By convention, integration tests are named with the *IT suffix. For example:

import kotlin.test.Test
import kotlin.test.assertNotNull

class UserRepositoryIT {
    @Test
    fun saveFindUser() {
        // Example integration with a database or service
        val repository = UserRepository()
        repository.save(User("KotlinUser"))
        
        val user = repository.findByName("KotlinUser")
        assertNotNull(user)
    }
}

Run tests

In Maven projects, test execution is typically split between two plugins: Surefire and Failsafe to ensure a clean build lifecycle.

With Surefire plugin

The Surefire plugin handles unit tests. It runs all Kotlin and Java tests that follow the *Test naming pattern.

By default, it executes during the test phase of the build lifecycle and fails the build immediately if a test fails.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>3.5.5</version>
</plugin>

To run only your unit tests, use the following command:

mvn test

With Failsafe plugin

The Failsafe plugin handles integration tests. It runs all Kotlin and Java tests that follow the *IT naming pattern.

Unlike Surefire, Failsafe allows the build to continue if a test fails during the integration-test phase, allowing the post-integration-test phase tasks (like stopping a Docker container) to run. The build finally fails during the verify phase if there were any test failures.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-failsafe-plugin</artifactId>
    <version>3.5.5</version>
    <executions>
        <execution>
            <goals>
                <goal>integration-test</goal>
                <goal>verify</goal>
            </goals>
        </execution>
    </executions>
</plugin>

To run both unit and integration tests, use the following command:

mvn verify

Explore other testing frameworks

Besides JUnit, you can use other popular frameworks to make Kotlin tests more idiomatic and readable:

Library	Description
AssertJ	Fluent assertion library with chainable assertions.
Mockito-Kotlin	Kotlin wrapper for Mockito that provides helper functions and better integration with the Kotlin type system.
MockK	Native Kotlin mocking library that supports Kotlin-specific features, including coroutines and extension functions.
Kotest	Assertion library for Kotlin offering multiple assertion styles and extensive matcher support.
Strikt	Assertion library for Kotlin with type-safe assertions and support for data classes.

What's next

Explore the features of the kotlin.test library.
Improve your test output with Kotlin's Power-assert compiler plugin.

06 May 2026