assertions
id: assertions title: 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:158)
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:158)
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:158)
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:158)
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:158)
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:158)
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:158)
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:158)
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:158)
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.
intercept()
Use intercept() when you expect a particular exception to be thrown by the test code (i.e. the test succeeds if the given Exception is thrown)
intercept[java.lang.IllegalArgumentException]{
// code expected to throw exception here
}
// munit.FailException: expected exception of type 'java.lang.IllegalArgumentException' but body evaluated successfully
// at munit.Assertions.fail(Assertions.scala:158)
interceptMessage()
Like intercept() except you can also specify a specific message the given Exception must match.
interceptMessage[java.lang.IllegalArgumentException]("argument type mismatch"){
// code expected to throw exception here
}
// munit.FailException: expected exception of type 'java.lang.IllegalArgumentException' but body evaluated successfully
// at munit.Assertions.fail(Assertions.scala:158)
fail()
Use fail() to make the test case fail immediately.
fail("test failed")
// munit.FailException: test failed
// at munit.Assertions.fail(Assertions.scala:158)
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:158)