0
# MUnit
1

2
MUnit is a comprehensive Scala testing framework that provides actionable error messages and extensible APIs for writing and running tests. It supports cross-platform development across JVM, JavaScript, and Native platforms, offering a modern alternative to traditional testing frameworks like ScalaTest.
3

4
## Package Information
5

6
- **Package Name**: org.scalameta:munit_2.13
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Installation**: `libraryDependencies += "org.scalameta" %% "munit" % "1.1.1" % Test`
10

11
## Core Imports
12

13
```scala
14
import munit.FunSuite
15
```
16

17
For additional functionality:
18

19
```scala
20
import munit._
21
import munit.Assertions
22
import munit.Location
23
```
24

25
## Basic Usage
26

27
```scala
28
import munit.FunSuite
29

30
class ExampleSuite extends FunSuite {
31
  test("basic assertion") {
32
    val result = 2 + 2
33
    assertEquals(result, 4)
34
  }
35

36
  test("string comparison") {
37
    val message = "Hello, World!"
38
    assert(message.startsWith("Hello"))
39
  }
40

41
  test("exception handling") {
42
    intercept[ArithmeticException] {
43
      10 / 0
44
    }
45
  }
46

47
  test("async test") {
48
    Future.successful(42).map { result =>
49
      assertEquals(result, 42)
50
    }
51
  }
52
}
53
```
54

55
## Architecture
56

57
MUnit's architecture is built around several key components:
58

59
- **Test Suites**: Base classes (`Suite`, `FunSuite`) that organize and execute tests
60
- **Assertions**: Type-safe comparison methods with detailed failure messages
61
- **Fixtures**: Resource management for test setup and teardown (synchronous and asynchronous)
62
- **Transforms**: Extensible pipeline for customizing test and suite behavior
63
- **Framework Integration**: JUnit runner for IDE support and SBT framework for build tools
64
- **Cross-Platform Support**: Unified API across JVM, JavaScript, and Native platforms
65

66
The design emphasizes simplicity for basic use cases while providing powerful extension points for advanced scenarios through the transform system and fixture architecture.
67

68
## Capabilities
69

70
### Test Suite Classes
71

72
Core test suite classes that users extend to write tests. Includes `FunSuite` for function-style tests and `Suite` for minimal custom test suites.
73

74
```scala { .api }
75
abstract class FunSuite extends BaseFunSuite
76

77
abstract class Suite extends PlatformSuite {
78
  def munitTests(): Seq[Test]
79
  def munitFixtures: Seq[AnyFixture[_]] = Nil
80
  def beforeAll(): Unit = ()
81
  def afterAll(): Unit = ()
82
  def beforeEach(context: BeforeEach): Unit = ()
83
  def afterEach(context: AfterEach): Unit = ()
84
}
85
```
86

87
[Test Suites](./test-suites.md)
88

89
### Assertions and Testing
90

91
Rich assertion methods with type-safe comparisons and helpful diff output for test failures. Includes basic assertions, equality checks, exception handling, and failure methods.
92

93
```scala { .api }
94
def assert(cond: => Boolean, clue: => Any = "assertion failed")(implicit loc: Location): Unit
95
def assertEquals[A, B](obtained: A, expected: B, clue: => Any = "values are not the same")(implicit loc: Location, compare: Compare[A, B]): Unit
96
def intercept[T <: Throwable](body: => Any)(implicit T: ClassTag[T], loc: Location): T
97
def fail(message: String, clues: Clues = new Clues(Nil))(implicit loc: Location): Nothing
98
```
99

100
[Assertions](./assertions.md)
101

102
### Test Configuration and Metadata
103

104
Test configuration classes and metadata types for organizing and controlling test execution. Includes test options, tags, and source location tracking.
105

106
```scala { .api }
107
final class TestOptions(val name: String, val tags: Set[Tag], val location: Location) {
108
  def tag(t: Tag): TestOptions
109
  def ignore: TestOptions
110
  def only: TestOptions
111
  def fail: TestOptions
112
  def flaky: TestOptions
113
}
114

115
class Tag(val value: String) extends Annotation
116
```
117

118
[Configuration](./configuration.md)
119

120
### Fixtures and Lifecycle Management
121

122
Flexible fixture system for managing test resources with both synchronous and asynchronous support. Includes base fixtures, function-style fixtures, and lifecycle hooks.
123

124
```scala { .api }
125
abstract class AnyFixture[T](val fixtureName: String) {
126
  def apply(): T
127
  def beforeAll(): Any = ()
128
  def afterAll(): Any = ()
129
}
130

131
abstract class Fixture[T](name: String) extends AnyFixture[T](name)
132
abstract class FutureFixture[T](name: String) extends AnyFixture[T](name)
133
```
134

135
[Fixtures](./fixtures.md)
136

137
### Exception Handling
138

139
Comprehensive exception classes for test failures with IDE integration and detailed error reporting. Includes comparison failures, suite failures, and custom exception types.
140

141
```scala { .api }
142
class FailException(val message: String, val cause: Throwable, val isStackTracesEnabled: Boolean, val location: Location) extends AssertionError
143
class ComparisonFailException extends ComparisonFailure with FailExceptionLike[ComparisonFailException]
144
```
145

146
[Exceptions](./exceptions.md)
147

148
### Transforms and Extensions
149

150
Extensible transform system for customizing test and suite behavior. Allows modification of individual tests, entire suites, and return value handling.
151

152
```scala { .api }
153
final class TestTransform(val name: String, fn: Test => Test) extends Function1[Test, Test]
154
final class SuiteTransform(val name: String, fn: List[Test] => List[Test]) extends Function1[List[Test], List[Test]]
155
final class ValueTransform(val name: String, fn: PartialFunction[Any, Future[Any]]) extends Function1[Any, Option[Future[Any]]]
156
```
157

158
[Transforms](./transforms.md)
159

160
## Types
161

162
```scala { .api }
163
final class Test(val name: String, val body: () => Future[Any], val tags: Set[Tag], val location: Location)
164
final class Location(val path: String, val line: Int) extends Annotation
165
class BeforeEach(val test: Test)
166
class AfterEach(val test: Test)
167
```