0
# Assertion Framework
1

2
Rich assertion system with over 50 built-in assertions, logical combinators, and detailed failure reporting.
3

4
## Capabilities
5

6
### Core Assertion Functions
7

8
Basic assertion functions for testing values and effects.
9

10
```scala { .api }
11
/**
12
 * Checks that a value satisfies an assertion
13
 * @param value - The value to test (lazily evaluated)
14
 * @param assertion - The assertion to check
15
 * @returns TestResult indicating success or failure
16
 */
17
def assert[A](value: => A)(assertion: Assertion[A]): TestResult
18

19
/**
20
 * Checks that an effect produces a value satisfying an assertion
21
 * @param effect - ZIO effect to execute and test
22
 * @param assertion - The assertion to check against the effect result
23
 * @returns ZIO effect producing TestResult
24
 */
25
def assertM[R, E, A](effect: ZIO[R, E, A])(assertion: AssertionM[A]): ZIO[R, E, TestResult]
26

27
/**
28
 * Checks that all provided boolean expressions are true
29
 * @param exprs - Variable number of boolean expressions
30
 * @returns TestResult for all expressions
31
 */
32
def assertTrue(exprs: Boolean*): TestResult
33

34
/**
35
 * Assertion that a test completes successfully
36
 */
37
val assertCompletes: TestResult
38

39
/**
40
 * Effectful assertion that a test completes successfully
41
 */
42
val assertCompletesM: UIO[TestResult]
43
```
44

45
### Assertion Class
46

47
Core assertion type with logical combinators.
48

49
```scala { .api }
50
/**
51
 * An assertion that can be checked against a value of type A
52
 * @tparam A - The type of value this assertion can check
53
 */
54
case class Assertion[A](arrow: TestArrow[A, Boolean]) {
55
  /** Evaluates the assertion against a value */
56
  def run(actual: A): AssertResult
57
  
58
  /** Logical AND - both assertions must pass */
59
  def &&(that: Assertion[A]): Assertion[A]
60
  
61
  /** Logical OR - either assertion must pass */
62
  def ||(that: Assertion[A]): Assertion[A]
63
  
64
  /** Logical NOT - assertion must fail */
65
  def unary_!: Assertion[A]
66
  
67
  /** Adds a descriptive label to the assertion */
68
  def label(string: String): Assertion[A]
69
}
70
```
71

72
### Basic Assertions
73

74
Fundamental assertions for common testing scenarios.
75

76
```scala { .api }
77
/** Assertion that always succeeds */
78
val anything: Assertion[Any]
79

80
/** Assertion that always fails */
81
val nothing: Assertion[Any]
82

83
/** Checks that value is null */
84
val isNull: Assertion[Any]
85

86
/** Checks that value is not null */
87
val isNonNull: Assertion[Any]
88

89
/** Checks that value equals expected value */
90
def equalTo[A](expected: A): Assertion[A]
91

92
/** Negates another assertion */
93
def not[A](assertion: Assertion[A]): Assertion[A]
94

95
/** Checks that value is the unit value */
96
val isUnit: Assertion[Unit]
97
```
98

99
### Boolean Assertions
100

101
Specific assertions for boolean values.
102

103
```scala { .api }
104
/** Checks that boolean value is true */
105
val isTrue: Assertion[Boolean]
106

107
/** Checks that boolean value is false */
108
val isFalse: Assertion[Boolean]
109
```
110

111
### Numeric Assertions
112

113
Assertions for comparing numeric values.
114

115
```scala { .api }
116
/** Checks that value is greater than reference */
117
def isGreaterThan[A: Ordering](reference: A): Assertion[A]
118

119
/** Checks that value is greater than or equal to reference */
120
def isGreaterThanEqualTo[A: Ordering](reference: A): Assertion[A]
121

122
/** Checks that value is less than reference */
123
def isLessThan[A: Ordering](reference: A): Assertion[A]
124

125
/** Checks that value is less than or equal to reference */
126
def isLessThanEqualTo[A: Ordering](reference: A): Assertion[A]
127

128
/** Checks that value is within tolerance of reference */
129
def isWithin[A: Numeric](reference: A, tolerance: A): Assertion[A]
130

131
/** Checks that value approximately equals reference within tolerance */
132
def approximatelyEquals[A: Numeric](reference: A, tolerance: A): Assertion[A]
133

134
/** Checks that numeric value is positive */
135
def isPositive[A: Numeric]: Assertion[A]
136

137
/** Checks that numeric value is negative */
138
def isNegative[A: Numeric]: Assertion[A]
139

140
/** Checks that numeric value is zero */
141
def isZero[A: Numeric]: Assertion[A]
142

143
/** Checks that numeric value is not zero */
144
def isNonZero[A: Numeric]: Assertion[A]
145
```
146

147
### String Assertions
148

149
Specialized assertions for string values.
150

151
```scala { .api }
152
/** Case-insensitive string equality */
153
def equalToIgnoringCase(expected: String): Assertion[String]
154

155
/** Checks that string starts with prefix */
156
def startsWithString(prefix: String): Assertion[String]
157

158
/** Checks that string ends with suffix */
159
def endsWithString(suffix: String): Assertion[String]
160

161
/** Checks that string contains substring */
162
def containsString(element: String): Assertion[String]
163

164
/** Checks that string matches regular expression */
165
def matchesRegex(regex: String): Assertion[String]
166

167
/** Checks that string is empty */
168
val isEmptyString: Assertion[String]
169

170
/** Checks that string is not empty */
171
val isNonEmptyString: Assertion[String]
172
```
173

174
### Collection Assertions
175

176
Assertions for testing collections and iterables.
177

178
```scala { .api }
179
/** Checks that collection is empty */
180
val isEmpty: Assertion[Iterable[Any]]
181

182
/** Checks that collection is not empty */
183
val isNonEmpty: Assertion[Iterable[Any]]
184

185
/** Checks that collection size satisfies assertion */
186
def hasSize[A](assertion: Assertion[Int]): Assertion[Iterable[A]]
187

188
/** Checks that collection contains element */
189
def contains[A](element: A): Assertion[Iterable[A]]
190

191
/** Checks that collection contains all specified elements */
192
def containsAll[A](elements: A*): Assertion[Iterable[A]]
193

194
/** Checks that at least one element satisfies assertion */
195
def exists[A](assertion: Assertion[A]): Assertion[Iterable[A]]
196

197
/** Checks that all elements satisfy assertion */
198
def forall[A](assertion: Assertion[A]): Assertion[Iterable[A]]
199

200
/** Checks that collection has same elements as other (order independent) */
201
def hasSameElements[A](other: Iterable[A]): Assertion[Iterable[A]]
202

203
/** Checks that collection is subset of another */
204
def isSubsetOf[A](other: Iterable[A]): Assertion[Iterable[A]]
205

206
/** Checks that collection is superset of another */
207
def isSupersetOf[A](other: Iterable[A]): Assertion[Iterable[A]]
208

209
/** Checks that all elements in collection are distinct */
210
val isDistinct: Assertion[Iterable[Any]]
211

212
/** Checks that list is sorted according to ordering */
213
def isSorted[A: Ordering]: Assertion[List[A]]
214
```
215

216
### Option Assertions
217

218
Assertions for testing Option values.
219

220
```scala { .api }
221
/** Checks that Option is Some and its value satisfies assertion */
222
def isSome[A](assertion: Assertion[A]): Assertion[Option[A]]
223

224
/** Checks that Option is None */
225
val isNone: Assertion[Option[Any]]
226

227
/** Checks that Option is defined (Some) */
228
val isDefined: Assertion[Option[Any]]
229
```
230

231
### Either Assertions
232

233
Assertions for testing Either values.
234

235
```scala { .api }
236
/** Checks that Either is Left and its value satisfies assertion */
237
def isLeft[A](assertion: Assertion[A]): Assertion[Either[A, Any]]
238

239
/** Checks that Either is Right and its value satisfies assertion */
240
def isRight[A](assertion: Assertion[A]): Assertion[Either[Any, A]]
241
```
242

243
### Exception and ZIO Assertions
244

245
Assertions for testing exceptions and ZIO effects.
246

247
```scala { .api }
248
/** Checks that expression throws exception satisfying assertion */
249
def throws[A](assertion: Assertion[Throwable]): Assertion[A]
250

251
/** Checks that expression throws specific exception type */
252
def throwsA[E <: Throwable]: Assertion[Any]
253

254
/** Checks that ZIO effect dies with throwable satisfying assertion */
255
def dies(assertion: Assertion[Throwable]): Assertion[ZIO[Any, Any, Any]]
256

257
/** Checks that ZIO effect fails with error satisfying assertion */
258
def fails[E](assertion: Assertion[E]): Assertion[ZIO[Any, E, Any]]
259

260
/** Checks that ZIO effect succeeds with value satisfying assertion */
261
def succeeds[A](assertion: Assertion[A]): Assertion[ZIO[Any, Any, A]]
262

263
/** Checks that ZIO effect is interrupted */
264
val isInterrupted: Assertion[ZIO[Any, Any, Any]]
265
```
266

267
## Usage Examples
268

269
```scala
270
import zio.test._
271
import zio.test.Assertion._
272

273
// Basic assertions
274
test("equality") {
275
  assert(2 + 2)(equalTo(4))
276
}
277

278
test("numeric comparisons") {
279
  assert(42)(isGreaterThan(40) && isLessThan(50))
280
}
281

282
test("string operations") {
283
  assert("Hello World")(
284
    startsWithString("Hello") &&
285
    endsWithString("World") &&
286
    containsString(" ")
287
  )
288
}
289

290
test("collection testing") {
291
  assert(List(1, 2, 3, 2))(
292
    hasSize(equalTo(4)) &&
293
    contains(2) &&
294
    !isDistinct
295
  )
296
}
297

298
test("option testing") {
299
  assert(Some(42))(isSome(isGreaterThan(40)))
300
  assert(None)(isNone)
301
}
302

303
test("either testing") {
304
  assert(Right(42))(isRight(equalTo(42)))
305
  assert(Left("error"))(isLeft(equalToIgnoringCase("ERROR")))
306
}
307

308
testM("effect assertions") {
309
  for {
310
    _ <- assertM(ZIO.succeed(42))(equalTo(42))
311
    _ <- assertM(ZIO.fail("boom"))(anything)
312
  } yield assertCompletes
313
}
314
```