0
# ZIO Test
1

2
ZIO Test is a featherweight testing library for effectful programs. Built on ZIO's powerful effect system, it provides tools for testing concurrent, asynchronous, and resource-safe programs with deterministic testing capabilities, property-based testing, assertion combinators, and test environments that can be easily composed and managed.
3

4
## Package Information
5

6
- **Package Name**: zio-test
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Installation**: `libraryDependencies += "dev.zio" %% "zio-test" % "1.0.18"`
10

11
## Core Imports
12

13
```scala
14
import zio.test._
15
import zio.test.Assertion._
16
import zio.test.environment._
17
```
18

19
For specific modules:
20

21
```scala
22
import zio.test.{DefaultRunnableSpec, Gen, TestAspect}
23
import zio.test.mock.Mock
24
import zio.test.laws.ZLaws
25
```
26

27
## Basic Usage
28

29
```scala
30
import zio.test._
31
import zio.test.Assertion._
32
import zio.test.environment.TestEnvironment
33

34
object MyTest extends DefaultRunnableSpec {
35
  def spec = suite("my suite")(
36
    test("basic assertion") {
37
      assert(42)(equalTo(42))
38
    },
39
    testM("effectful test") {
40
      for {
41
        result <- ZIO.effectTotal(1 + 1)
42
      } yield assert(result)(equalTo(2))
43
    },
44
    test("property-based test") {
45
      check(Gen.int(1, 100)) { n =>
46
        assert(n * 2)(isGreaterThan(n))
47
      }
48
    }
49
  )
50
}
51
```
52

53
## Architecture
54

55
ZIO Test is built around several key components:
56

57
- **Core DSL**: Functions for creating tests (`test`, `testM`) and organizing them into suites (`suite`)
58
- **Assertion System**: Rich set of built-in assertions with composition operators
59
- **Property-Based Testing**: Generators (`Gen`) for creating test data and property verification functions
60
- **Test Environment**: Testable versions of ZIO services (`TestClock`, `TestConsole`, `TestRandom`, `TestSystem`)
61
- **Test Aspects**: Cross-cutting concerns like timeouts, retries, and conditional execution
62
- **Mock Framework**: Service mocking with expectation-based testing
63
- **Spec Framework**: Base classes for runnable test specifications
64

65
## Capabilities
66

67
### Core Testing DSL
68

69
Essential functions for creating and organizing tests with ZIO's effect system integration.
70

71
```scala { .api }
72
def test(label: String)(assertion: => TestResult): ZSpec[Any, Nothing]
73
def testM[R, E](label: String)(assertion: => ZIO[R, E, TestResult]): ZSpec[R, E]
74
def suite[R, E, T](label: String)(specs: Spec[R, E, T]*): Spec[R, E, T]
75

76
type ZTest[-R, +E] = ZIO[R, TestFailure[E], TestSuccess]
77
type ZSpec[-R, +E] = Spec[R, TestFailure[E], TestSuccess]
78
type TestResult = BoolAlgebra[AssertionResult]
79
```
80

81
[Core Testing DSL](./core-dsl.md)
82

83
### Assertion System
84

85
Comprehensive assertion library with 60+ built-in assertions and logical composition operators.
86

87
```scala { .api }
88
def assert[A](value: => A)(assertion: Assertion[A]): TestResult
89
def assertM[R, E, A](effect: ZIO[R, E, A])(assertion: AssertionM[A]): ZIO[R, E, TestResult]
90

91
// Built-in assertions
92
def equalTo[A](expected: A): Assertion[A]
93
def isGreaterThan[A](reference: A): Assertion[A]
94
def contains[A](element: A): Assertion[Iterable[A]]
95
def startsWith(prefix: String): Assertion[String]
96
val isTrue: Assertion[Boolean]
97
val isEmpty: Assertion[Iterable[Any]]
98
```
99

100
[Assertions](./assertions.md)
101

102
### Property-Based Testing
103

104
Sophisticated generator system for creating test data and verifying properties across input ranges.
105

106
```scala { .api }
107
def check[R <: TestConfig, A](rv: Gen[R, A])(test: A => TestResult): URIO[R, TestResult]
108
def checkM[R <: TestConfig, R1 <: R, E, A](rv: Gen[R, A])(test: A => ZIO[R1, E, TestResult]): ZIO[R1, E, TestResult]
109

110
final case class Gen[-R, +A](sample: ZStream[R, Nothing, Sample[R, A]])
111

112
// Built-in generators
113
val anyInt: Gen[Any, Int]
114
val anyString: Gen[Any, String]
115
def listOf[R, A](gen: Gen[R, A]): Gen[R with Sized, List[A]]
116
def oneOf[R, A](as: A*): Gen[R, A]
117
```
118

119
[Property-Based Testing](./property-testing.md)
120

121
### Test Environment
122

123
Testable versions of ZIO services enabling deterministic testing of time, console, randomness, and system properties.
124

125
```scala { .api }
126
type ZTestEnv = TestClock with TestConsole with TestRandom with TestSystem
127

128
// TestClock operations
129
def adjust(duration: Duration): URIO[TestClock, Unit]
130
def setTime(duration: Duration): URIO[TestClock, Unit]
131

132
// TestConsole operations
133
def feedLines(lines: String*): URIO[TestConsole, Unit] 
134
val output: ZIO[TestConsole, Nothing, Vector[String]]
135

136
// TestRandom operations
137
def feedInts(ints: Int*): URIO[TestRandom, Unit]
138
def setSeed(seed: Long): URIO[TestRandom, Unit]
139
```
140

141
[Test Environment](./test-environment.md)
142

143
### Test Aspects
144

145
Cross-cutting concerns for tests including timeouts, retries, conditional execution, and test organization.
146

147
```scala { .api }
148
abstract class TestAspect[+LowerR, -UpperR, +LowerE, -UpperE]
149

150
// Built-in aspects
151
val ignore: TestAspectAtLeastR[Annotations]
152
def timeout(duration: Duration): TestAspectAtLeastR[Live]
153
val flaky: TestAspectAtLeastR[Annotations]
154
def retry(schedule: Schedule[Any, TestFailure[Any], Any]): TestAspectPoly
155
def tag(tag: String, tags: String*): TestAspectPoly
156
```
157

158
[Test Aspects](./test-aspects.md)
159

160
### Mock Testing Framework
161

162
Service mocking system with expectation-based testing for ZIO services.
163

164
```scala { .api }
165
trait Mock[R]
166
abstract class Expectation[R]
167
sealed trait Capability[R, I, E, A]
168

169
// Mock creation
170
object MockClock extends Mock[Clock]
171
object MockConsole extends Mock[Console]
172
object MockRandom extends Mock[Random]
173
```
174

175
[Mock Testing](./mock-testing.md)
176

177
### Test Specifications
178

179
Base classes and utilities for creating runnable test specifications.
180

181
```scala { .api }
182
abstract class RunnableSpec[R, E]
183
abstract class DefaultRunnableSpec extends RunnableSpec[TestEnvironment, Any]
184

185
final case class Spec[-R, +E, +T](caseValue: SpecCase[R, E, T, Spec[R, E, T]])
186
```
187

188
[Test Specifications](./specifications.md)
189

190
## Types
191

192
### Core Types
193

194
```scala { .api }
195
// Test results
196
sealed trait TestSuccess
197
sealed trait TestFailure[+E]
198

199
// Assertion types  
200
final class Assertion[-A]
201
type AssertResult = BoolAlgebra[AssertionValue]
202
type AssertResultM = BoolAlgebraM[Any, Nothing, AssertionValue]
203

204
// Annotation types
205
type Annotated[+A] = (A, TestAnnotationMap)
206
trait TestAnnotation[V]
207

208
// Environment types
209
type TestEnvironment = TestClock with TestConsole with TestRandom with TestSystem with Annotations with Live
210
```
211

212
### Generator Types
213

214
```scala { .api }
215
final case class Gen[-R, +A](sample: ZStream[R, Nothing, Sample[R, A]])
216
final case class Sample[+R, +A](value: A, shrink: ZStream[R, Nothing, Sample[R, A]])
217

218
// Test configuration
219
type TestConfig = Has[TestConfig.Service]
220
type Sized = Has[Sized.Service]
221
```