0
# Assertions
1

2
Rich assertion methods that provide type-safe comparisons with detailed failure messages and helpful diff output. The assertion system is designed to give actionable error messages that help developers quickly identify and fix test failures.
3

4
## Capabilities
5

6
### Basic Assertions
7

8
Core assertion methods for general-purpose testing.
9

10
```scala { .api }
11
/**
12
 * Basic boolean assertion with optional clue
13
 * @param cond The condition to assert
14
 * @param clue Additional context for failure messages
15
 */
16
def assert(cond: => Boolean, clue: => Any = "assertion failed")(implicit loc: Location): Unit
17

18
/**
19
 * Assumption for conditional test execution
20
 * @param cond The condition to assume
21
 * @param clue Additional context if assumption fails
22
 */
23
def assume(cond: Boolean, clue: => Any = "assumption failed")(implicit loc: Location): Unit
24
```
25

26
**Usage Examples:**
27

28
```scala
29
class AssertionExamples extends FunSuite {
30
  test("basic assertions") {
31
    assert(2 + 2 == 4)
32
    assert(List(1, 2, 3).nonEmpty, "List should not be empty")
33
    
34
    // Conditional test execution
35
    assume(System.getProperty("os.name").contains("Linux"))
36
    // Test only runs on Linux
37
  }
38
}
39
```
40

41
### Equality Assertions
42

43
Type-safe equality checks with comprehensive diff output for failures.
44

45
```scala { .api }
46
/**
47
 * Assert that two values are equal with type-safe comparison
48
 * @param obtained The actual value
49
 * @param expected The expected value
50
 * @param clue Additional context for failure messages
51
 */
52
def assertEquals[A, B](obtained: A, expected: B, clue: => Any = "values are not the same")(implicit loc: Location, compare: Compare[A, B], diffOptions: DiffOptions): Unit
53

54
/**
55
 * Assert that two values are not equal
56
 * @param obtained The actual value
57
 * @param expected The value that should not match
58
 * @param clue Additional context for failure messages
59
 */
60
def assertNotEquals[A, B](obtained: A, expected: B, clue: => Any = "values are the same")(implicit loc: Location, compare: Compare[A, B]): Unit
61
```
62

63
**Usage Examples:**
64

65
```scala
66
class EqualityExamples extends FunSuite {
67
  test("value equality") {
68
    val user = User("Alice", 25)
69
    val expected = User("Alice", 25)
70
    assertEquals(user, expected)
71
  }
72
  
73
  test("collection equality") {
74
    val list1 = List(1, 2, 3)
75
    val list2 = List(1, 2, 3)
76
    assertEquals(list1, list2)
77
    
78
    val different = List(1, 2, 4)
79
    assertNotEquals(list1, different)
80
  }
81
  
82
  test("with custom clue") {
83
    val result = processData(input)
84
    assertEquals(result.status, "success", s"Processing failed for input: $input")
85
  }
86
}
87
```
88

89
### Numeric Assertions
90

91
Specialized assertions for floating-point number comparisons with tolerance.
92

93
```scala { .api }
94
/**
95
 * Assert double equality with tolerance for floating-point precision
96
 * @param obtained The actual double value
97
 * @param expected The expected double value
98
 * @param delta The acceptable difference between values
99
 */
100
def assertEqualsDouble(obtained: Double, expected: Double, delta: Double, clue: => Any = "values are not the same")(implicit loc: Location): Unit
101

102
/**
103
 * Assert float equality with tolerance for floating-point precision
104
 * @param obtained The actual float value
105
 * @param expected The expected float value
106
 * @param delta The acceptable difference between values
107
 */
108
def assertEqualsFloat(obtained: Float, expected: Float, delta: Float, clue: => Any = "values are not the same")(implicit loc: Location): Unit
109
```
110

111
**Usage Examples:**
112

113
```scala
114
class NumericExamples extends FunSuite {
115
  test("floating point comparisons") {
116
    val result = 0.1 + 0.2
117
    assertEqualsDouble(result, 0.3, 0.0001)
118
    
119
    val calculation: Float = 1.0f / 3.0f * 3.0f
120
    assertEqualsFloat(calculation, 1.0f, 0.0001f)
121
  }
122
}
123
```
124

125
### String Assertions
126

127
String comparison with diff visualization for easy identification of differences.
128

129
```scala { .api }
130
/**
131
 * Assert string equality with diff output for mismatches
132
 * @param obtained The actual string
133
 * @param expected The expected string
134
 * @param clue Additional context for failure messages
135
 */
136
def assertNoDiff(obtained: String, expected: String, clue: => Any = "diff assertion failed")(implicit loc: Location, diffOptions: DiffOptions): Unit
137
```
138

139
**Usage Examples:**
140

141
```scala
142
class StringExamples extends FunSuite {
143
  test("string comparison with diff") {
144
    val generated = generateHtml()
145
    val expected = """
146
      |<html>
147
      |  <body>
148
      |    <h1>Hello, World!</h1>
149
      |  </body>
150
      |</html>
151
    """.stripMargin
152
    
153
    assertNoDiff(generated, expected)
154
  }
155
}
156
```
157

158
### Exception Assertions
159

160
Methods for testing that specific exceptions are thrown with optional message validation.
161

162
```scala { .api }
163
/**
164
 * Assert that a specific exception type is thrown
165
 * @param body The code that should throw an exception
166
 * @return The caught exception for further inspection
167
 */
168
def intercept[T <: Throwable](body: => Any)(implicit T: ClassTag[T], loc: Location): T
169

170
/**
171
 * Assert that a specific exception with a specific message is thrown
172
 * @param expectedExceptionMessage The expected exception message
173
 * @param body The code that should throw an exception
174
 * @return The caught exception for further inspection
175
 */
176
def interceptMessage[T <: Throwable](expectedExceptionMessage: String)(body: => Any)(implicit T: ClassTag[T], loc: Location): T
177
```
178

179
**Usage Examples:**
180

181
```scala
182
class ExceptionExamples extends FunSuite {
183
  test("exception handling") {
184
    intercept[ArithmeticException] {
185
      10 / 0
186
    }
187
    
188
    val exception = intercept[IllegalArgumentException] {
189
      validateAge(-5)
190
    }
191
    assert(exception.getMessage.contains("negative"))
192
  }
193
  
194
  test("exception with specific message") {
195
    interceptMessage[IllegalStateException]("Service not initialized") {
196
      service.process()
197
    }
198
  }
199
}
200
```
201

202
### Explicit Failures
203

204
Methods for explicitly failing tests with custom messages and context.
205

206
```scala { .api }
207
/**
208
 * Explicitly fail a test with a message and cause
209
 * @param message The failure message
210
 * @param cause The underlying exception that caused the failure
211
 */
212
def fail(message: String, cause: Throwable)(implicit loc: Location, diffOptions: DiffOptions): Nothing
213

214
/**
215
 * Explicitly fail a test with a message and clues
216
 * @param message The failure message
217
 * @param clues Additional debugging context
218
 */
219
def fail(message: String, clues: Clues = new Clues(Nil))(implicit loc: Location, diffOptions: DiffOptions): Nothing
220

221
/**
222
 * Fail with comparison context for IDE integration
223
 * @param message The failure message
224
 * @param obtained The actual value
225
 * @param expected The expected value
226
 * @param clues Additional debugging context
227
 */
228
def failComparison(message: String, obtained: Any, expected: Any, clues: Clues = new Clues(Nil))(implicit loc: Location, diffOptions: DiffOptions): Nothing
229

230
/**
231
 * Fail the entire test suite
232
 * @param message The failure message
233
 * @param clues Additional debugging context
234
 */
235
def failSuite(message: String, clues: Clues = new Clues(Nil))(implicit loc: Location, diffOptions: DiffOptions): Nothing
236
```
237

238
**Usage Examples:**
239

240
```scala
241
class FailureExamples extends FunSuite {
242
  test("conditional failure") {
243
    val result = complexOperation()
244
    if (!result.isValid) {
245
      fail(s"Operation failed: ${result.error}")
246
    }
247
  }
248
  
249
  test("failure with comparison") {
250
    val obtained = parseJson(input)
251
    val expected = ExpectedResult(...)
252
    
253
    if (obtained != expected) {
254
      failComparison("JSON parsing mismatch", obtained, expected)
255
    }
256
  }
257
}
258
```
259

260
### Debugging Support
261

262
Utilities for adding context and debugging information to test failures.
263

264
```scala { .api }
265
/**
266
 * Add a debugging clue to a value
267
 * @param c The clue containing debug information
268
 * @return The original value with attached debugging context
269
 */
270
def clue[T](c: Clue[T]): T
271

272
/**
273
 * Create a collection of clues for debugging
274
 * @param clue Variable number of clues to combine
275
 * @return Combined clues for debugging context
276
 */
277
def clues(clue: Clue[_]*): Clues
278

279
/**
280
 * Print a value using the configured printer
281
 * @param clue The value to print
282
 * @return String representation of the value
283
 */
284
def munitPrint(clue: => Any): String
285

286
/**
287
 * Get the current printer instance
288
 * @return The configured printer for formatting output
289
 */
290
def printer: Printer
291

292
/**
293
 * Check if ANSI colors are enabled for output
294
 */
295
def munitAnsiColors: Boolean
296
```
297

298
**Usage Examples:**
299

300
```scala
301
class DebuggingExamples extends FunSuite {
302
  test("with debugging clues") {
303
    val input = getData()
304
    val result = clue(processData(clue(input)))
305
    
306
    assertEquals(result.status, "success")
307
  }
308
  
309
  test("multiple clues") {
310
    val user = getUser()
311
    val permissions = getPermissions(user)
312
    
313
    assert(
314
      hasAccess(user, resource),
315
      clues(
316
        clue(user),
317
        clue(permissions),
318
        clue(resource)
319
      )
320
    )
321
  }
322
}
323
```