Edit

Writing assertions

MUnit provides a few ways to fail a test given a condition.

assert()

Use assert() to fail a test if a boolean condition does not hold true. For example, assume we have two values:

val a = 1
// a: Int = 1
val b = 2
// b: Int = 2

In the most basic case when no hints are provided, the error message is "assertion failed" when the condition is false.

assert(a > b)
// munit.FailException: assertion failed
//  at munit.Assertions.fail(Assertions.scala:134)

Include an optional message to explain why the assertion failed.

assert(a > b, "a was smaller than b")
// munit.FailException: a was smaller than b
//  at munit.Assertions.fail(Assertions.scala:134)

Use clue() to include optional clues in the boolean condition based on values in the expression.

assert(clue(a) > clue(b))
// munit.FailException: assertion failed
// Clues {
//   a: Int = 1
//   b: Int = 2
// }
//  at munit.Assertions.fail(Assertions.scala:134)

Clues can wrap more complicated expressions.

assert(clue(List(a).head) > clue(b))
// munit.FailException: assertion failed
// Clues {
//   List(a).head: Int = 1
//   b: Int = 2
// }
//  at munit.Assertions.fail(Assertions.scala:134)

assertEquals()

Use assertEquals() to assert that two values are the same.

assertEquals(a, b)
// munit.FailException: values are not the same
// => Obtained
// 1
// => Diff (- obtained, + expected)
// -1
// +2
//  at munit.Assertions.fail(Assertions.scala:134)

The error message automatically produces a diff on assertion failure.

case class Library(name: String, awesome: Boolean, versions: Range = 0.to(1))
val munitLibrary = Library("MUnit", true)
// munitLibrary: Library = Library("MUnit", true, Range.Inclusive(0, 1))
val mdocLibrary = Library("MDoc", true)
// mdocLibrary: Library = Library("MDoc", true, Range.Inclusive(0, 1))

assertEquals(munitLibrary, mdocLibrary)
// munit.FailException: values are not the same
// => Obtained
// Library(
//   "MUnit",
//   true,
//   Range.Inclusive(
//     0,
//     1
//   )
// )
// => Diff (- obtained, + expected)
//  Library(
// -  "MUnit",
// +  "MDoc",
//    true,
//  at munit.Assertions.fail(Assertions.scala:134)

Diffs make it easy to track down differences even in large data structures.

assertEquals(
  Map(1 -> List(1.to(3))),
  Map(1 -> List(1.to(4)))
)
// munit.FailException: values are not the same
// => Obtained
// Map(
//   1 -> List(
//     Range.Inclusive(
//       1,
//       2,
//       3
//     )
//   )
// )
// => Diff (- obtained, + expected)
//        2,
// -      3
// +      3,
// +      4
//      )
//  at munit.Assertions.fail(Assertions.scala:134)

Comparing two values of different types is a compile error.

assertEquals(1, "")
// error: Cannot prove that Int =:= String.
// Error occurred in an application involving default arguments.
// assertEquals(1, "")
// ^^^^^^^^^^^^^^^^^^^

The two types must match exactly, it's a type error to compare two values even if one value is a subtype of the other.

assertEquals(Some(1), Option(1))
// error: Cannot prove that Some[Int] =:= Option[Int].
// Error occurred in an application involving default arguments.
// assertEquals(Some(1): Option[Int], Option(1))
// ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Upcast the subtype using a type ascription subtype: Supertype when you want to compare a subtype with a supertype.

// OK
assertEquals(Some(1): Option[Int], Option(1))

assertNotEquals()

Use assertNotEqual() to assert that two values are not the same.

assertNotEquals(a, a)
// munit.FailException: values are the same
//  at munit.Assertions.fail(Assertions.scala:134)

The assertion does not fail when both values are different.

// OK
assertNotEquals(a, b)

assertNoDiff()

Use assertNoDiff() to compare two multiline strings.

val obtainedString = "val x = 41\nval y = 43\nval z = 43"
// obtainedString: String = """val x = 41
// val y = 43
// val z = 43"""
val expectedString = "val x = 41\nval y = 42\nval z = 43"
// expectedString: String = """val x = 41
// val y = 42
// val z = 43"""

assertNoDiff(obtainedString, expectedString)
// munit.FailException: diff assertion failed
// => Obtained
//     """|val x = 41
//        |val y = 43
//        |val z = 43
//        |""".stripMargin
// => Diff (- obtained, + expected)
//  val x = 41
// -val y = 43
// +val y = 42
//  val z = 43
//  at munit.Assertions.fail(Assertions.scala:134)

The difference between assertNoDiff() and assertEquals() is that assertEquals() fails according to the == method while assertNoDiff() ignores non-visible differences such as trailing/leading whitespace, Windows/Unix newlines and ANSI color codes. The "=> Obtained" section of assertNoDiff() error messages also include copy-paste friendly syntax using .stripMargin.

fail()

Use fail() to make the test case fail immediately.

fail("test failed")
// munit.FailException: test failed
//  at munit.Assertions.fail(Assertions.scala:134)

Use clues() to include optional context why the test failed.

fail("test failed", clues(a + b))
// munit.FailException: test failed
// Clues {
//   a + b: Int = 3
// }
//  at munit.Assertions.fail(Assertions.scala:134)