0
# Core Testing DSL
1

2
Essential functions for creating and organizing tests with ZIO's effect system integration. The core DSL provides the fundamental building blocks for test creation and suite organization.
3

4
## Capabilities
5

6
### Test Creation
7

8
Create individual tests with pure or effectful assertions.
9

10
```scala { .api }
11
/**
12
 * Creates a pure test with a synchronous assertion
13
 * @param label - Test description/name
14
 * @param assertion - Pure test result containing assertions
15
 * @returns Spec that can be included in a suite
16
 */
17
def test(label: String)(assertion: => TestResult): ZSpec[Any, Nothing]
18

19
/**
20
 * Creates an effectful test with an asynchronous assertion
21
 * @param label - Test description/name  
22
 * @param assertion - ZIO effect that produces a test result
23
 * @returns Spec that requires environment R and may fail with E
24
 */
25
def testM[R, E](label: String)(assertion: => ZIO[R, E, TestResult]): ZSpec[R, E]
26
```
27

28
**Usage Examples:**
29

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

34
// Pure test
35
test("addition works") {
36
  assert(2 + 2)(equalTo(4))
37
}
38

39
// Effectful test
40
testM("async operation") {
41
  for {
42
    result <- ZIO.effectTotal(fetchSomeData())
43
    validation <- ZIO.effectTotal(validateData(result))
44
  } yield assert(validation)(isTrue)
45
}
46

47
// Test with environment requirements
48
testM("database test") {
49
  for {
50
    user <- UserService.createUser("john", "john@example.com")
51
    found <- UserService.findByEmail("john@example.com")
52
  } yield assert(found)(isSome(equalTo(user)))
53
}
54
```
55

56
### Suite Organization
57

58
Group related tests into hierarchical suites.
59

60
```scala { .api }
61
/**
62
 * Creates a test suite containing multiple specs
63
 * @param label - Suite description/name
64
 * @param specs - Variable number of test specs to include
65
 * @returns Combined spec containing all provided specs
66
 */
67
def suite[R, E, T](label: String)(specs: Spec[R, E, T]*): Spec[R, E, T]
68

69
/**
70
 * Creates an effectful suite where the specs are computed
71
 * @param label - Suite description/name
72
 * @param specs - Effect that produces an iterable of specs
73
 * @returns Spec that computes its children dynamically
74
 */
75
def suiteM[R, E, T](label: String)(specs: ZIO[R, E, Iterable[Spec[R, E, T]]]): Spec[R, E, T]
76
```
77

78
**Usage Examples:**
79

80
```scala
81
// Basic suite
82
suite("math operations")(
83
  test("addition") { assert(1 + 1)(equalTo(2)) },
84
  test("subtraction") { assert(5 - 3)(equalTo(2)) },
85
  test("multiplication") { assert(3 * 4)(equalTo(12)) }
86
)
87

88
// Nested suites
89
suite("user management")(
90
  suite("user creation")(
91
    test("valid user") { /* test */ },
92
    test("invalid email") { /* test */ }
93
  ),
94
  suite("user deletion")(
95
    test("existing user") { /* test */ },
96
    test("non-existent user") { /* test */ }
97
  )
98
)
99

100
// Dynamic suite
101
suiteM("generated tests") {
102
  ZIO.effectTotal(
103
    (1 to 10).map { i =>
104
      test(s"test $i") {
105
        assert(i * 2)(isGreaterThan(i))
106
      }
107
    }
108
  )
109
}
110
```
111

112
### Assertion Functions
113

114
Core assertion functions for test validation.
115

116
```scala { .api }
117
/**
118
 * Creates a test result by applying an assertion to a value
119
 * @param value - Value to test (computed lazily)
120
 * @param assertion - Assertion to apply to the value
121
 * @returns Test result indicating success or failure
122
 */
123
def assert[A](value: => A)(assertion: Assertion[A]): TestResult
124

125
/**
126
 * Creates an effectful test result by applying an assertion to an effect's result
127
 * @param effect - ZIO effect that produces a value to test
128
 * @param assertion - Assertion to apply to the effect's result
129
 * @returns ZIO effect that produces a test result
130
 */
131
def assertM[R, E, A](effect: ZIO[R, E, A])(assertion: AssertionM[A]): ZIO[R, E, TestResult]
132
```
133

134
**Usage Examples:**
135

136
```scala
137
// Pure assertion
138
assert(calculateResult())(equalTo(42))
139

140
// Effectful assertion
141
assertM(databaseQuery)(contains(expectedRecord))
142

143
// Multiple assertions
144
assert(user.name)(equalTo("John")) &&
145
assert(user.age)(isGreaterThan(18)) &&
146
assert(user.email)(contains("@"))
147
```
148

149
### Completion Assertions
150

151
Special assertions for testing completion without specific values.
152

153
```scala { .api }
154
/**
155
 * Asserts that the test completes successfully
156
 */
157
val assertCompletes: TestResult
158

159
/**
160
 * Effectful version that asserts completion
161
 */
162
val assertCompletesM: UIO[TestResult]
163
```
164

165
**Usage Examples:**
166

167
```scala
168
test("operation completes") {
169
  performSideEffect()
170
  assertCompletes
171
}
172

173
testM("async operation completes") {
174
  for {
175
    _ <- performAsyncOperation()
176
    result <- assertCompletesM
177
  } yield result
178
}
179
```
180

181
### Test Result Utilities
182

183
Utilities for creating specific test outcomes.
184

185
```scala { .api }
186
/**
187
 * Creates a failed test result with the specified runtime cause
188
 * @param cause - The cause of the test failure
189
 * @returns ZIO effect that fails with TestFailure
190
 */
191
def failed[E](cause: Cause[E]): ZIO[Any, TestFailure[E], Nothing]
192

193
/**
194
 * Creates an ignored test result
195
 * @returns ZIO effect that produces TestSuccess.Ignored
196
 */
197
val ignored: UIO[TestSuccess]
198
```
199

200
**Platform and Version Specific Testing:**
201

202
```scala { .api }
203
/**
204
 * Creates platform-specific tests
205
 * @param js - Value/test for JavaScript platforms
206
 * @param jvm - Value/test for JVM platforms  
207
 * @param f - Function to create test from platform value
208
 * @returns Test that runs only on supported platforms
209
 */
210
def platformSpecific[R, E, A](js: => A, jvm: => A)(f: A => ZTest[R, E]): ZTest[R, E]
211

212
/**
213
 * Creates version-specific tests
214
 * @param dotty - Value/test for Dotty/Scala 3
215
 * @param scala2 - Value/test for Scala 2
216
 * @param f - Function to create test from version value
217
 * @returns Test that runs only on supported versions
218
 */
219
def versionSpecific[R, E, A](dotty: => A, scala2: => A)(f: A => ZTest[R, E]): ZTest[R, E]
220
```
221

222
## Types
223

224
### Core Test Types
225

226
```scala { .api }
227
/**
228
 * A ZIO effect that represents a test requiring environment R and potentially failing with E
229
 */
230
type ZTest[-R, +E] = ZIO[R, TestFailure[E], TestSuccess]
231

232
/**
233
 * The canonical spec type for ZIO Test - a spec that contains tests
234
 */  
235
type ZSpec[-R, +E] = Spec[R, TestFailure[E], TestSuccess]
236

237
/**
238
 * Result of running assertions - success or failure with details
239
 */
240
type TestResult = BoolAlgebra[AssertionResult]
241

242
/**
243
 * Effectful assertion result type
244
 */
245
type AssertResultM = BoolAlgebraM[Any, Nothing, AssertionValue]
246

247
/**
248
 * Pure assertion result type
249
 */
250
type AssertResult = BoolAlgebra[AssertionValue]
251
```
252

253
### Service Types
254

255
```scala { .api }
256
/**
257
 * Test annotation service for adding metadata to tests
258
 */
259
type Annotations = Has[Annotations.Service]
260

261
/**
262
 * Service for configuring test data generation size
263
 */
264
type Sized = Has[Sized.Service]
265

266
/**
267
 * Service for test configuration (samples, retries, etc.)
268
 */
269
type TestConfig = Has[TestConfig.Service]
270

271
/**
272
 * Service for test logging
273
 */
274
type TestLogger = Has[TestLogger.Service]
275
```
276

277
### Test Reporting
278

279
```scala { .api }
280
/**
281
 * Function type for reporting test results
282
 * @param duration - Time taken to run tests
283
 * @param spec - Executed test specification with results
284
 * @returns Effect that logs/reports the results
285
 */
286
type TestReporter[-E] = (Duration, ExecutedSpec[E]) => URIO[TestLogger, Unit]
287

288
/**
289
 * Combined ZIO test environment with all test services
290
 */
291
type ZTestEnv = TestClock with TestConsole with TestRandom with TestSystem
292
```