tessl/maven-com-tngtech-java--junit-dataprovider
A TestNG-like dataprovider runner for JUnit having a simplified syntax compared to all the existing JUnit features.
—
data-formats.mddocs/
Data Provider Formats and Types
This document covers the various formats and data types supported by JUnit DataProvider, including return types for data provider methods and parameter type conversion.
Supported Return Types
Data provider methods can return data in several formats, all of which are automatically converted to the appropriate test parameters.
Object[][] (Standard Array Format)
The most common and straightforward format:
@DataProvider
public static Object[][] stringTests() {
return new Object[][] {
{ "hello", 5, true },
{ "world", 5, true },
{ "", 0, false },
{ "testing", 7, true }
};
}Iterable<Iterable<?>> (Nested Iterables)
Flexible format using any Iterable implementations:
@DataProvider
public static List<List<Object>> iterableTests() {
return Arrays.asList(
Arrays.asList("hello", 5, true),
Arrays.asList("world", 5, true),
Arrays.asList("", 0, false)
);
}
@DataProvider
public static Iterable<Iterable<String>> stringIterables() {
Set<List<String>> data = new HashSet<>();
data.add(Arrays.asList("param1", "param2"));
data.add(Arrays.asList("param3", "param4"));
return data;
}Iterable<?> (Single Iterable)
Each element in the iterable becomes a single parameter test case:
@DataProvider
public static List<String> singleParameterTests() {
return Arrays.asList("test1", "test2", "test3");
}
@Test
@UseDataProvider("singleParameterTests")
public void testSingleParameter(String input) {
assertNotNull(input);
}String[] (String-Based Data)
String arrays with configurable parsing:
@DataProvider
public static String[] stringArrayData() {
return new String[] {
"param1,param2,123",
"param3,param4,456",
"param5,param6,789"
};
}
@DataProvider(splitBy = "\\|", convertNulls = false)
public static String[] customDelimiterData() {
return new String[] {
"param1|param2|null",
"param3|param4|notNull"
};
}String Data Provider Configuration
When using String-based data providers (either through String[] return type or inline @DataProvider values), several configuration options control parsing behavior.
Delimiter Configuration
@DataProvider(splitBy = "\\|") // Use pipe delimiter
@DataProvider(splitBy = ";") // Use semicolon
@DataProvider(splitBy = "\\s+") // Split on whitespaceDefault delimiter is comma (,).
Null Value Handling
@DataProvider(convertNulls = true) // "null" string becomes null value (default)
@DataProvider(convertNulls = false) // "null" remains as string literal@Test
@DataProvider(value = {"test,null,123"}, convertNulls = true)
public void testWithNull(String str, String nullValue, int num) {
assertEquals("test", str);
assertNull(nullValue); // Converted to null
assertEquals(123, num);
}Whitespace Trimming
@DataProvider(trimValues = true) // Trim whitespace (default)
@DataProvider(trimValues = false) // Preserve whitespace@Test
@DataProvider(value = {" test , value "}, trimValues = true)
public void testTrimmed(String param1, String param2) {
assertEquals("test", param1); // Whitespace trimmed
assertEquals("value", param2); // Whitespace trimmed
}Parameter Type Conversion
JUnit DataProvider automatically converts string parameters to appropriate types for test method parameters.
Primitive Types
All primitive types are supported via their wrapper class valueOf() methods:
// Supported primitive types
boolean, byte, char, double, float, int, long, short
// Example conversions
"true" → boolean true
"123" → int 123
"45.67" → double 45.67
"X" → char 'X'@Test
@DataProvider({"true,123,45.67,X"})
public void testPrimitives(boolean b, int i, double d, char c) {
assertTrue(b);
assertEquals(123, i);
assertEquals(45.67, d, 0.001);
assertEquals('X', c);
}Primitive Wrapper Types
Boolean, Byte, Character, Double, Float, Integer, Long, Short@Test
@DataProvider({"true,null,123"})
public void testWrappers(Boolean b, Integer nullInt, Long l) {
assertTrue(b);
assertNull(nullInt); // null string converted to null wrapper
assertEquals(Long.valueOf(123), l);
}Enum Types
Enum conversion uses Enum.valueOf() with case-sensitive matching by default:
enum Status { ACTIVE, INACTIVE, PENDING }
@DataProvider(ignoreEnumCase = false) // Case-sensitive (default)
@DataProvider(ignoreEnumCase = true) // Case-insensitive@Test
@DataProvider({"ACTIVE,INACTIVE"})
public void testEnums(Status status1, Status status2) {
assertEquals(Status.ACTIVE, status1);
assertEquals(Status.INACTIVE, status2);
}
@Test
@DataProvider(value = {"active,inactive"}, ignoreEnumCase = true)
public void testEnumsCaseInsensitive(Status status1, Status status2) {
assertEquals(Status.ACTIVE, status1); // "active" converted to ACTIVE
assertEquals(Status.INACTIVE, status2); // "inactive" converted to INACTIVE
}String Type
Strings are used directly without conversion:
@Test
@DataProvider({"hello,world,test string"})
public void testStrings(String s1, String s2, String s3) {
assertEquals("hello", s1);
assertEquals("world", s2);
assertEquals("test string", s3);
}Custom Types with String Constructor
Types with a single-argument String constructor are automatically supported:
public class CustomType {
private final String value;
public CustomType(String value) { // Required constructor
this.value = value;
}
// getters, equals, etc.
}
@Test
@DataProvider({"value1,value2"})
public void testCustomType(CustomType ct1, CustomType ct2) {
// CustomType("value1") and CustomType("value2") are created automatically
}Data Provider Examples by Use Case
Testing with Multiple Data Sources
@DataProvider
public static Object[][] mixedDataTypes() {
return new Object[][] {
{ "string", 123, true, Status.ACTIVE },
{ "another", 456, false, Status.INACTIVE },
{ null, 0, false, Status.PENDING }
};
}
@Test
@UseDataProvider("mixedDataTypes")
public void testMixedTypes(String str, int num, boolean flag, Status status) {
// Test logic with various parameter types
}Testing Edge Cases
@DataProvider
public static Object[][] edgeCases() {
return new Object[][] {
{ "", 0 }, // Empty string
{ null, -1 }, // Null value
{ "whitespace ", 10 }, // Trailing whitespace
{ "unicode\u00A9", 8 } // Unicode characters
};
}Large Data Sets
@DataProvider
public static Object[][] generateLargeDataSet() {
Object[][] data = new Object[1000][2];
for (int i = 0; i < 1000; i++) {
data[i] = new Object[] { "test" + i, i };
}
return data;
}Type Conversion Error Handling
When automatic type conversion fails, the framework throws appropriate runtime exceptions:
- NumberFormatException: Invalid numeric format
- IllegalArgumentException: Invalid enum value or constructor parameter
- RuntimeException: Missing required String constructor for custom types
// This will throw NumberFormatException at runtime
@Test
@DataProvider({"not_a_number"})
public void testInvalidNumber(int number) {
// Never reached due to conversion error
}To handle such cases, ensure your test data matches the expected parameter types or implement proper validation in your data provider methods.
Install with Tessl CLI
npx tessl i tessl/maven-com-tngtech-java--junit-dataprovider