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:252)
//  at munit.Assertions.fail$(Assertions.scala:246)
//  at munit.FunSuite.fail(FunSuite.scala:11)
//  at munit.Assertions.$anonfun$assert$1(Assertions.scala:32)
//  at scala.runtime.java8.JFunction0$mcV$sp.apply(JFunction0$mcV$sp.scala:18)
//  at munit.internal.console.StackTraces$.dropInside(StackTraces.scala:10)
//  at munit.Assertions.assert(Assertions.scala:29)
//  at munit.Assertions.assert$(Assertions.scala:25)
//  at munit.FunSuite.assert(FunSuite.scala:11)
//  at repl.MdocSession$App$$anonfun$3.apply$mcV$sp(assertions.md:29)
//  at repl.MdocSession$App$$anonfun$3.apply(assertions.md:29)
//  at repl.MdocSession$App$$anonfun$3.apply(assertions.md:29)

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:252)
//  at munit.Assertions.fail$(Assertions.scala:246)
//  at munit.FunSuite.fail(FunSuite.scala:11)
//  at munit.Assertions.$anonfun$assert$1(Assertions.scala:32)
//  at scala.runtime.java8.JFunction0$mcV$sp.apply(JFunction0$mcV$sp.scala:18)
//  at munit.internal.console.StackTraces$.dropInside(StackTraces.scala:10)
//  at munit.Assertions.assert(Assertions.scala:29)
//  at munit.Assertions.assert$(Assertions.scala:25)
//  at munit.FunSuite.assert(FunSuite.scala:11)
//  at repl.MdocSession$App$$anonfun$5.apply$mcV$sp(assertions.md:39)
//  at repl.MdocSession$App$$anonfun$5.apply(assertions.md:39)
//  at repl.MdocSession$App$$anonfun$5.apply(assertions.md:39)

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:252)
//  at munit.Assertions.fail$(Assertions.scala:246)
//  at munit.FunSuite.fail(FunSuite.scala:11)
//  at munit.Assertions.$anonfun$assert$1(Assertions.scala:32)
//  at scala.runtime.java8.JFunction0$mcV$sp.apply(JFunction0$mcV$sp.scala:18)
//  at munit.internal.console.StackTraces$.dropInside(StackTraces.scala:10)
//  at munit.Assertions.assert(Assertions.scala:29)
//  at munit.Assertions.assert$(Assertions.scala:25)
//  at munit.FunSuite.assert(FunSuite.scala:11)
//  at repl.MdocSession$App$$anonfun$7.apply$mcV$sp(assertions.md:49)
//  at repl.MdocSession$App$$anonfun$7.apply(assertions.md:49)
//  at repl.MdocSession$App$$anonfun$7.apply(assertions.md:49)

Note, the -Yrangepos compiler option is required for clue() to work correctly. When -Yrangepos is not enabled you may see output like this instead:

// Clues {
//   : Int = 1
//   : Int = 2
// }

To fix this problem in sbt, add the following line to your settings:

 // build.sbt
 lazy val myProject = project
   .settings(
+    scalacOptions += "-Yrangepos"
   )

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:252)
//  at munit.Assertions.fail$(Assertions.scala:246)
//  at munit.FunSuite.fail(FunSuite.scala:11)
//  at munit.Assertions.$anonfun$assert$1(Assertions.scala:32)
//  at scala.runtime.java8.JFunction0$mcV$sp.apply(JFunction0$mcV$sp.scala:18)
//  at munit.internal.console.StackTraces$.dropInside(StackTraces.scala:10)
//  at munit.Assertions.assert(Assertions.scala:29)
//  at munit.Assertions.assert$(Assertions.scala:25)
//  at munit.FunSuite.assert(FunSuite.scala:11)
//  at repl.MdocSession$App$$anonfun$9.apply$mcV$sp(assertions.md:59)
//  at repl.MdocSession$App$$anonfun$9.apply(assertions.md:59)
//  at repl.MdocSession$App$$anonfun$9.apply(assertions.md:59)

assertEquals()

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

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

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(
//   name = "MUnit",
//   awesome = true,
//   versions = Range(0, 1)
// )
val mdocLibrary = Library("MDoc", true)
// mdocLibrary: Library = Library(
//   name = "MDoc",
//   awesome = true,
//   versions = Range(0, 1)
// )

assertEquals(munitLibrary, mdocLibrary)
// munit.ComparisonFailException: values are not the same
// => Obtained
// Library(
//   name = "MUnit",
//   awesome = true,
//   versions = Range(
//     0,
//     1
//   )
// )
// => Diff (- obtained, + expected)
//  Library(
// -  name = "MUnit",
// +  name = "MDoc",
//    awesome = true,
//  at munit.Assertions.failComparison(Assertions.scala:274)

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.ComparisonFailException: values are not the same
// => Obtained
// Map(
//   1 -> List(
//     Range(
//       1,
//       2,
//       3
//     )
//   )
// )
// => Diff (- obtained, + expected)
//        2,
// -      3
// +      3,
// +      4
//      )
//  at munit.Assertions.failComparison(Assertions.scala:274)

Comparing two values of different types is a compile error.

assertEquals(Option("message"), "message")
// error: Can't compare these two types:
//   First type:  Option[String]
//   Second type: String
// Possible ways to fix this error:
//   Alternative 1: provide an implicit instance for Compare[Option[String], String]
//   Alternative 2: upcast either type into `Any` or a shared supertype
// Error occurred in an application involving default arguments.
// assertEquals(Option("message"), "message")
// ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

It's a compile error even if the comparison is true at runtime.

assertEquals(List(1), Vector(1))
// error: Can't compare these two types:
//   First type:  List[Int]
//   Second type: scala.collection.immutable.Vector[Int]
// Possible ways to fix this error:
//   Alternative 1: provide an implicit instance for Compare[List[Int], scala.collection.immutable.Vector[Int]]
//   Alternative 2: upcast either type into `Any` or a shared supertype
// Error occurred in an application involving default arguments.
// assertEquals(Option("message"), "message")
// ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

assertEquals('a', 'a'.toInt)
// error: Can't compare these two types:
//   First type:  Char
//   Second type: Int
// Possible ways to fix this error:
//   Alternative 1: provide an implicit instance for Compare[Char, Int]
//   Alternative 2: upcast either type into `Any` or a shared supertype
// Error occurred in an application involving default arguments.
// assertEquals(Option("message"), "message")
// ^^^^^^^^^^^^^^^^^^^^^^^^^^^^

It's OK to compare two types as long as one argument is a subtype of the other type.

assertEquals(Option(1), Some(1)) // OK // OK
assertEquals(Some(1), Option(1)) // OK

Use assertEquals[Any, Any] if you think it's OK to compare the two types at runtime.

val right1: Either[String      , Int] = Right(42)
// right1: Either[String, Int] = Right(value = 42)
val right2: Either[List[String], Int] = Right(42)
// right2: Either[List[String], Int] = Right(value = 42)

assertEquals[Any, Any](right1, right2)

assertNotEquals()

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

assertNotEquals(a, a)
// munit.ComparisonFailException: values are the same expected same: 1 was not: 1
//  at munit.Assertions.failComparison(Assertions.scala:274)

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.ComparisonFailException: 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.failComparison(Assertions.scala:274)

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:252)
//  at munit.Assertions.fail$(Assertions.scala:246)
//  at munit.FunSuite.fail(FunSuite.scala:11)
//  at munit.Assertions.runIntercept(Assertions.scala:194)
//  at munit.Assertions.intercept(Assertions.scala:176)
//  at munit.Assertions.intercept$(Assertions.scala:173)
//  at munit.FunSuite.intercept(FunSuite.scala:11)
//  at repl.MdocSession$App$$anonfun$38.apply(assertions.md:191)
//  at repl.MdocSession$App$$anonfun$38.apply(assertions.md:191)

interceptMessage()

Like intercept() except additionally asserts that the thrown exception has a specific error message.

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:252)
//  at munit.Assertions.fail$(Assertions.scala:246)
//  at munit.FunSuite.fail(FunSuite.scala:11)
//  at munit.Assertions.runIntercept(Assertions.scala:194)
//  at munit.Assertions.interceptMessage(Assertions.scala:185)
//  at munit.Assertions.interceptMessage$(Assertions.scala:182)
//  at munit.FunSuite.interceptMessage(FunSuite.scala:11)
//  at repl.MdocSession$App$$anonfun$40.apply(assertions.md:203)
//  at repl.MdocSession$App$$anonfun$40.apply(assertions.md:203)

fail()

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

fail("test failed")
// munit.FailException: test failed
//  at munit.Assertions.fail(Assertions.scala:252)
//  at munit.Assertions.fail$(Assertions.scala:246)
//  at munit.FunSuite.fail(FunSuite.scala:11)
//  at repl.MdocSession$App$$anonfun$42.apply(assertions.md:215)
//  at repl.MdocSession$App$$anonfun$42.apply(assertions.md:215)

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:252)
//  at munit.Assertions.fail$(Assertions.scala:246)
//  at munit.FunSuite.fail(FunSuite.scala:11)
//  at repl.MdocSession$App$$anonfun$44.apply(assertions.md:225)
//  at repl.MdocSession$App$$anonfun$44.apply(assertions.md:225)

compileErrors()

Use compileErrors() to assert that an example code snippet fails with a specific compile-time error message.

assertNoDiff(
  compileErrors("Set(2, 1).sorted"),
     """|error: value sorted is not a member of scala.collection.immutable.Set[Int]
        |Set(2, 1).sorted
        |          ^
        |""".stripMargin
)

The argument to compileErrors must be a string literal. It's not possible to pass in more complicated expressions such as variables or string interpolators.

val code = """val x: String = 2"""
compileErrors(code)
compileErrors(s"/* code */ $code")
// error: cannot compile dynamic expressions, only constant literals.
// To fix this problem, pass in a string literal in double quotes "..."
// compileErrors(code)
//               ^^^^
// error: cannot compile dynamic expressions, only constant literals.
// To fix this problem, pass in a string literal in double quotes "..."
// compileErrors(s"/* code */ $code")
//               ^^^^^^^^^^^^^^^^^^

Inline the code variable to fix the compile error.

compileErrors("val x: String = 2")
// res9: String = """error:
// type mismatch;
//  found   : Int(2)
//  required: String
// val x: String = 2
//                 ^"""