0
# CDAP Common Unit Test
1

2
Common unit testing utilities and interfaces for the Cask Data Application Platform (CDAP) testing framework. This library provides test categorization interfaces and resource management utilities to standardize testing patterns across the CDAP ecosystem.
3

4
## Package Information
5

6
- **Package Name**: cdap-common-unit-test
7
- **Group ID**: co.cask.cdap
8
- **Language**: Java
9
- **Installation**: Add Maven dependency with coordinates `co.cask.cdap:cdap-common-unit-test:5.1.2`
10

11
## Maven Dependency
12

13
```xml
14
<dependency>
15
    <groupId>co.cask.cdap</groupId>
16
    <artifactId>cdap-common-unit-test</artifactId>
17
    <version>5.1.2</version>
18
    <scope>test</scope>
19
</dependency>
20
```
21

22
## Core Imports
23

24
```java
25
import co.cask.cdap.test.SlowTests;
26
import co.cask.cdap.test.XSlowTests;
27
import co.cask.cdap.test.SingletonExternalResource;
28
```
29

30
## Basic Usage
31

32
### Test Categorization
33

34
Use the marker interfaces to categorize tests by execution time for selective test execution:
35

36
```java
37
import org.junit.Test;
38
import org.junit.experimental.categories.Category;
39
import co.cask.cdap.test.SlowTests;
40
import co.cask.cdap.test.XSlowTests;
41

42
public class MyTest {
43
    
44
    @Test
45
    @Category(SlowTests.class)
46
    public void moderatelySlowTest() {
47
        // Test that takes 2-30 seconds
48
    }
49
    
50
    @Test
51
    @Category(XSlowTests.class) 
52
    public void verySlowTest() {
53
        // Test that takes more than 30 seconds
54
    }
55
}
56
```
57

58
### Resource Singleton Management
59

60
Use SingletonExternalResource to share resources efficiently across test suites:
61

62
```java
63
import org.junit.Rule;
64
import org.junit.Test;
65
import org.junit.rules.ExternalResource;
66
import co.cask.cdap.test.SingletonExternalResource;
67

68
public class MyTestSuite {
69
    
70
    private static ExternalResource expensiveResource = new ExternalResource() {
71
        @Override
72
        protected void before() throws Throwable {
73
            // Setup expensive resource once
74
        }
75
        
76
        @Override
77
        protected void after() {
78
            // Cleanup expensive resource once
79
        }
80
    };
81
    
82
    @Rule
83
    public SingletonExternalResource resource = new SingletonExternalResource(expensiveResource);
84
    
85
    @Test
86
    public void testUsingSharedResource() {
87
        // Access the underlying resource
88
        ExternalResource underlying = resource.get();
89
        // Use the resource in your test
90
    }
91
}
92
```
93

94
## Capabilities
95

96
### Test Speed Categorization
97

98
Marker interfaces for organizing tests by execution time to enable selective test execution based on time constraints.
99

100
```java { .api }
101
public interface SlowTests {
102
    // Marker interface for tests running 2-30 seconds
103
}
104
```
105

106
```java { .api }
107
public interface XSlowTests extends SlowTests {
108
    // Marker interface for tests running more than 30 seconds
109
}
110
```
111

112
**Usage Pattern:**
113
- Apply `@Category(SlowTests.class)` to tests that take more than a couple seconds but less than 30 seconds
114
- Apply `@Category(XSlowTests.class)` to tests that take more than 30 seconds
115
- Use with JUnit's `@IncludeCategory` and `@ExcludeCategory` annotations to control test execution
116

117
### Singleton Resource Management
118

119
Wrapper for JUnit ExternalResource that maintains singleton instances with reference counting for efficient resource sharing across test suites.
120

121
```java { .api }
122
public class SingletonExternalResource extends ExternalResource {
123
    
124
    public SingletonExternalResource(ExternalResource externalResource);
125
    
126
    protected void before() throws Throwable;
127
    
128
    protected void after();
129
    
130
    public <T extends ExternalResource> T get();
131
}
132
```
133

134
**Constructor:**
135
- `SingletonExternalResource(ExternalResource externalResource)` - Creates a singleton wrapper around the provided ExternalResource
136

137
**Methods:**
138
- `before()` - Overridden from ExternalResource. Handles singleton setup with reference counting. Only sets up the underlying resource on the first call.
139
- `after()` - Overridden from ExternalResource. Handles singleton teardown with reference counting. Only tears down the underlying resource when the last reference is released.
140
- `get()` - Returns the underlying ExternalResource instance, cast to the specified type T
141

142
**Key Features:**
143
- Thread-safe reference counting using AtomicInteger
144
- Automatic setup/teardown lifecycle management
145
- Supports shared usage across both individual tests and test suites
146
- Prevents resource leaks through proper reference counting
147

148
## Error Handling
149

150
### SingletonExternalResource
151

152
The `before()` method can throw any `Throwable` that the underlying ExternalResource's `before()` method throws. The `after()` method catches reflection-related exceptions internally and wraps them in RuntimeException, though these should not occur under normal circumstances.
153

154
The `get()` method throws `NullPointerException` if called with a null underlying resource (enforced by `Objects.requireNonNull`).
155

156
## Dependencies
157

158
This library requires:
159
- **JUnit**: Uses `org.junit.rules.ExternalResource` as the base class for SingletonExternalResource
160
- **Java Standard Library**: Uses reflection (`java.lang.reflect.*`), atomic operations (`java.util.concurrent.atomic.AtomicInteger`), and utility classes (`java.util.Objects`)
161

162
## Maven Configuration
163

164
Add to your project's test dependencies:
165

166
```xml
167
<dependencies>
168
    <dependency>
169
        <groupId>co.cask.cdap</groupId>
170
        <artifactId>cdap-common-unit-test</artifactId>
171
        <version>5.1.2</version>
172
        <scope>test</scope>
173
    </dependency>
174
</dependencies>
175
```