0
# Test Suite Management
1

2
Utilities for collecting and running multiple test files, with support for pattern matching and integration with Java IDEs. Includes adapters for running Groovy scripts as JUnit tests.
3

4
## Capabilities
5

6
### GroovyTestSuite
7

8
TestSuite for running individual Groovy test scripts within Java IDEs or as standalone applications.
9

10
```groovy { .api }
11
/**
12
 * TestSuite for running Groovy unit tests in Java IDEs
13
 */
14
class GroovyTestSuite extends TestSuite {
15
    
16
    /** Create test suite instance */
17
    static Test suite();
18
    
19
    /** Load test from system property or command line argument */
20
    void loadTestSuite();
21
    
22
    /** Compile Groovy script file to class */
23
    Class compile(String fileName);
24
    
25
    /** Command-line entry point */
26
    static void main(String[] args);
27
}
28
```
29

30
**Usage Examples:**
31

32
```groovy
33
// Run from command line
34
java groovy.test.GroovyTestSuite src/test/MyTest.groovy
35

36
// Run with system property
37
java -Dtest=src/test/MyTest.groovy groovy.test.GroovyTestSuite
38

39
// Create programmatically
40
import groovy.test.GroovyTestSuite
41
import junit.textui.TestRunner
42

43
def suite = GroovyTestSuite.suite()
44
TestRunner.run(suite)
45
```
46

47
### AllTestSuite
48

49
Collects and runs multiple Groovy test files from directories using pattern matching.
50

51
```groovy { .api }
52
/**
53
 * Collects multiple test files from directories with pattern matching
54
 */
55
class AllTestSuite extends TestSuite {
56
    
57
    /** Create suite with default system properties */
58
    static Test suite();
59
    
60
    /** Create suite with custom directory and pattern */
61
    static Test suite(String basedir, String pattern);
62
    
63
    /** Create suite with includes and excludes patterns */
64
    static Test suite(String basedir, String pattern, String excludesPattern);
65
    
66
    /** Load individual test file */
67
    protected void loadTest(String filename);
68
    
69
    /** Compile test file to class */
70
    protected Class compile(String filename);
71
    
72
    /** System property for test directory */
73
    static final String SYSPROP_TEST_DIR = "groovy.test.dir";
74
    
75
    /** System property for test pattern */
76
    static final String SYSPROP_TEST_PATTERN = "groovy.test.pattern";
77
    
78
    /** System property for excludes pattern */
79
    static final String SYSPROP_TEST_EXCLUDES_PATTERN = "groovy.test.excludesPattern";
80
}
81
```
82

83
**Usage Examples:**
84

85
```groovy
86
import groovy.test.AllTestSuite
87
import junit.textui.TestRunner
88

89
// Use default settings (./test/ directory, **/*Test.groovy pattern)
90
def suite = AllTestSuite.suite()
91
TestRunner.run(suite)
92

93
// Custom directory and pattern
94
def customSuite = AllTestSuite.suite("src/test", "**/*Spec.groovy")
95
TestRunner.run(customSuite)
96

97
// With excludes pattern
98
def filteredSuite = AllTestSuite.suite(
99
    "test", 
100
    "**/*Test.groovy", 
101
    "**/Abstract*Test.groovy"
102
)
103
TestRunner.run(filteredSuite)
104

105
// Configure via system properties
106
System.setProperty("groovy.test.dir", "src/test/groovy")
107
System.setProperty("groovy.test.pattern", "**/*Specification.groovy")
108
System.setProperty("groovy.test.excludesPattern", "**/integration/**")
109

110
def propSuite = AllTestSuite.suite()
111
TestRunner.run(propSuite)
112
```
113

114
### ScriptTestAdapter
115

116
JUnit Test adapter for running Groovy Script classes as test cases.
117

118
```groovy { .api }
119
/**
120
 * JUnit Test adapter for Groovy Script classes
121
 */
122
class ScriptTestAdapter implements Test {
123
    
124
    /** Create adapter for script class with arguments */
125
    ScriptTestAdapter(Class scriptClass, String[] arguments);
126
    
127
    /** Return test count (always 1) */
128
    int countTestCases();
129
    
130
    /** Execute the script as a test */
131
    void run(TestResult result);
132
    
133
    /** Return descriptive test name */
134
    String toString();
135
}
136
```
137

138
**Usage Examples:**
139

140
```groovy
141
import org.apache.groovy.test.ScriptTestAdapter
142
import junit.framework.TestResult
143

144
// Create adapter for script class
145
def scriptClass = new GroovyClassLoader().parseClass("""
146
    println "Running test script"
147
    assert 2 + 2 == 4
148
    assert "hello".toUpperCase() == "HELLO"
149
    println "Test script completed successfully"
150
""")
151

152
def adapter = new ScriptTestAdapter(scriptClass, [] as String[])
153
def result = new TestResult()
154

155
adapter.run(result)
156

157
println "Test count: ${adapter.countTestCases()}"
158
println "Errors: ${result.errorCount()}"
159
println "Failures: ${result.failureCount()}"
160

161
// Use with TestSuite
162
import junit.framework.TestSuite
163

164
def suite = new TestSuite()
165
suite.addTest(adapter)
166
```
167

168
## Integration Examples
169

170
### IDE Integration
171

172
Configure your IDE to run Groovy tests using these test suites:
173

174
```groovy
175
// IntelliJ IDEA / Eclipse: Create JUnit run configuration
176
// Main class: groovy.test.AllTestSuite
177
// VM options: -Dgroovy.test.dir=src/test/groovy -Dgroovy.test.pattern=**/*Test.groovy
178

179
// Or use GroovyTestSuite for individual files
180
// Main class: groovy.test.GroovyTestSuite  
181
// Program arguments: src/test/groovy/MySpecificTest.groovy
182
```
183

184
### Gradle Integration
185

186
```groovy
187
// build.gradle
188
test {
189
    // Run Groovy tests alongside Java tests
190
    include '**/*Test.groovy'
191
    include '**/*Spec.groovy'
192
    
193
    systemProperty 'groovy.test.dir', 'src/test/groovy'
194
    systemProperty 'groovy.test.pattern', '**/*Test.groovy' 
195
}
196

197
// Custom test task for AllTestSuite
198
task groovyTests(type: JavaExec) {
199
    classpath = sourceSets.test.runtimeClasspath
200
    main = 'groovy.test.AllTestSuite'
201
    systemProperty 'groovy.test.dir', 'src/test/groovy'
202
    systemProperty 'groovy.test.pattern', '**/*Test.groovy'
203
}
204
```
205

206
### Maven Integration
207

208
```xml
209
<!-- pom.xml -->
210
<plugin>
211
    <groupId>org.apache.maven.plugins</groupId>
212
    <artifactId>maven-surefire-plugin</artifactId>
213
    <configuration>
214
        <includes>
215
            <include>**/*Test.groovy</include>
216
            <include>**/*Test.java</include>
217
        </includes>
218
        <systemProperties>
219
            <property>
220
                <name>groovy.test.dir</name>
221
                <value>src/test/groovy</value>
222
            </property>
223
            <property>
224
                <name>groovy.test.pattern</name>
225
                <value>**/*Test.groovy</value>
226
            </property>
227
        </systemProperties>
228
    </configuration>
229
</plugin>
230
```
231

232
## Test File Requirements
233

234
Test files collected by AllTestSuite must meet one of these criteria:
235

236
1. **TestCase classes**: Extend `junit.framework.TestCase` or `groovy.test.GroovyTestCase`
237
2. **Script files**: Groovy scripts that can be wrapped in `ScriptTestAdapter`
238

239
```groovy
240
// Valid TestCase class
241
class MyFeatureTest extends GroovyTestCase {
242
    void testSomething() {
243
        assertEquals(expected, actual)
244
    }
245
}
246

247
// Valid test script
248
def calculator = new Calculator()
249
assert calculator.add(2, 3) == 5
250
assert calculator.multiply(4, 5) == 20
251
println "Calculator tests passed"
252
```
253

254
## System Properties
255

256
Configure test collection behavior using system properties:
257

258
| Property | Default | Description |
259
|----------|---------|-------------|
260
| `groovy.test.dir` | `"./test/"` | Base directory for test collection |
261
| `groovy.test.pattern` | `"**/*Test.groovy"` | Include pattern for test files |
262
| `groovy.test.excludesPattern` | `""` | Exclude pattern for test files |
263
264
**Pattern Examples:**
265

266
```groovy
267
// Include all Groovy files ending with Test or Spec
268
"**/*{Test,Spec}.groovy"
269

270
// Include only unit tests, exclude integration tests  
271
"**/*Test.groovy" // include
272
"**/integration/**" // exclude
273

274
// Include nested directories
275
"**/test/**/*Test.groovy"
276

277
// Exclude abstract base classes
278
"**/*Test.groovy" // include  
279
"**/Abstract*Test.groovy" // exclude
280
```
281

282
## Error Handling
283

284
Test suite errors are reported through the JUnit TestResult mechanism:
285

286
- **Compilation errors**: Wrapped in `RuntimeException` with detailed error messages
287
- **File not found**: `IOException` when test files cannot be read
288
- **Invalid test format**: `RuntimeException` when files don't extend TestCase or Script
289

290
```groovy
291
// Error handling example
292
def suite = AllTestSuite.suite("invalid/path", "*.groovy")
293
def result = new TestResult()
294

295
suite.run(result)
296

297
if (result.errorCount() > 0) {
298
    result.errors().each { error ->
299
        println "Error in ${error.failedTest()}: ${error.thrownException().message}"
300
    }
301
}
302
```