0
# Assertions
1

2
Comprehensive assertion system with 100+ built-in assertions for testing values, collections, exceptions, and more. The assertion library provides both simple equality checks and complex structural validations.
3

4
## Capabilities
5

6
### Core Assertion Type
7

8
The fundamental assertion type that powers all ZIO Test assertions.
9

10
```scala { .api }
11
/**
12
 * Core assertion type for testing values of type A
13
 */
14
case class Assertion[-A](arrow: TestArrow[A, Boolean]) {
15
  /** Combine assertions with logical AND */
16
  def &&[A1 <: A](that: Assertion[A1]): Assertion[A1]
17
  
18
  /** Combine assertions with logical OR */
19
  def ||[A1 <: A](that: Assertion[A1]): Assertion[A1]
20
  
21
  /** Negate this assertion */
22
  def unary_! : Assertion[A]
23
  
24
  /** Test a value against this assertion */
25
  def test(value: A)(implicit sourceLocation: SourceLocation): Boolean
26
  
27
  /** Run assertion and return TestResult */
28
  def run(value: => A)(implicit sourceLocation: SourceLocation): TestResult
29
  
30
  /** Add label to assertion for better error messages */
31
  def label(message: String): Assertion[A]
32
}
33
```
34

35
### Basic Assertion Functions
36

37
Essential assertion functions available in the package object.
38

39
```scala { .api }
40
/**
41
 * Asserts that the given test was completed
42
 */
43
def assertCompletes(implicit trace: Trace, sourceLocation: SourceLocation): TestResult
44

45
/**
46
 * Effectful version of assertCompletes  
47
 */
48
def assertCompletesZIO(implicit trace: Trace, sourceLocation: SourceLocation): UIO[TestResult]
49

50
/**
51
 * Asserts that the given test was never completed
52
 */
53
def assertNever(message: String)(implicit trace: Trace, sourceLocation: SourceLocation): TestResult
54
```
55

56
### Custom Assertion Creation
57

58
Functions for creating custom assertions from predicates and transformations.
59

60
```scala { .api }
61
/**
62
 * Creates a new assertion from a function
63
 * @param name - Name of the assertion for error reporting
64
 * @param run - Function that tests the assertion condition
65
 * @return New Assertion instance
66
 */
67
def assertion[A](name: String)(run: (=> A) => Boolean): Assertion[A]
68

69
/**
70
 * Creates a recursive assertion that transforms input before testing
71
 * @param name - Name of the assertion
72
 * @param assertion - Assertion to apply to transformed value
73
 * @param get - Function to extract testable value from input
74
 * @return New Assertion instance
75
 */
76
def assertionRec[A, B](name: String)(assertion: Assertion[B])(get: A => Option[B]): Assertion[A]
77
```
78

79
**Usage Examples:**
80

81
```scala
82
import zio.test._
83
import zio.test.Assertion._
84

85
// Custom assertion for even numbers
86
val isEven = assertion[Int]("isEven")(n => n % 2 == 0)
87

88
test("custom assertions") {
89
  assert(4)(isEven) &&
90
  assert(List(2, 4, 6))(forall(isEven))
91
}
92

93
// Recursive assertion for optional fields
94
val hasValidEmail = assertionRec[User, String]("hasValidEmail")(
95
  containsString("@")
96
)(user => user.email)
97

98
test("recursive assertions") {
99
  val user = User("Alice", Some("alice@example.com"))
100
  assert(user)(hasValidEmail)
101
}
102
```
103

104
### Value Equality Assertions
105

106
Fundamental equality and comparison assertions.
107

108
```scala { .api }
109
/**
110
 * Asserts that the value equals the expected value
111
 */
112
def equalTo[A](expected: A): Assertion[A]
113

114
/**
115
 * Asserts that the value does not equal the specified value
116
 */  
117
def not[A](assertion: Assertion[A]): Assertion[A]
118

119
/**
120
 * Asserts that the value is one of the specified values
121
 */
122
def isOneOf[A](values: A*): Assertion[A]
123

124
/**
125
 * Asserts that the value is a subtype of the specified type
126
 */
127
def isSubtype[A, B <: A](implicit classTag: ClassTag[B]): Assertion[A]
128
```
129

130
### Numeric Assertions
131

132
Assertions for numeric comparisons and ranges.
133

134
```scala { .api }
135
/**
136
 * Asserts that the numeric value is approximately equal within tolerance
137
 */
138
def approximatelyEquals[A: Numeric](expected: A, tolerance: A): Assertion[A]
139

140
/**
141
 * Asserts that the value is less than expected
142
 */
143
def isLessThan[A: Ordering](expected: A): Assertion[A]
144

145
/**
146
 * Asserts that the value is less than or equal to expected
147
 */
148
def isLessThanEqualTo[A: Ordering](expected: A): Assertion[A]
149

150
/**
151
 * Asserts that the value is greater than expected
152
 */  
153
def isGreaterThan[A: Ordering](expected: A): Assertion[A]
154

155
/**
156
 * Asserts that the value is greater than or equal to expected
157
 */
158
def isGreaterThanEqualTo[A: Ordering](expected: A): Assertion[A]
159

160
/**
161
 * Asserts that the numeric value is within the specified range
162
 */
163
def isWithin[A: Numeric](min: A, max: A): Assertion[A]
164

165
/**
166
 * Asserts that the numeric value is positive
167
 */
168
def isPositive[A: Numeric]: Assertion[A]
169

170
/**
171
 * Asserts that the numeric value is negative  
172
 */
173
def isNegative[A: Numeric]: Assertion[A]
174

175
/**
176
 * Asserts that the numeric value is zero
177
 */ 
178
def isZero[A: Numeric]: Assertion[A]
179

180
/**
181
 * Asserts that the numeric value is non-negative (>= 0)
182
 */
183
def nonNegative[A: Numeric]: Assertion[A]
184

185
/**
186
 * Asserts that the numeric value is non-positive (<= 0)
187
 */
188
def nonPositive[A: Numeric]: Assertion[A]
189
```
190

191
**Usage Examples:**
192

193
```scala
194
import zio.test._
195
import zio.test.Assertion._
196

197
test("numeric assertions") {
198
  assert(42)(equalTo(42)) &&
199
  assert(3.14159)(approximatelyEquals(3.14, 0.01)) &&
200
  assert(10)(isGreaterThan(5)) &&
201
  assert(10)(isLessThanEqualTo(10)) &&
202
  assert(7)(isWithin(5, 10)) &&
203
  assert(42)(isPositive) &&
204
  assert(-5)(isNegative) &&
205
  assert(0)(isZero)
206
}
207
```
208

209
### Collection Assertions
210

211
Comprehensive assertions for testing collections, sequences, and iterables.
212

213
```scala { .api }
214
/**
215
 * Asserts that the collection contains the specified element
216
 */
217
def contains[A](expected: A): Assertion[Iterable[A]]
218

219
/**
220
 * Asserts that at least one element satisfies the assertion
221
 */
222
def exists[A](assertion: Assertion[A]): Assertion[Iterable[A]]
223

224
/**
225
 * Asserts that all elements satisfy the assertion
226
 */
227
def forall[A](assertion: Assertion[A]): Assertion[Iterable[A]]
228

229
/**
230
 * Asserts that the collection has the specified size
231
 */
232
def hasSize[A](expected: Int): Assertion[Iterable[A]]
233

234
/**
235
 * Asserts that the collection has the element at the specified index
236
 */
237
def hasAt[A](index: Int)(assertion: Assertion[A]): Assertion[Seq[A]]
238

239
/**
240
 * Asserts that the first element satisfies the assertion
241
 */
242
def hasFirst[A](assertion: Assertion[A]): Assertion[Iterable[A]]
243

244
/**
245
 * Asserts that the last element satisfies the assertion  
246
 */
247
def hasLast[A](assertion: Assertion[A]): Assertion[Iterable[A]]
248

249
/**
250
 * Asserts that the collection is empty
251
 */
252
def isEmpty: Assertion[Iterable[Any]]
253

254
/**
255
 * Asserts that the collection is non-empty
256
 */
257
def isNonEmpty: Assertion[Iterable[Any]]
258

259
/**
260
 * Asserts that elements are distinct (no duplicates)
261
 */
262
def isDistinct[A]: Assertion[Iterable[A]]
263

264
/**
265
 * Asserts that the collection is sorted according to natural ordering
266
 */
267
def isSorted[A: Ordering]: Assertion[Seq[A]]
268

269
/**
270
 * Asserts that the collection is sorted in reverse order
271
 */
272
def isSortedReverse[A: Ordering]: Assertion[Seq[A]]
273
```
274

275
**Usage Examples:**
276

277
```scala
278
import zio.test._
279
import zio.test.Assertion._
280

281
test("collection assertions") {
282
  val numbers = List(1, 2, 3, 4, 5)
283
  val empty = List.empty[Int]
284
  val sorted = List(1, 3, 5, 7, 9)
285
  
286
  assert(numbers)(contains(3)) &&
287
  assert(numbers)(hasSize(5)) &&
288
  assert(numbers)(forall(isPositive)) &&
289
  assert(numbers)(exists(equalTo(4))) &&
290
  assert(numbers)(hasFirst(equalTo(1))) &&
291
  assert(numbers)(hasLast(equalTo(5))) &&
292
  assert(numbers)(hasAt(2)(equalTo(3))) &&
293
  assert(numbers)(isNonEmpty) &&
294
  assert(empty)(isEmpty) &&
295
  assert(sorted)(isSorted) &&
296
  assert(List(1, 2, 3, 1))(not(isDistinct))
297
}
298
```
299

300
### Set Operations
301

302
Assertions for set-like operations on collections.
303

304
```scala { .api }
305
/**
306
 * Asserts that collections have the same elements (order-independent)
307
 */
308
def hasSameElements[A](expected: Iterable[A]): Assertion[Iterable[A]]
309

310
/**
311
 * Asserts that collections have the same distinct elements
312
 */  
313
def hasSameElementsDistinct[A](expected: Iterable[A]): Assertion[Iterable[A]]
314

315
/**
316
 * Asserts that the collection is a subset of expected
317
 */
318
def hasSubset[A](expected: Iterable[A]): Assertion[Iterable[A]]
319

320
/**
321
 * Asserts that collections have non-empty intersection
322
 */
323
def hasIntersection[A](expected: Iterable[A]): Assertion[Iterable[A]]
324

325
/**
326
 * Asserts that the collection contains at least one of the expected elements
327
 */
328
def hasAtLeastOneOf[A](expected: Iterable[A]): Assertion[Iterable[A]]
329

330
/**
331
 * Asserts that the collection contains at most one of the expected elements
332
 */
333
def hasAtMostOneOf[A](expected: Iterable[A]): Assertion[Iterable[A]]
334

335
/**
336
 * Asserts that the collection contains exactly one of the expected elements
337
 */
338
def hasOneOf[A](expected: Iterable[A]): Assertion[Iterable[A]]
339

340
/**
341
 * Asserts that the collection contains none of the expected elements
342
 */
343
def hasNoneOf[A](expected: Iterable[A]): Assertion[Iterable[A]]
344
```
345

346
### Sequence Assertions
347

348
Assertions specific to ordered sequences.
349

350
```scala { .api }
351
/**
352
 * Asserts that the sequence starts with the expected prefix
353
 */
354
def startsWith[A](expected: Seq[A]): Assertion[Seq[A]]
355

356
/**
357
 * Asserts that the sequence ends with the expected suffix
358
 */
359
def endsWith[A](expected: Seq[A]): Assertion[Seq[A]]
360
```
361

362
### Map Assertions
363

364
Specialized assertions for map-like collections.
365

366
```scala { .api }
367
/**
368
 * Asserts that the map contains the specified key
369
 */
370
def hasKey[K](expected: K): Assertion[Map[K, Any]]
371

372
/**
373
 * Asserts that the map contains all specified keys
374
 */
375
def hasKeys[K](expected: K*): Assertion[Map[K, Any]]
376

377
/**
378
 * Asserts that the map contains all specified values  
379
 */
380
def hasValues[V](expected: V*): Assertion[Map[Any, V]]
381
```
382

383
### String Assertions
384

385
String-specific assertion functions.
386

387
```scala { .api }
388
/**
389
 * Asserts that the string contains the expected substring
390
 */
391
def containsString(expected: String): Assertion[String]
392

393
/**
394
 * Asserts that the string starts with the expected prefix
395
 */
396
def startsWithString(expected: String): Assertion[String]
397

398
/**
399
 * Asserts that the string ends with the expected suffix
400
 */
401
def endsWithString(expected: String): Assertion[String]
402

403
/**
404
 * Asserts that strings are equal ignoring case
405
 */
406
def equalsIgnoreCase(expected: String): Assertion[String]
407

408
/**
409
 * Asserts that the string matches the regex pattern
410
 */
411
def matchesRegex(regex: String): Assertion[String]
412

413
/**
414
 * Asserts that the string has the specified length
415
 */
416
def hasSizeString(expected: Int): Assertion[String]
417
```
418

419
**Usage Examples:**
420

421
```scala
422
import zio.test._
423
import zio.test.Assertion._
424

425
test("string assertions") {
426
  val text = "Hello World"
427
  val email = "user@example.com"
428
  
429
  assert(text)(containsString("World")) &&
430
  assert(text)(startsWithString("Hello")) &&
431
  assert(text)(endsWithString("World")) &&
432
  assert(text)(hasSizeString(11)) &&
433
  assert("HELLO")(equalsIgnoreCase("hello")) &&
434
  assert(email)(matchesRegex(".*@.*\\..*"))
435
}
436
```
437

438
### Option Assertions
439

440
Assertions for Option values.
441

442
```scala { .api }
443
/**
444
 * Asserts that the Option is Some and the value satisfies the assertion
445
 */
446
def isSome[A](assertion: Assertion[A]): Assertion[Option[A]]
447

448
/**
449
 * Asserts that the Option is None
450
 */
451
def isNone: Assertion[Option[Any]]
452
```
453

454
### Either Assertions
455

456
Assertions for Either values.
457

458
```scala { .api }
459
/**  
460
 * Asserts that the Either is Left and the value satisfies the assertion
461
 */
462
def isLeft[A](assertion: Assertion[A]): Assertion[Either[A, Any]]
463

464
/**
465
 * Asserts that the Either is Right and the value satisfies the assertion
466
 */
467
def isRight[A](assertion: Assertion[A]): Assertion[Either[Any, A]]
468
```
469

470
### Try Assertions
471

472
Assertions for Try values.
473

474
```scala { .api }
475
/**
476
 * Asserts that the Try is Success and the value satisfies the assertion
477
 */
478
def isSuccess[A](assertion: Assertion[A]): Assertion[scala.util.Try[A]]
479

480
/**
481
 * Asserts that the Try is Failure and the exception satisfies the assertion
482
 */
483
def isFailure[A](assertion: Assertion[Throwable]): Assertion[scala.util.Try[A]]
484
```
485

486
### Exit Assertions
487

488
Assertions for ZIO Exit values.
489

490
```scala { .api }
491
/**
492
 * Asserts that the Exit succeeded and the value satisfies the assertion
493
 */
494
def succeeds[A](assertion: Assertion[A]): Assertion[Exit[Any, A]]
495

496
/**
497
 * Asserts that the Exit failed and the error satisfies the assertion
498
 */
499
def fails[E](assertion: Assertion[E]): Assertion[Exit[E, Any]]
500

501
/**
502
 * Asserts that the Exit died and the throwable satisfies the assertion
503
 */
504
def dies(assertion: Assertion[Throwable]): Assertion[Exit[Any, Any]]
505

506
/**
507
 * Asserts that the Exit died with a specific throwable type
508
 */
509
def diesWithA[A: ClassTag]: Assertion[Exit[Any, Any]]
510

511
/**
512
 * Asserts that the Exit failed with a specific error type  
513
 */
514
def failsWithA[A: ClassTag]: Assertion[Exit[A, Any]]
515

516
/**
517
 * Asserts that the Exit contains the specified cause
518
 */
519
def containsCause[E](assertion: Assertion[Cause[E]]): Assertion[Exit[E, Any]]
520
```
521

522
**Usage Examples:**
523

524
```scala
525
import zio.test._
526
import zio.test.Assertion._
527

528
test("exit assertions") {
529
  val success = Exit.succeed(42)
530
  val failure = Exit.fail("error")
531
  val die = Exit.die(new RuntimeException("boom"))
532
  
533
  assert(success)(succeeds(equalTo(42))) &&
534
  assert(failure)(fails(equalTo("error"))) &&
535
  assert(die)(dies(hasMessage(containsString("boom"))))
536
}
537
```
538

539
### Exception Assertions
540

541
Assertions for testing exception properties.
542

543
```scala { .api }
544
/**
545
 * Asserts that evaluating the expression throws an exception satisfying the assertion
546
 */
547
def throws[A](assertion: Assertion[Throwable]): Assertion[() => A]
548

549
/**
550
 * Asserts that evaluating the expression throws a specific exception type
551
 */
552
def throwsA[E: ClassTag]: Assertion[() => Any]
553

554
/**
555
 * Asserts that the throwable has the specified message
556
 */
557
def hasMessage(expected: String): Assertion[Throwable]
558

559
/**
560
 * Asserts that the throwable has suppressed exceptions satisfying the assertion
561
 */
562
def hasSuppressed(assertion: Assertion[Iterable[Throwable]]): Assertion[Throwable]
563

564
/**
565
 * Asserts that the throwable has a cause satisfying the assertion
566
 */
567
def hasThrowableCause(assertion: Assertion[Throwable]): Assertion[Throwable]
568
```
569

570
**Usage Examples:**
571

572
```scala
573
import zio.test._
574
import zio.test.Assertion._
575

576
test("exception assertions") {
577
  val divideByZero = () => 1 / 0
578
  val exception = new IllegalArgumentException("Invalid input")
579
  
580
  assert(divideByZero)(throwsA[ArithmeticException]) &&
581
  assert(exception)(hasMessage(containsString("Invalid")))
582
}
583
```