Testing in Kotlin (JUnit & kotlin.test)

Reviewed & published by Brayan K

Automated tests are small functions, marked with @Test, that call your code and assert the result — kotlin.test and JUnit let you verify behaviour and catch regressions before they ship.

Part of the free Kotlin course at LearnCodingFast — hands-on lessons with worked examples and the output they print, plus practice exercises and a quick quiz.

You'll write tests with assertEquals, assertTrue, and assertFailsWith, use readable backtick names, and follow Arrange-Act-Assert.

What You'll Learn in This Lesson

• Marking tests with @Test
• assertEquals, assertTrue, and assertFailsWith
• How kotlin.test relates to JUnit 5
• Readable backtick test names
• The Arrange-Act-Assert structure
• What MockK is for (and when you don't need it)

1️⃣ Your First Test: @Test and assertions

A test is a function marked @Test inside a class. Inside it you call your code and check the result with an assertion. assertEquals(expected, actual) fails if they differ; assertTrue(cond) fails if the condition is false. Backtick names make each test a readable sentence.

// A real test class with JUnit 5 + kotlin.test.
// (Runs under a test runner like Gradle, not main().)
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertTrue

fun add(a: Int, b: Int): Int = a + b

class CalculatorTest {

    // @Test marks a function the runner will execute.
    // Backtick names let you write a readable sentence.
    @Test
    fun `add returns the sum of two numbers`() {
        // assertEquals(expected, actual)
        assertEquals(5, add(2, 3))
    }

    @Test
    fun `add of a number and zero is the number`() {
        assertTrue(add(7, 0) == 7)
    }
}

2️⃣ Arrange-Act-Assert and Testing Errors

Structure each test in three phases: Arrange the inputs, Act by calling the code once, and Assert the outcome. To test that bad input fails correctly, wrap the call in assertFailsWith<Exception> { ... }, which passes only when that exact exception is thrown.

// The Arrange-Act-Assert pattern keeps tests readable.
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertFailsWith

fun divide(a: Int, b: Int): Int = a / b

class DivideTest {

    @Test
    fun `divides two numbers`() {
        // Arrange
        val a = 10
        val b = 2
        // Act
        val result = divide(a, b)
        // Assert
        assertEquals(5, result)
    }

    @Test
    fun `dividing by zero throws`() {
        // assertFailsWith checks the RIGHT exception is thrown.
        assertFailsWith<ArithmeticException> {
            divide(1, 0)
        }
    }
}

3️⃣ A Runnable Demo You Can Try Now

Real test classes need a build tool to run, but the idea — call a function, compare to an expected value, report pass/fail — fits in a plain main(). This little harness lets you watch assertions succeed in the Playground.

// A runnable demo of the SAME idea, using plain main()
// so you can see assertions pass/fail in the Playground.
fun add(a: Int, b: Int): Int = a + b

fun check(name: String, expected: Int, actual: Int) {
    if (expected == actual) {
        println("PASS: $name")
    } else {
        println("FAIL: $name (expected $expected, got $actual)")
    }
}

fun main() {
    check("2 + 3", 5, add(2, 3))
    check("7 + 0", 7, add(7, 0))
    check("10 + 10", 20, add(10, 10))
}

Your turn. Fill in the ___ blank, then run and compare.

// 🎯 YOUR TURN — replace each ___ then run main()
fun square(n: Int): Int = n * n

fun check(name: String, expected: Int, actual: Int) {
    // 1) print "PASS: <name>" when they match, else "FAIL: <name>"
    if (expected ___ actual) {           // 👉 put: ==
        println("PASS: $name")
    } else {
        println("FAIL: $name")
    }
}

fun main() {
    check("square 4", 16, square(4))
    check("square 5", 25, square(5))

    // ✅ Expected output:
    // PASS: square 4
    // PASS: square 5
}

Mini-Challenge: Test isEven

Write a Boolean check harness and verify isEven.

// 🎯 MINI-CHALLENGE: test a function with a mini harness.
// Save as IsEvenTest.kt and run main().
//
// 1. Write isEven(n) returning n % 2 == 0.
// 2. Write check(name, expected, actual) for Booleans that prints
//    "PASS: <name>" or "FAIL: <name>".
// 3. In main(), check isEven(4)==true and isEven(7)==false.
//
// ✅ Expected output:
//    PASS: 4 is even
//    PASS: 7 is odd

fun isEven(n: Int): Boolean = n % 2 == 0

fun check(name: String, expected: Boolean, actual: Boolean) {
    // print PASS or FAIL
}

fun main() {
    check("4 is even", true, isEven(4))
    check("7 is odd", false, isEven(7))
}

Common Errors (and the fix)

• ❌ Test never runs — you forgot @Test or imported the wrong one. ✅ Use import kotlin.test.Test and annotate the function.
• ❌ Confusing failure message — arguments to assertEquals are reversed. ✅ Put expected first, actual second.
• ❌ Error test passes by accident — you used a try/catch that swallows everything. ✅ Use assertFailsWith<T> for the exact type.
• ❌ One test, many assertions on unrelated things — failures are hard to read. ✅ Test one behaviour per test.

Pro Tips

• 💡 Name behaviours, not methods: `returns 0 for empty input` reads better than testAdd1.
• 💡 Test the edges: empty, zero, negative, and boundary values catch the most bugs.
• 💡 Mock only real dependencies: use MockK for databases or networks, never for pure functions.

📋 Quick Reference — kotlin.test

🎉 Lesson Complete!

• ✅ Mark tests with @Test from kotlin.test
• ✅ assertEquals takes expected first, then actual
• ✅ assertFailsWith<T> verifies the right exception
• ✅ Backtick names turn tests into readable specs
• ✅ Structure tests as Arrange-Act-Assert; mock only real dependencies

Practice quiz

Continue this course

• Previous: Advanced Collections (groupBy, fold, windowed)
• Next: Java Interop — Call Java from Kotlin and Kotlin from Java with @Jvm annotations
• Quick reference: Kotlin cheat sheet

Frequently asked questions

What is kotlin.test and how does it relate to JUnit?

kotlin.test is a small, multiplatform assertion library that provides @Test plus functions like assertEquals, assertTrue, assertFalse, assertNull, and assertFailsWith. On the JVM it typically delegates to an underlying runner such as JUnit 5, so kotlin.test gives you a clean, framework-agnostic API while JUnit (or another engine) actually discovers and runs the tests. The practical upside is that the same assertions work whether you target the JVM, JavaScript, or native, and you are not locked to one framework's assertion style.

How do the common assertions work?

assertEquals(expected, actual) fails unless the two are equal — note the order is expected first, then actual, which affects the failure message. assertTrue(condition) and assertFalse(condition) check a Boolean directly. assertNull and assertNotNull check nullability. assertFailsWith<SomeException> { ... } runs the block and passes only if it throws the specified exception type, which is the idiomatic way to test error paths. Each assertion takes an optional message string you can supply to make a failure easier to diagnose.

Why use backtick test names?

Kotlin lets you name a function with backticks, allowing spaces and ordinary punctuation: fun `add returns the sum`() { }. For test methods this is hugely helpful because the test name becomes a readable sentence describing the behaviour under test, and that sentence is exactly what appears in the test report when it passes or fails. It turns a wall of camelCase names into self-documenting specifications, so a failing test immediately tells you which behaviour broke without reading the body.

What is the Arrange-Act-Assert pattern?

Arrange-Act-Assert (AAA) is a three-part structure that keeps each test focused and readable. Arrange sets up the inputs and any objects the test needs; Act performs the single operation under test, usually one method call; Assert checks the outcome with one or a few assertions. Keeping these phases visually separate (often with blank lines or comments) makes a test easy to scan and discourages testing several unrelated things at once. A good test exercises one behaviour and has a clear, single reason to fail.

What is MockK and when do I need it?

MockK is the popular Kotlin mocking library used to create fake versions of dependencies so you can test a unit in isolation. When the code under test calls out to a collaborator — a repository, a network client, a clock — you replace that collaborator with a mock whose behaviour you script (every { repo.find(1) } returns user) and whose interactions you verify (verify { repo.save(user) }). You need mocking when a real dependency is slow, non-deterministic, or has side effects you do not want in a test. For pure functions like the add() example, no mocking is required — just call and assert.