0
# Test Cases and Assertions
1

2
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.
3

4
## Capabilities
5

6
### GroovyTestCase (JUnit 3)
7

8
JUnit 3 base class with enhanced Groovy-aware assertion methods and script testing capabilities.
9

10
```groovy { .api }
11
/**
12
 * JUnit 3 base class with Groovy-aware testing capabilities
13
 */
14
class GroovyTestCase extends TestCase {
15
    
16
    /** Test a Groovy script execution without exceptions */
17
    protected void assertScript(String script) throws Exception;
18
    
19
    /** Assert that arrays contain equivalent values */
20
    protected void assertArrayEquals(Object[] expected, Object[] value);
21
    
22
    /** Assert array length for different array types */
23
    protected void assertLength(int length, char[] array);
24
    protected void assertLength(int length, int[] array);
25
    protected void assertLength(int length, Object[] array);
26
    
27
    /** Assert that arrays contain specific elements */
28
    protected void assertContains(char expected, char[] array);
29
    protected void assertContains(int expected, int[] array);
30
    
31
    /** Assert toString() and inspect() output */
32
    protected void assertToString(Object value, String expected);
33
    protected void assertInspect(Object value, String expected);
34
    
35
    /** Expect closure to fail and return exception message */
36
    protected String shouldFail(Closure code);
37
    protected String shouldFail(Class clazz, Closure code);
38
    protected String shouldFailWithCause(Class clazz, Closure code);
39
    
40
    /** Expect script to fail and return exception message */
41
    protected String shouldFail(String script);
42
    protected String shouldFail(Class clazz, String script);
43
    
44
    /** Mark test as not-yet-implemented (static version) */
45
    public static boolean notYetImplemented(Object caller);
46
    
47
    /** Mark test as not-yet-implemented (instance version) */
48
    public boolean notYetImplemented();
49
    
50
    /** Groovy-aware equality assertion (overrides TestCase) */
51
    public static void assertEquals(String message, Object expected, Object actual);
52
    public static void assertEquals(Object expected, Object actual);
53
    public static void assertEquals(String expected, String actual);
54
    
55
    /** Normalize line endings utility */
56
    protected String fixEOLs(String value);
57
    
58
    /** Test method name utilities - getName() can be overridden for AgileDox style */
59
    public String getName();
60
    public String getMethodName();
61
    
62
    /** Get test class name for script generation */
63
    protected String getTestClassName();
64
}
65
```
66

67
**Usage Examples:**
68

69
```groovy
70
import groovy.test.GroovyTestCase
71

72
class MyTest extends GroovyTestCase {
73
    
74
    void testBasicAssertions() {
75
        // Groovy-aware equality
76
        assertEquals([1, 2, 3], [1, 2, 3])
77
        assertEquals(new BigDecimal("1.0"), 1.0)
78
        
79
        // Array assertions
80
        assertArrayEquals(["a", "b"] as String[], ["a", "b"] as String[])
81
        assertLength(3, [1, 2, 3] as int[])
82
        assertContains(2, [1, 2, 3] as int[])
83
    }
84
    
85
    void testScriptExecution() {
86
        // Test that script runs without exception
87
        assertScript '''
88
            def x = 10
89
            def y = 20
90
            assert x + y == 30
91
        '''
92
    }
93
    
94
    void testFailureExpectation() {
95
        // Expect any exception
96
        shouldFail {
97
            throw new RuntimeException("Expected failure")
98
        }
99
        
100
        // Expect specific exception type
101
        shouldFail(IllegalArgumentException) {
102
            throw new IllegalArgumentException("Bad argument")
103
        }
104
        
105
        // Expect exception with specific nested cause
106
        shouldFailWithCause(NumberFormatException) {
107
            try {
108
                Integer.parseInt("not-a-number")
109
            } catch (NumberFormatException e) {
110
                throw new RuntimeException("Wrapper", e)
111
            }
112
        }
113
    }
114
    
115
    void testNotYetImplemented() {
116
        if (notYetImplemented()) return
117
        
118
        // This test will pass when the feature is implemented
119
        // but currently fails - that's expected behavior
120
        def result = myNewFeature()
121
        assertEquals("expected", result)
122
    }
123
}
124
```
125

126
### GroovyAssert (JUnit 4+)
127

128
Static assertion methods compatible with JUnit 4+ for use in modern testing frameworks.
129

130
```groovy { .api }
131
/**
132
 * JUnit 4+ compatible static assertion methods for Groovy
133
 */
134
class GroovyAssert extends Assert {
135
    
136
    /** Test script execution without exceptions */
137
    public static void assertScript(String script) throws Exception;
138
    
139
    /** Expect closure to fail and return the exception */
140
    public static Throwable shouldFail(Closure code);
141
    public static Throwable shouldFail(Class clazz, Closure code);
142
    
143
    /** Expect closure to fail with specific nested cause */
144
    public static Throwable shouldFailWithCause(Class expectedCause, Closure code);
145
    
146
    /** Expect script to fail and return the exception */
147
    public static Throwable shouldFail(String script);
148
    public static Throwable shouldFail(Class clazz, String script);
149
    
150
    /** Support for not-yet-implemented tests */
151
    public static boolean notYetImplemented(Object caller);
152
    
153
    /** JDK version checking utility */
154
    public static boolean isAtLeastJdk(String specVersion);
155
}
156
```
157

158
**Usage Examples:**
159

160
```groovy
161
import static groovy.test.GroovyAssert.*
162
import org.junit.Test
163

164
class MyJUnit4Test {
165
    
166
    @Test
167
    void testWithStaticAssertions() {
168
        // Test script execution
169
        assertScript '''
170
            def list = [1, 2, 3]
171
            assert list.size() == 3
172
            assert list.sum() == 6
173
        '''
174
        
175
        // Expect failures
176
        def exception = shouldFail(IllegalArgumentException) {
177
            throw new IllegalArgumentException("Test exception")
178
        }
179
        assertEquals("Test exception", exception.message)
180
    }
181
    
182
    @Test
183
    void testNotYetImplemented() {
184
        if (notYetImplemented(this)) return
185
        
186
        // Implementation pending
187
        fail("Feature not yet implemented")
188
    }
189
    
190
    @Test  
191
    void testJdkVersion() {
192
        if (isAtLeastJdk("11")) {
193
            // Use JDK 11+ features
194
            def text = """
195
                Multi-line
196
                text block
197
                """
198
            assertNotNull(text)
199
        }
200
    }
201
}
202
```
203

204
### GroovyShellTestCase
205

206
Test case class with integrated GroovyShell management for script evaluation and binding manipulation.
207

208
```groovy { .api }
209
/**
210
 * Test case with integrated GroovyShell management
211
 */
212
class GroovyShellTestCase extends GroovyTestCase {
213
    
214
    /** Create new shell instance (override to customize) */
215
    protected GroovyShell createNewShell();
216
    
217
    /** Execute closure with temporary variable binding */
218
    protected Object withBinding(Map map, Closure closure);
219
    
220
    /** Execute script with temporary variable binding */
221
    protected Object withBinding(Map map, String script);
222
    
223
    // All GroovyShell methods available via @Delegate
224
    // evaluate(), parse(), run() etc.
225
}
226
```
227

228
**Usage Examples:**
229

230
```groovy
231
import groovy.test.GroovyShellTestCase
232

233
class ShellTest extends GroovyShellTestCase {
234
    
235
    void testScriptEvaluation() {
236
        def result = evaluate("10 + 20")
237
        assertEquals(30, result)
238
        
239
        def script = """
240
            def multiply(a, b) { a * b }
241
            multiply(6, 7)
242
        """
243
        assertEquals(42, evaluate(script))
244
    }
245
    
246
    void testWithBinding() {
247
        def result = withBinding([x: 100, y: 200]) {
248
            evaluate("x + y")
249
        }
250
        assertEquals(300, result)
251
        
252
        def scriptResult = withBinding([name: "World"]) { 
253
            "Hello, \${name}!"
254
        }
255
        assertEquals("Hello, World!", scriptResult)
256
    }
257
    
258
    protected GroovyShell createNewShell() {
259
        // Customize shell creation
260
        def config = new CompilerConfiguration()
261
        config.scriptBaseClass = MyCustomBaseScript.name
262
        return new GroovyShell(config)
263
    }
264
}
265
```
266

267
### StringTestUtil
268

269
Utility class for string-specific testing operations, particularly multiline string comparisons.
270

271
```groovy { .api }
272
/**
273
 * String testing utilities
274
 */
275
class StringTestUtil {
276
    
277
    /** Compare multiline strings with line-by-line equality checking */
278
    static void assertMultilineStringsEqual(String a, String b);
279
}
280
```
281

282
**Usage Examples:**
283

284
```groovy
285
import static groovy.test.StringTestUtil.assertMultilineStringsEqual
286

287
class TextProcessorTest extends GroovyTestCase {
288
    
289
    void testMultilineOutput() {
290
        def processor = new TextProcessor()
291
        def result = processor.format("""
292
            line one
293
            line two  
294
            line three
295
        """)
296
        
297
        def expected = """
298
            Line One
299
            Line Two
300
            Line Three
301
        """
302
        
303
        // Compare multiline strings with automatic trimming and normalization
304
        assertMultilineStringsEqual(expected, result)
305
    }
306
}
307
```
308

309
## Error Handling
310

311
The assertion methods throw standard JUnit exceptions:
312

313
- `AssertionFailedError` for failed assertions
314
- `ComparisonFailure` for failed equality assertions with detailed diff information
315

316
The `shouldFail` methods catch and return exceptions, allowing for detailed exception testing:
317

318
```groovy
319
def exception = shouldFail(SQLException) {
320
    database.executeInvalidQuery()
321
}
322
assertEquals("Invalid SQL syntax", exception.message)
323
assertEquals("42000", exception.sqlState)
324
```