CDAP Common Unit Test

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.

Package Information

• Package Name: cdap-common-unit-test
• Group ID: co.cask.cdap
• Language: Java
• Installation: Add Maven dependency with coordinates co.cask.cdap:cdap-common-unit-test:5.1.2

Maven Dependency

<dependency>
    <groupId>co.cask.cdap</groupId>
    <artifactId>cdap-common-unit-test</artifactId>
    <version>5.1.2</version>
    <scope>test</scope>
</dependency>

Core Imports

import co.cask.cdap.test.SlowTests;
import co.cask.cdap.test.XSlowTests;
import co.cask.cdap.test.SingletonExternalResource;

Basic Usage

Test Categorization

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

import org.junit.Test;
import org.junit.experimental.categories.Category;
import co.cask.cdap.test.SlowTests;
import co.cask.cdap.test.XSlowTests;

public class MyTest {
    
    @Test
    @Category(SlowTests.class)
    public void moderatelySlowTest() {
        // Test that takes 2-30 seconds
    }
    
    @Test
    @Category(XSlowTests.class) 
    public void verySlowTest() {
        // Test that takes more than 30 seconds
    }
}

Resource Singleton Management

Use SingletonExternalResource to share resources efficiently across test suites:

import org.junit.Rule;
import org.junit.Test;
import org.junit.rules.ExternalResource;
import co.cask.cdap.test.SingletonExternalResource;

public class MyTestSuite {
    
    private static ExternalResource expensiveResource = new ExternalResource() {
        @Override
        protected void before() throws Throwable {
            // Setup expensive resource once
        }
        
        @Override
        protected void after() {
            // Cleanup expensive resource once
        }
    };
    
    @Rule
    public SingletonExternalResource resource = new SingletonExternalResource(expensiveResource);
    
    @Test
    public void testUsingSharedResource() {
        // Access the underlying resource
        ExternalResource underlying = resource.get();
        // Use the resource in your test
    }
}

Capabilities

Test Speed Categorization

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

public interface SlowTests {
    // Marker interface for tests running 2-30 seconds
}

public interface XSlowTests extends SlowTests {
    // Marker interface for tests running more than 30 seconds
}

Usage Pattern:

• Apply @Category(SlowTests.class) to tests that take more than a couple seconds but less than 30 seconds
• Apply @Category(XSlowTests.class) to tests that take more than 30 seconds
• Use with JUnit's @IncludeCategory and @ExcludeCategory annotations to control test execution

Singleton Resource Management

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

public class SingletonExternalResource extends ExternalResource {
    
    public SingletonExternalResource(ExternalResource externalResource);
    
    protected void before() throws Throwable;
    
    protected void after();
    
    public <T extends ExternalResource> T get();
}

Constructor:

• SingletonExternalResource(ExternalResource externalResource) - Creates a singleton wrapper around the provided ExternalResource

Methods:

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

Key Features:

• Thread-safe reference counting using AtomicInteger
• Automatic setup/teardown lifecycle management
• Supports shared usage across both individual tests and test suites
• Prevents resource leaks through proper reference counting

Error Handling

SingletonExternalResource

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.

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

Dependencies

This library requires:

• JUnit: Uses org.junit.rules.ExternalResource as the base class for SingletonExternalResource
• Java Standard Library: Uses reflection (java.lang.reflect.*), atomic operations (java.util.concurrent.atomic.AtomicInteger), and utility classes (java.util.Objects)

Maven Configuration

Add to your project's test dependencies:

<dependencies>
    <dependency>
        <groupId>co.cask.cdap</groupId>
        <artifactId>cdap-common-unit-test</artifactId>
        <version>5.1.2</version>
        <scope>test</scope>
    </dependency>
</dependencies>