0
# ZIO Test
1
2
ZIO Test is a featherweight testing library for effectful programs built on ZIO, providing a comprehensive framework for property-based testing, test composition, and resource-safe test execution. It enables developers to write tests that are both expressive and reliable, with automatic resource cleanup, deterministic test execution through ZIO's effect system, and rich assertion capabilities.
3
4
## Package Information
5
6
- **Package Name**: zio-test
7
- **Package Type**: Maven
8
- **Language**: Scala
9
- **Installation**:
10
```scala
11
// SBT
12
libraryDependencies += "dev.zio" %% "zio-test" % "2.1.19" % Test
13
libraryDependencies += "dev.zio" %% "zio-test-sbt" % "2.1.19" % Test
14
15
// Mill
16
def testDeps = Agg(ivy"dev.zio::zio-test:2.1.19")
17
```
18
19
## Core Imports
20
21
```scala
22
import zio.test._
23
import zio.test.Assertion._
24
```
25
26
For basic testing with default environment:
27
28
```scala
29
import zio.test._
30
31
object MyTest extends ZIOSpecDefault {
32
def spec = suite("my tests")(
33
test("basic test") {
34
assertTrue(2 + 2 == 4)
35
}
36
)
37
}
38
```
39
40
For testing with custom environment:
41
42
```scala
43
import zio.test._
44
45
object MyTest extends ZIOSpec[MyTestEnvironment] {
46
type Env = MyTestEnvironment
47
48
def spec = suite("my tests")(
49
test("custom environment test") {
50
for {
51
service <- ZIO.service[MyService]
52
result <- service.doSomething()
53
} yield assertTrue(result.isSuccess)
54
}
55
)
56
}
57
```
58
59
## Basic Usage
60
61
```scala
62
import zio.test._
63
import zio.test.Assertion._
64
65
object ExampleTest extends ZIOSpecDefault {
66
def spec = suite("Example Tests")(
67
68
// Basic assertion test
69
test("simple assertion") {
70
assertTrue(2 + 2 == 4)
71
},
72
73
// Effectful test
74
test("effectful computation") {
75
for {
76
result <- ZIO.succeed(42)
77
} yield assertTrue(result > 40)
78
},
79
80
// Property-based test
81
test("property test") {
82
check(Gen.int) { n =>
83
assertTrue((n + 1) > n)
84
}
85
},
86
87
// Test with custom assertion
88
test("collection assertion") {
89
val numbers = List(1, 2, 3, 4, 5)
90
assertTrue(
91
numbers.contains(3) &&
92
numbers.size == 5 &&
93
numbers.forall(_ > 0)
94
)
95
}
96
)
97
}
98
```
99
100
## Architecture
101
102
ZIO Test is built around several key components:
103
104
- **Spec DSL**: Hierarchical test structure using `suite()` and `test()` for organizing tests
105
- **Assertion System**: Rich assertion library with smart assertions (Scala 3) and traditional assertion functions
106
- **Property Testing**: Comprehensive generator system (`Gen`) for property-based testing with automatic shrinking
107
- **Test Services**: Controllable test environment services (TestClock, TestConsole, TestRandom, etc.) for deterministic testing
108
- **Test Aspects**: Cross-cutting concerns like timeouts, retries, parallelism, and lifecycle hooks
109
- **Effect Integration**: Seamless ZIO effect system integration with proper resource management and error handling
110
111
## Capabilities
112
113
### Core Testing DSL
114
115
Essential functions for creating test specifications and organizing test suites. The foundation of all ZIO Test usage.
116
117
```scala { .api }
118
def suite[In](label: String)(specs: In*)(implicit
119
suiteConstructor: SuiteConstructor[In]
120
): Spec[suiteConstructor.OutEnvironment, suiteConstructor.OutError]
121
122
def test[In](label: String)(assertion: => In)(implicit
123
testConstructor: TestConstructor[Nothing, In]
124
): testConstructor.Out
125
126
type ZTest[-R, +E] = ZIO[R, TestFailure[E], TestSuccess]
127
```
128
129
[Core Testing DSL](./core-testing.md)
130
131
### Smart Assertions (Scala 3)
132
133
Compile-time smart assertions with automatic expression analysis and enhanced error reporting for more intuitive test writing.
134
135
```scala { .api }
136
inline def assertTrue(inline assertion: Boolean)(implicit
137
trace: Trace, sourceLocation: SourceLocation
138
): TestResult
139
140
inline def assert[A](inline value: A)(inline assertion: Assertion[A])(implicit
141
trace: Trace, sourceLocation: SourceLocation
142
): TestResult
143
144
inline def assertZIO[R, E, A](effect: ZIO[R, E, A])(inline assertion: Assertion[A])(implicit
145
trace: Trace, sourceLocation: SourceLocation
146
): ZIO[R, E, TestResult]
147
```
148
149
[Smart Assertions](./smart-assertions.md)
150
151
### Assertion Library
152
153
Comprehensive assertion system with 100+ built-in assertions for values, collections, exceptions, and more.
154
155
```scala { .api }
156
case class Assertion[-A](arrow: TestArrow[A, Boolean])
157
158
def equalTo[A](expected: A): Assertion[A]
159
def contains[A](expected: A): Assertion[Iterable[A]]
160
def hasSize[A](expected: Int): Assertion[Iterable[A]]
161
def isLessThan[A: Ordering](expected: A): Assertion[A]
162
def startsWith[A](expected: Seq[A]): Assertion[Seq[A]]
163
def succeeds[A](assertion: Assertion[A]): Assertion[Exit[Any, A]]
164
def fails[E](assertion: Assertion[E]): Assertion[Exit[E, Any]]
165
```
166
167
[Assertions](./assertions.md)
168
169
### Property-Based Testing
170
171
Generator system for creating random test data and property-based testing with automatic shrinking support.
172
173
```scala { .api }
174
case class Gen[-R, +A](sample: ZStream[R, Nothing, Sample[R, A]])
175
176
def check[R, A, In](rv: Gen[R, A])(test: A => In)(implicit
177
checkConstructor: CheckConstructor[R, In]
178
): ZIO[checkConstructor.OutEnvironment, checkConstructor.OutError, TestResult]
179
180
def checkAll[R, A, In](rv: Gen[R, A])(test: A => In)(implicit
181
checkConstructor: CheckConstructor[R, In]
182
): ZIO[checkConstructor.OutEnvironment, checkConstructor.OutError, TestResult]
183
184
def int: Gen[Any, Int]
185
def string: Gen[Any, String]
186
def listOf[A](gen: Gen[Any, A]): Gen[Any, List[A]]
187
```
188
189
[Property Testing](./property-testing.md)
190
191
### Test Services
192
193
Controllable test environment services that replace real services with deterministic, testable implementations.
194
195
```scala { .api }
196
trait TestClock extends Clock
197
trait TestConsole extends Console
198
trait TestRandom extends Random
199
trait TestSystem extends System
200
trait TestConfig
201
202
type TestEnvironment = Annotations with Live with Sized with TestConfig
203
204
def testClock(implicit trace: Trace): UIO[TestClock]
205
def testConsole(implicit trace: Trace): UIO[TestConsole]
206
def testRandom(implicit trace: Trace): UIO[TestRandom]
207
def testSystem(implicit trace: Trace): UIO[TestSystem]
208
```
209
210
[Test Services](./test-services.md)
211
212
### Test Aspects
213
214
Cross-cutting concerns for configuring test execution, lifecycle, timeouts, retries, and environment management.
215
216
```scala { .api }
217
abstract class TestAspect[-R0, +R1, -E0, +E1]
218
219
def timeout(duration: Duration): TestAspectPoly
220
def ignore: TestAspectPoly
221
def flaky(n: Int): TestAspectPoly
222
def parallel: TestAspectPoly
223
def sequential: TestAspectPoly
224
def before[R](zio: ZIO[R, Nothing, Any]): TestAspect[Nothing, R, Nothing, Any]
225
def after[R](zio: ZIO[R, Nothing, Any]): TestAspect[Nothing, R, Nothing, Any]
226
```
227
228
[Test Aspects](./test-aspects.md)
229
230
## Types
231
232
```scala { .api }
233
// Core test specification type
234
final case class Spec[-R, +E](caseValue: SpecCase[R, E, Spec[R, E]])
235
236
// Test result types
237
sealed trait TestSuccess
238
sealed trait TestFailure[+E]
239
case class TestResult(arrow: TestArrow[Any, Boolean])
240
241
// Base specification classes
242
abstract class ZIOSpecDefault extends ZIOSpec[TestEnvironment]
243
abstract class ZIOSpec[R] extends ZIOSpecAbstract[R]
244
abstract class ZIOSpecAbstract[R]
245
246
// Environment and configuration
247
type TestEnvironment = Annotations with Live with Sized with TestConfig
248
```