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
```