skip to content

What does kotlin.test's assertEquals do, and why does the order of its first two arguments matter?

level: juniorimportance: must knowfreq 80%

answer

  1. expected first, actual second
  2. uses == / .equals() (structural)
  3. order only changes the message
  4. trailing optional message arg
  5. Double needs absoluteTolerance overload

basics

~20 s

assertEquals checks that two values are equal and fails the test if they are not. You pass the expected value first and the actual value second; the order changes the failure message, not the pass/fail result.

solid answer

~30 s

`assertEquals(expected, actual, message?)` fails the test unless `expected == actual` (structural equality via `.equals()`). Equality is symmetric so swapping the two values never changes pass/fail, but kotlin.test prints `expected:<X> but was:<Y>`, so putting them in the wrong order yields a misleading diagnostic. Always pass the known/expected value first and the computed/actual value second. The optional trailing `message: String?` is appended to the failure output. For `Double`/`Float`, use the `absoluteTolerance` overload `assertEquals(expected, actual, absoluteTolerance)` instead of exact equality to avoid rounding-based failures.

code

kotlin · 5 lines
kotlin
import kotlin.test.assertEquals

assertEquals(4, 2 + 2)                 // expected, actual
assertEquals(4, 2 + 2, "math broke")  // with message
assertEquals(0.3, 0.1 + 0.2, absoluteTolerance = 1e-9)

go deeper

for a junior

Knows assertEquals fails when values differ and that expected goes first.

for a middle

Explains the message format expected:<> but was:<> and that equality is structural via ==.

for a senior

Mentions the absoluteTolerance overload for floats and the optional message arg, and why specific assertions beat assertTrue(a==b).

for a principal

Frames argument-order discipline as a team convention for readable failures and discusses structural-vs-referential equality trade-offs in test design.

## What `assertEquals` does `assertEquals(expected, actual, message?)` is the most-used assertion in `kotlin.test`. It fails the test if `expected != actual` (structural equality via the `equals` operator, i.e. Kotlin's `==`), and passes otherwise. ### Argument order matters for the failure message The signature is `assertEquals(expected, actual)`. The order does **not** change whether the test passes (equality is symmetric), but it **does** change the diagnostic message: kotlin.test prints something like `expected:<X> but was:<Y>`. Swapping the arguments produces a misleading message, so always put the *known/expected* value first. ```kotlin import kotlin.test.assertEquals import kotlin.test.Test class CalcTest { @Test fun adds() { val result = 2 + 2 assertEquals(4, result) // expected first, actual second assertEquals(4, result, "addition broke") // optional failure message } } ``` ### How equality is decided - It uses `==`, which calls `.equals()`. For `data class`, `String`, collections, etc. this is structural (value) equality. - It is **not** `assertSame` — two distinct objects that are `equals` will pass `assertEquals` but fail `assertSame`. ### Floating point caveat For `Double`/`Float`, `kotlin.test` offers an overload with an `absoluteTolerance`: `assertEquals(expected, actual, absoluteTolerance, message?)`. Use it instead of exact equality to avoid rounding failures: ```kotlin assertEquals(0.3, 0.1 + 0.2, absoluteTolerance = 1e-9) ``` ### The optional message Every core assertion ends with an optional trailing `message: String?`. It is appended to the failure output to explain *what* was being checked; it is never shown on success.

  • Does assertEquals use == or ===?
    `==` (structural equality, calls `.equals()`). For reference identity you need `assertSame`, which uses `===`.
  • How do you compare two Doubles safely?
    Use the overload with `absoluteTolerance`, e.g. `assertEquals(expected, actual, 1e-9)`, because floating-point arithmetic rarely yields bit-exact results.

Like labelling a before/after photo: swapping the labels doesn't change the photos, but anyone reading the caption gets confused.

saying these in an interview costs you the question

  • Says order changes whether the test passes
  • Puts actual first, expected second
  • Claims assertEquals compares references
  • Compares Doubles with exact assertEquals and no tolerance
  • Thinks the message shows on success

context

resolving links…