0
# Groovy Test
1

2
The Groovy testing library provides comprehensive testing utilities for Groovy applications, extending JUnit functionality with Groovy-specific features. It includes JUnit 3 base classes, JUnit 4+ compatible assertion methods, a complete mock/stub framework, AST transformations for test-driven development, and utilities for script testing and test suite management.
3

4
## Package Information
5

6
- **Package Name**: groovy-test
7
- **Package Type**: maven
8
- **Language**: Groovy/Java
9
- **Installation**: `implementation 'org.codehaus.groovy:groovy-test:3.0.25'`
10

11
## Core Imports
12

13
```groovy
14
// JUnit 3 style testing
15
import groovy.test.GroovyTestCase
16
import groovy.test.GroovyShellTestCase
17

18
// JUnit 4+ assertions
19
import static groovy.test.GroovyAssert.*
20

21
// Mock/Stub framework
22
import groovy.mock.interceptor.MockFor
23
import groovy.mock.interceptor.StubFor
24

25
// Test annotations
26
import groovy.test.NotYetImplemented
27

28
// Test suites
29
import groovy.test.GroovyTestSuite
30
import groovy.test.AllTestSuite
31

32
// Utilities
33
import groovy.test.StringTestUtil
34
```
35

36
For Java projects:
37

38
```java
39
// JUnit 4+ assertions
40
import static groovy.test.GroovyAssert.*;
41

42
// Test annotations
43
import groovy.test.NotYetImplemented;
44

45
// Test suites
46
import groovy.test.GroovyTestSuite;
47
import groovy.test.AllTestSuite;
48
```
49

50
## Basic Usage
51

52
```groovy
53
import groovy.test.GroovyTestCase
54
import groovy.mock.interceptor.MockFor
55

56
// JUnit 3 style test case
57
class MyServiceTest extends GroovyTestCase {
58
    
59
    void testSomething() {
60
        def result = myService.calculate(10, 20)
61
        assertEquals(30, result)
62
        assertScript "assert 10 + 20 == 30"
63
        
64
        // Test failure expectations
65
        shouldFail(IllegalArgumentException) {
66
            myService.calculate(-1, 0)
67
        }
68
    }
69
    
70
    void testWithMock() {
71
        def mock = new MockFor(Database)
72
        mock.demand.findUser { id -> [name: "Test User", id: id] }
73
        
74
        mock.use {
75
            def database = new Database()
76
            def service = new UserService(database)
77
            def user = service.getUser(123)
78
            assertEquals("Test User", user.name)
79
        }
80
    }
81
}
82
```
83

84
## Architecture
85

86
Groovy Test is organized around several key components:
87

88
- **Test Case Classes**: `GroovyTestCase` provides JUnit 3 compatibility with Groovy-aware assertions
89
- **Static Assertions**: `GroovyAssert` provides JUnit 4+ compatible static assertion methods
90
- **Mock/Stub Framework**: Interceptor-based mocking with `MockFor` (strict) and `StubFor` (loose) expectations
91
- **Test Suite Management**: Classes for collecting and running multiple test files from directories
92
- **AST Transformations**: `@NotYetImplemented` annotation for test-driven development workflows
93
- **Script Testing**: Adapters for running Groovy scripts as JUnit tests
94

95
## Capabilities
96

97
### Test Cases and Assertions
98

99
JUnit 3 and JUnit 4+ compatible test cases with Groovy-aware assertion methods. Enhanced equality checking using Groovy's type conversion and additional assertion utilities for arrays, collections, and script execution.
100

101
```groovy { .api }
102
class GroovyTestCase extends TestCase {
103
    protected void assertArrayEquals(Object[] expected, Object[] value);
104
    protected void assertScript(String script) throws Exception;
105
    protected String shouldFail(Closure code);
106
    protected String shouldFail(Class clazz, Closure code);
107
    public static boolean notYetImplemented(Object caller);
108
}
109

110
class GroovyAssert extends Assert {
111
    public static void assertScript(String script) throws Exception;
112
    public static Throwable shouldFail(Closure code);
113
    public static Throwable shouldFail(Class clazz, Closure code);
114
    public static Throwable shouldFailWithCause(Class expectedCause, Closure code);
115
    public static boolean notYetImplemented(Object caller);
116
}
117
```
118

119
[Test Cases and Assertions](./test-cases.md)
120

121
### Mock and Stub Framework
122

123
Comprehensive mocking framework supporting both strict (ordered) and loose (unordered) expectations. Uses metaclass interception to mock final classes and methods, with support for constructor interception and partial mocking.
124

125
```groovy { .api }
126
class MockFor {
127
    MockFor(Class clazz, boolean interceptConstruction = false);
128
    void use(Closure closure);
129
    def ignore(Object filter, Closure filterBehavior = null);
130
    GroovyObject proxyInstance(args = null);
131
}
132

133
class StubFor {
134
    StubFor(Class clazz, boolean interceptConstruction = false);
135
    void use(Closure closure);
136
    void verify();
137
    GroovyObject proxyInstance(args = null);
138
}
139
```
140

141
[Mock and Stub Framework](./mock-stub.md)
142

143
### Test Suite Management
144

145
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.
146

147
```groovy { .api }
148
class GroovyTestSuite extends TestSuite {
149
    static Test suite();
150
    void loadTestSuite();
151
}
152

153
class AllTestSuite extends TestSuite {
154
    static Test suite();
155
    static Test suite(String basedir, String pattern);
156
    static Test suite(String basedir, String pattern, String excludesPattern);
157
}
158
```
159

160
[Test Suite Management](./test-suites.md)
161

162
### AST Transformations
163

164
Annotation-based test enhancements including the `@NotYetImplemented` transformation for test-driven development. Automatically inverts test results to support "failing tests first" development patterns.
165

166
```groovy { .api }
167
@interface NotYetImplemented {
168
    Class<? extends AssertionError> exception() default AssertionError.class;
169
}
170
```
171

172
[AST Transformations](./ast-transformations.md)
173

174
## Types
175

176
```groovy { .api }
177
interface Test {
178
    int countTestCases();
179
    void run(TestResult result);
180
}
181

182
class TestSuite implements Test {
183
    void addTest(Test test);
184
    void addTestSuite(Class<? extends TestCase> testClass);
185
}
186

187
class Demand {
188
    // Dynamic method recording via invokeMethod
189
    Object invokeMethod(String methodName, Object args);
190
    void verify(List calls);
191
}
192

193
class GroovyShell {
194
    Object evaluate(String script);
195
    Script parse(String script);
196
    Script parse(String script, String fileName);
197
    void setProperty(String property, Object newValue);
198
}
199

200
class Binding {
201
    Map variables;
202
    void setVariable(String name, Object value);
203
    Object getVariable(String name);
204
}
205
```