Skip to content
Tutorials Center
My learning

Topics

Lesson 106 of 134 ยท Testing and Tooling

Testing in Kotlin

Learn how to test Kotlin code - kotlin.test and JUnit, assertEquals, assertFailsWith, the arrange-act-assert structure, table-driven tests and a tiny test runner you can run in your browser.

A test is a small program that calls your code and checks the answer. When you change the code later, the tests tell you within seconds whether you broke something. Without tests, every change is a bet; with them, you can improve a codebase with confidence.

Kotlin works with the standard JVM test tools. In real projects you use the kotlin.test library (assertions that work on every Kotlin platform) together with a runner such as JUnit 5, and you run the tests with Gradle (see Gradle basics). This site's runner compiles one file and has no test libraries, so this lesson does two things: it shows the real syntax read-only, and it builds a tiny test framework of about thirty lines that you can run and change here. By the end you will understand what the real tools do, because you will have written their core yourself.

The library is not available here

First, the honest part. Importing kotlin.test in the in-browser editor fails, because the dependency is not on the classpath:

Kotlin kotlin.test is not available here (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

The compiler reports main.kt:1:15: error: unresolved reference 'test'. and then unresolved reference 'assertEquals'. In a Gradle project the same code works after one line in build.gradle.kts: testImplementation(kotlin("test")). We will write our own versions of the functions instead; the names and behavior match the real ones, so everything you learn transfers.

Assertions: three small functions

An assertion compares what happened with what you expected and throws an error when they differ. Three assertions cover most tests:

  • assertEquals(expected, actual) compares with ==.
  • assertTrue(condition) checks a boolean.
  • assertFailsWith<SomeException> { ... } checks that the code throws, and returns the exception so you can examine its message.

The next example implements them, adds a test runner, and tests a function that converts a price like "12.50" into cents. Read the helpers first; the tests start at fun main().

Kotlin A tiny test framework

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

Four tests pass. The wrong expectation produces FAIL a wrong expectation (fails on purpose) -> Expected <1205>, actual <1250>., and the crashing test is reported as ERROR with IllegalStateException: the test crashed. The last line reads 4 passed, 1 failed, 1 errors.

Look at the difference between FAIL and ERROR. A failure means an assertion did not hold: the code ran and gave a different answer than expected. An error means something unexpected blew up (an exception that is not an assertion), which usually points to a bug in the code or in the test. Real runners make the same distinction.

assertFailsWith in the real library is declared with a reified type parameter just like ours, which is why you write assertFailsWith<IllegalArgumentException> { ... } without passing a class. It is a good example of an inline function with reified types.

What a real test looks like

Here is the same kind of test written for a Gradle project with kotlin.test. This is a read-only example, because it needs the library and a build tool:

Kotlin
// read-only example: src/test/kotlin/PriceTest.kt, needs kotlin("test") and a runner
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertFailsWith

class PriceTest {
    @Test
    fun parsesPriceWithCents() {
        assertEquals(1250, parsePrice("12.50"))
    }

    @Test
    fun rejectsGarbage() {
        val e = assertFailsWith<IllegalArgumentException> { parsePrice("abc") }
        assertEquals("not a price: abc", e.message)
    }
}

The differences from our runner are small. A class groups tests. @Test marks a function as a test, so the framework finds it by scanning instead of you calling it. Each test gets a fresh instance of the class, so tests cannot leak state into each other through fields. Methods marked @BeforeTest and @AfterTest run before and after every test for setup and cleanup. Then gradle test (or the green arrow in your IDE) compiles everything, runs every test and prints a report.

Kotlin lets you give test functions readable names in backticks, which shows up in the report:

Kotlin
// read-only example
@Test
fun `rejects prices with one digit after the dot`() {
    assertFailsWith<IllegalArgumentException> { parsePrice("1.5") }
}

Structure: arrange, act, assert

Good tests have three visible parts, in this order:

  1. Arrange: create the objects and data.
  2. Act: call the one thing you test.
  3. Assert: check the outcome.

Keep each test about one behavior, and name it after that behavior ("rejects negative amounts"), so a failing test report reads like a sentence describing what broke. Here is a bank-style example, with the three parts marked:

Kotlin Arrange, act, assert

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

All three lines end in OK. The second test checks something beginners forget: after the error, the object must still be in a valid state. The exception types come from require and check: require signals a bad argument (IllegalArgumentException), check signals a bad state (IllegalStateException).

Table-driven tests

When the same logic must hold for many inputs, put the cases in a list and loop. When one fails, include the input in the message so you know which case broke.

Kotlin Table-driven tests

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

The output is 6 cases, 0 failures. Include the edge cases in the table: 1900 and 2100 (divisible by 100 but not by 400) are exactly what a careless implementation gets wrong. Good test data comes from boundaries: zero, one, the maximum, empty, negative, null.

Tests as a safety net for refactoring

Tests have another job: they let you rewrite code without fear. Below, a loop-based function is replaced by a shorter version. The same test table is run against both, and any difference would show up at once.

Kotlin Same tests, two implementations

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

Both lines read all 5 cases pass. If the short version had a bug, the failing inputs would be listed. This is the habit that makes teams fast: write the test first or alongside, then change the implementation freely.

What to test, and what not to

  • Test behavior through the public API (inputs and outputs), not private details. Tests tied to the internals break whenever you refactor.
  • Test the unhappy paths: invalid input, empty collections, exceptions.
  • Keep tests independent: no test may rely on another having run first, and no test may depend on the clock, random numbers or the network. When code needs those, pass them in; see test doubles and testing coroutines.
  • Keep tests fast. A suite that runs in seconds gets run constantly; one that takes minutes gets skipped.
  • Do not chase 100% coverage as a goal. Cover the logic where bugs would hurt.

Common mistakes

  • Swapping the arguments. assertEquals(expected, actual) has an order. Reversed, the failure message lies to you.
  • A test that cannot fail. Always see a new test fail once (change the expected value) to prove it checks something.
  • Catching the exception yourself with try/catch and forgetting the "nothing was thrown" case. assertFailsWith handles it.
  • Comparing floating-point numbers with ==. 0.1 + 0.2 is not exactly 0.3. The real library has assertEquals(expected, actual, absoluteTolerance) for doubles.
  • Shared mutable state between tests, like a top-level list that tests append to.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does assertFailsWith<IllegalArgumentException> { parsePrice("abc") } check?

    It fails if nothing is thrown or a different exception type is thrown, and otherwise returns the exception so you can check its message.
  2. 2. In test reports, what is the difference between a failure and an error?

    A failure means the code produced a different result than expected. An error means something unexpected was thrown, usually a bug.
  3. 3. What goes first in assertEquals(a, b) in kotlin.test?

    The signature is assertEquals(expected, actual). Reversed arguments make failure messages misleading.
  4. 4. What does the @Test annotation do in a real kotlin.test or JUnit class?

    The runner scans for @Test functions and runs each one, creating a fresh instance of the class for every test.
  5. 5. Which of these is a good test-design rule?

    Independent tests of observable behavior survive refactoring; edge cases and error paths are where bugs hide.

Summary

  • A test calls your code and asserts the result; kotlin.test with JUnit and Gradle is the standard setup, and it is not available in this site's runner.
  • The core is three tools: assertEquals(expected, actual), assertTrue, and assertFailsWith<T> { }.
  • Failures are broken expectations; errors are unexpected exceptions.
  • Structure each test as arrange, act, assert, and name it after one behavior.
  • Table-driven tests cover many inputs; include edge cases.
  • Keep tests fast, independent and focused on public behavior; inject time, randomness and I/O.

Next: Test Doubles