0
# Test Discovery
1
2
Test specification discovery mechanism that allows SBT to identify ZIO test classes and convert them into executable test tasks. This system enables automatic detection of ZIO test specifications in the classpath.
3
4
## Capabilities
5
6
### ZioSpecFingerprint
7
8
The fingerprint implementation that enables SBT to discover ZIO test specifications by identifying classes that extend `ZIOSpecAbstract`.
9
10
```scala { .api }
11
/**
12
* SBT fingerprint for discovering ZIO test specifications
13
* Identifies classes extending ZIOSpecAbstract as test targets
14
*/
15
object ZioSpecFingerprint extends SubclassFingerprint {
16
/**
17
* Returns the superclass name that SBT should look for
18
* @return Fully qualified name of ZIOSpecAbstract class
19
*/
20
def superclassName(): String
21
22
/**
23
* Indicates that test specifications are module objects (Scala objects)
24
* @return Always true, as ZIO tests are typically defined as objects
25
*/
26
def isModule(): Boolean
27
28
/**
29
* Indicates whether a no-argument constructor is required
30
* @return Always false, as Scala objects don't require explicit constructors
31
*/
32
def requireNoArgConstructor(): Boolean
33
}
34
```
35
36
**Implementation Details:**
37
38
```scala { .api }
39
// Returns the ZIOSpecAbstract class name for discovery
40
def superclassName(): String = classOf[ZIOSpecAbstract].getName
41
42
// ZIO test specifications are typically Scala objects
43
final def isModule(): Boolean = true
44
45
// Scala objects don't require no-arg constructors
46
final def requireNoArgConstructor(): Boolean = false
47
```
48
49
### Discovery Process
50
51
The test discovery process follows this flow:
52
53
1. **Classpath Scanning**: SBT scans the test classpath for classes matching the fingerprint criteria
54
2. **Subclass Detection**: Identifies all classes/objects extending `ZIOSpecAbstract`
55
3. **Module Loading**: Loads Scala objects (modules) that contain test specifications
56
4. **Task Creation**: Converts discovered specifications into executable `TaskDef` instances
57
5. **Runner Delegation**: Passes `TaskDef` instances to platform-specific test runners
58
59
### Supported Test Patterns
60
61
The fingerprint discovers various ZIO test specification patterns:
62
63
**Basic ZIO Spec Object:**
64
```scala
65
object MyTestSpec extends ZIOSpecDefault {
66
def spec = suite("MyTests")(
67
test("example test") {
68
assert(1 + 1)(equalTo(2))
69
}
70
)
71
}
72
```
73
74
**Custom ZIO Spec:**
75
```scala
76
object CustomSpec extends ZIOSpec[TestEnvironment] {
77
def spec = suite("CustomTests")(
78
test("custom test") {
79
// test implementation
80
assertTrue(true)
81
}
82
)
83
}
84
```
85
86
**ZIO Spec with Environment:**
87
```scala
88
object DatabaseSpec extends ZIOSpecDefault {
89
override def spec = suite("DatabaseTests")(
90
test("database connection") {
91
// test with custom environment
92
assertTrue(true)
93
}
94
).provide(/* custom layers */)
95
}
96
```
97
98
### Integration with SBT
99
100
The fingerprint integrates seamlessly with SBT's test discovery mechanism:
101
102
```scala
103
// SBT uses the fingerprint to:
104
// 1. Scan classpath for matching classes
105
// 2. Create TaskDef instances for each discovered test
106
// 3. Pass TaskDefs to the framework's runner
107
// 4. Execute tests and collect results
108
109
val discoveredSpecs: Array[TaskDef] = sbtDiscoveryEngine.discover(ZioSpecFingerprint)
110
val runner = framework.runner(args, remoteArgs, classLoader)
111
val tasks = runner.tasks(discoveredSpecs)
112
```
113
114
### Platform Considerations
115
116
The fingerprint works consistently across all supported platforms:
117
118
- **JVM**: Full reflection-based class discovery and loading
119
- **JavaScript**: Uses portable reflection for module loading
120
- **Native**: Optimized reflection for native compilation constraints
121
122
### Error Handling
123
124
The discovery process handles various error conditions:
125
126
- **Missing Classes**: Gracefully handles cases where discovered classes cannot be loaded
127
- **Invalid Specifications**: Filters out classes that don't properly extend `ZIOSpecAbstract`
128
- **ClassLoader Issues**: Manages class loading failures with appropriate error reporting
129
130
The robust discovery mechanism ensures that ZIO test specifications are reliably found and executed across different build configurations and runtime environments.