0
# Data Provider Formats and Types
1

2
This document covers the various formats and data types supported by JUnit DataProvider, including return types for data provider methods and parameter type conversion.
3

4
## Supported Return Types
5

6
Data provider methods can return data in several formats, all of which are automatically converted to the appropriate test parameters.
7

8
### Object[][] (Standard Array Format)
9

10
The most common and straightforward format:
11

12
```java
13
@DataProvider
14
public static Object[][] stringTests() {
15
    return new Object[][] {
16
        { "hello", 5, true },
17
        { "world", 5, true },
18
        { "", 0, false },
19
        { "testing", 7, true }
20
    };
21
}
22
```
23

24
### Iterable<Iterable<?>> (Nested Iterables)
25

26
Flexible format using any Iterable implementations:
27

28
```java
29
@DataProvider
30
public static List<List<Object>> iterableTests() {
31
    return Arrays.asList(
32
        Arrays.asList("hello", 5, true),
33
        Arrays.asList("world", 5, true),
34
        Arrays.asList("", 0, false)
35
    );
36
}
37

38
@DataProvider
39
public static Iterable<Iterable<String>> stringIterables() {
40
    Set<List<String>> data = new HashSet<>();
41
    data.add(Arrays.asList("param1", "param2"));
42
    data.add(Arrays.asList("param3", "param4"));
43
    return data;
44
}
45
```
46

47
### Iterable<?> (Single Iterable)
48

49
Each element in the iterable becomes a single parameter test case:
50

51
```java
52
@DataProvider
53
public static List<String> singleParameterTests() {
54
    return Arrays.asList("test1", "test2", "test3");
55
}
56

57
@Test
58
@UseDataProvider("singleParameterTests")
59
public void testSingleParameter(String input) {
60
    assertNotNull(input);
61
}
62
```
63

64
### String[] (String-Based Data)
65

66
String arrays with configurable parsing:
67

68
```java
69
@DataProvider
70
public static String[] stringArrayData() {
71
    return new String[] {
72
        "param1,param2,123",
73
        "param3,param4,456",
74
        "param5,param6,789"
75
    };
76
}
77

78
@DataProvider(splitBy = "\\|", convertNulls = false)
79
public static String[] customDelimiterData() {
80
    return new String[] {
81
        "param1|param2|null",
82
        "param3|param4|notNull"
83
    };
84
}
85
```
86

87
## String Data Provider Configuration
88

89
When using String-based data providers (either through String[] return type or inline @DataProvider values), several configuration options control parsing behavior.
90

91
### Delimiter Configuration
92

93
```java { .api }
94
@DataProvider(splitBy = "\\|")  // Use pipe delimiter
95
@DataProvider(splitBy = ";")    // Use semicolon  
96
@DataProvider(splitBy = "\\s+") // Split on whitespace
97
```
98

99
Default delimiter is comma (`,`).
100

101
### Null Value Handling
102

103
```java { .api }
104
@DataProvider(convertNulls = true)   // "null" string becomes null value (default)
105
@DataProvider(convertNulls = false)  // "null" remains as string literal
106
```
107

108
```java
109
@Test
110
@DataProvider(value = {"test,null,123"}, convertNulls = true)
111
public void testWithNull(String str, String nullValue, int num) {
112
    assertEquals("test", str);
113
    assertNull(nullValue);  // Converted to null
114
    assertEquals(123, num);
115
}
116
```
117

118
### Whitespace Trimming
119

120
```java { .api }
121
@DataProvider(trimValues = true)   // Trim whitespace (default)
122
@DataProvider(trimValues = false)  // Preserve whitespace
123
```
124

125
```java
126
@Test
127
@DataProvider(value = {" test , value "}, trimValues = true)
128
public void testTrimmed(String param1, String param2) {
129
    assertEquals("test", param1);   // Whitespace trimmed
130
    assertEquals("value", param2);  // Whitespace trimmed
131
}
132
```
133

134
## Parameter Type Conversion
135

136
JUnit DataProvider automatically converts string parameters to appropriate types for test method parameters.
137

138
### Primitive Types
139

140
All primitive types are supported via their wrapper class valueOf() methods:
141

142
```java { .api }
143
// Supported primitive types
144
boolean, byte, char, double, float, int, long, short
145

146
// Example conversions
147
"true" → boolean true
148
"123" → int 123  
149
"45.67" → double 45.67
150
"X" → char 'X'
151
```
152

153
```java
154
@Test
155
@DataProvider({"true,123,45.67,X"})
156
public void testPrimitives(boolean b, int i, double d, char c) {
157
    assertTrue(b);
158
    assertEquals(123, i);
159
    assertEquals(45.67, d, 0.001);
160
    assertEquals('X', c);
161
}
162
```
163

164
### Primitive Wrapper Types
165

166
```java { .api }
167
Boolean, Byte, Character, Double, Float, Integer, Long, Short
168
```
169

170
```java
171
@Test
172
@DataProvider({"true,null,123"})
173
public void testWrappers(Boolean b, Integer nullInt, Long l) {
174
    assertTrue(b);
175
    assertNull(nullInt);  // null string converted to null wrapper
176
    assertEquals(Long.valueOf(123), l);
177
}
178
```
179

180
### Enum Types
181

182
Enum conversion uses Enum.valueOf() with case-sensitive matching by default:
183

184
```java { .api }
185
enum Status { ACTIVE, INACTIVE, PENDING }
186

187
@DataProvider(ignoreEnumCase = false)  // Case-sensitive (default)
188
@DataProvider(ignoreEnumCase = true)   // Case-insensitive
189
```
190

191
```java
192
@Test
193
@DataProvider({"ACTIVE,INACTIVE"})
194
public void testEnums(Status status1, Status status2) {
195
    assertEquals(Status.ACTIVE, status1);
196
    assertEquals(Status.INACTIVE, status2);
197
}
198

199
@Test
200
@DataProvider(value = {"active,inactive"}, ignoreEnumCase = true)
201
public void testEnumsCaseInsensitive(Status status1, Status status2) {
202
    assertEquals(Status.ACTIVE, status1);   // "active" converted to ACTIVE
203
    assertEquals(Status.INACTIVE, status2); // "inactive" converted to INACTIVE
204
}
205
```
206

207
### String Type
208

209
Strings are used directly without conversion:
210

211
```java
212
@Test
213
@DataProvider({"hello,world,test string"})
214
public void testStrings(String s1, String s2, String s3) {
215
    assertEquals("hello", s1);
216
    assertEquals("world", s2);
217
    assertEquals("test string", s3);
218
}
219
```
220

221
### Custom Types with String Constructor
222

223
Types with a single-argument String constructor are automatically supported:
224

225
```java
226
public class CustomType {
227
    private final String value;
228
    
229
    public CustomType(String value) {  // Required constructor
230
        this.value = value;
231
    }
232
    
233
    // getters, equals, etc.
234
}
235

236
@Test
237
@DataProvider({"value1,value2"})
238
public void testCustomType(CustomType ct1, CustomType ct2) {
239
    // CustomType("value1") and CustomType("value2") are created automatically
240
}
241
```
242

243
## Data Provider Examples by Use Case
244

245
### Testing with Multiple Data Sources
246

247
```java
248
@DataProvider
249
public static Object[][] mixedDataTypes() {
250
    return new Object[][] {
251
        { "string", 123, true, Status.ACTIVE },
252
        { "another", 456, false, Status.INACTIVE },
253
        { null, 0, false, Status.PENDING }
254
    };
255
}
256

257
@Test
258
@UseDataProvider("mixedDataTypes")
259
public void testMixedTypes(String str, int num, boolean flag, Status status) {
260
    // Test logic with various parameter types
261
}
262
```
263

264
### Testing Edge Cases
265

266
```java
267
@DataProvider
268
public static Object[][] edgeCases() {
269
    return new Object[][] {
270
        { "", 0 },           // Empty string
271
        { null, -1 },        // Null value
272
        { "whitespace ", 10 }, // Trailing whitespace
273
        { "unicode\u00A9", 8 } // Unicode characters
274
    };
275
}
276
```
277

278
### Large Data Sets
279

280
```java
281
@DataProvider
282
public static Object[][] generateLargeDataSet() {
283
    Object[][] data = new Object[1000][2];
284
    for (int i = 0; i < 1000; i++) {
285
        data[i] = new Object[] { "test" + i, i };
286
    }
287
    return data;
288
}
289
```
290

291
## Type Conversion Error Handling
292

293
When automatic type conversion fails, the framework throws appropriate runtime exceptions:
294

295
- **NumberFormatException**: Invalid numeric format
296
- **IllegalArgumentException**: Invalid enum value or constructor parameter
297
- **RuntimeException**: Missing required String constructor for custom types
298

299
```java
300
// This will throw NumberFormatException at runtime
301
@Test
302
@DataProvider({"not_a_number"})  
303
public void testInvalidNumber(int number) {
304
    // Never reached due to conversion error
305
}
306
```
307

308
To handle such cases, ensure your test data matches the expected parameter types or implement proper validation in your data provider methods.