Edit

Getting started

MUnit is a Scala testing library with the following goals:

• Reuse JUnit: MUnit is implemented as a JUnit runner and tries to build on top of existing JUnit functionality where possible. Any tool that knows how to run a JUnit test suite knows how to run MUnit, including IDEs like IntelliJ.
• Actionable errors: test reports are pretty-printed with colors to help you quickly understand what caused a test failure. MUnit tries to displays diffs and source locations when possible and it does a best-effort to highlight relevant stack trace elements.
• No Scala dependencies: MUnit has no external Scala dependencies so that it can easily cross-build against a wide range of Scala compiler versions.
• Cross-platform: MUnit compiles to JVM bytecode, JavaScript via Scala.js and ahead-of-time optimized binaries via Scala Native/LLVM.

Quick start

scala-cli:

//> using test.dep org.scalameta::munit::1.0.4

sbt:

libraryDependencies += "org.scalameta" %% "munit" % "1.0.4" % Test
// Use %%% for non-JVM projects.

If you are using a version of sbt lower than 1.5.0, you will also need to add:

testFrameworks += new TestFramework("munit.Framework")

Mill

object test extends ScalaTests with TestModule.Munit {
  override def ivyDeps =
    Agg(
      ivy"org.scalameta::munit::1.0.4"
    )
}

Maven

<dependency>
  <groupId>org.scalameta</groupId>
  <artifactId>munit_3</artifactId>
  <version>1.0.4</version>
  <scope>test</scope>
</dependency>

The complete setup can be seen in a Maven g8 template scalameta/maven-scala-seed.g8

Supported Platforms

Scala Version	JVM	Scala.js (0.6.x)	Scala.js (1.x)	Native (0.4.x)	Native (0.5.x)
2.11.x	✅	✅ until 0.7.16	✅	✅	n/a
2.12.x	✅	✅ until 0.7.16	✅	✅	✅
2.13.x	✅	✅ until 0.7.16	✅	✅	✅
3.x	✅	n/a	✅	n/a	✅

Next, write a test suite.

class MySuite extends munit.FunSuite {
  test("hello") {
    val obtained = 42
    val expected = 43
    assertEquals(obtained, expected)
  }
}

Run tests in sbt

Execute sbt test to run MUnit tests in the terminal. It's recommended to stay in the sbt shell for the best compiler performance.

$ sbt
> test

Use testOnly to run only a single test suite in the sbt shell.

# sbt shell
> testOnly com.MySuite

Run tests in IntelliJ

MUnit test suites can be executed from in IntelliJ like normal test suites. Please ensure that the JUnit plugin is enabled.

It's possible to run individual test cases from IntelliJ by clicking on the green "Play" icon in the left gutter. Alternatively, you can also use the .only marker to run an individual test.

- test("name") {
+ test("name".only) {
    // ...
  }

Run tests in VS Code

MUnit test suites can be executed from VS Code like normal test suites.

Search for failed tests in CI logs

Test results are formatted in a specific way to make it easy to search for them in a large log file.

Test	Prefix	Comment	See Also
Success	+
Failed	==> X		Writing assertions
Ignored	==> i	ignored	Filtering tests
Pending	==> i	PENDING	Declaring tests
Skipped	==> s		Filtering tests

Knowing these prefixes may come in handy for example when browsing test logs in a browser. Search for ==> X to quickly navigate to the failed tests.

Usage guide

See the guide on writing tests to learn more about using MUnit.

Why JUnit?

MUnit builds on top of JUnit in order to benefit from existing JUnit tooling integrations. For example, IntelliJ can already automatically detect JUnit test suites and provides a nice interface to explore JUnit test results. Some build tools like Pants also have built-in support to JUnit test suites.

Why not just JUnit?

The default JUnit testing syntax is based on annotations and does not feel idiomatic when used from Scala. MUnit tries to fill in the gap by providing a small Scala API on top of JUnit.

Inspirations

MUnit is inspired by several existing testing libraries:

• ScalaTest: the syntax for defining munit.FunSuite test suites is the same as for org.scalatest.FunSuite.
• JUnit: MUnit is implemented as a custom JUnit runner and features like assume test filters are implemented on top of existing JUnit functionality.
• utest: the nicely formatted stack traces and test reports is heavily inspired by the beautifully formatted output in utest.
• ava: the idea for showing the source locations for assertion errors comes from ava, a JavaScript testing library.