typelevel / munit-cats-effect

Integration library for MUnit & cats-effect

Version Matrix

munit-cats-effect

Integration library for MUnit and cats-effect.

Binaries

Cats Effect 2 integration is provided via:

libraryDependencies += "org.typelevel" %%% "munit-cats-effect-2" % "1.0.0" % "test"

Cats Effect 3 integration is provided via:

libraryDependencies += "org.typelevel" %%% "munit-cats-effect-3" % "1.0.0" % "test"

Builds are available for Scala 2.12, 2.13, and 3 for both the JVM and Scala.js.

Getting Started

The munit.CatsEffectSuite trait provides the ability to write tests that return IO and SyncIO values without needing to call any unsafe methods (e.g. unsafeRunSync()).

import cats.effect.{IO, SyncIO}
import munit.CatsEffectSuite

class ExampleSuite extends CatsEffectSuite {

  test("tests can return IO[Unit] with assertions expressed via a map") {
    IO(42).map(it => assertEquals(it, 42))
  }

  test("alternatively, asertions can be written via assertIO") {
    assertIO(IO(42), 42)
  }

  test("or via assertEquals syntax") {
    IO(42).assertEquals(42)
  }

  test("or via plain assert syntax on IO[Boolean]") {
    IO(true).assert
  }

  test("SyncIO works too") {
    SyncIO(42).assertEquals(42)
  }

  import cats.effect.std.Dispatcher

  val dispatcher = ResourceFixture(Dispatcher[IO])

  dispatcher.test("resources can be lifted to munit fixtures") { dsp =>
    dsp.unsafeRunAndForget(IO(42))
  }
}

There are more assertion functions like interceptIO and interceptMessageIO as well as syntax versions intercept and interceptMessage. See the CatsEffectAssertions trait for full details.

Suite-local fixtures

MUnit supports reusable suite-local fixtures that are instantiated only once for the entire test suite. This is useful when an expensive resource (like an HTTP client) is needed for each test case but it is undesirable to allocate a new one each time.

import cats.effect.{IO, Resource}

class SuiteLocalExampleSuite extends CatsEffectSuite {

  val myFixture = ResourceSuiteLocalFixture(
    "my-fixture",
    Resource.make(IO.unit)(_ => IO.unit)
  )

  override def munitFixtures = List(myFixture)

  test("first test") {
    IO(myFixture()).assertEquals(())
  }

  test("second test") {
    IO(myFixture()).assertEquals(())
  }

}

Notice that this integration is not pure; myFixture is mutated internally when the framework initializes the fixture, so the same reference that is used from test cases must be specified in munitFixtures. Otherwise an exception FixtureNotInstantiatedException will be thrown.