0
# JUnit DataProvider
1

2
JUnit DataProvider is a Java testing library that extends JUnit 4 with TestNG-style data provider functionality, enabling parameterized tests with enhanced syntax and flexibility. The library provides annotations (@DataProvider, @UseDataProvider) that allow test methods to receive data from various sources including arrays, iterables, and string-based formats, supporting complex test scenarios with multiple data sets.
3

4
## Package Information
5

6
- **Package Name**: junit-dataprovider
7
- **Package Type**: maven
8
- **Language**: Java (JDK 1.6+)
9
- **License**: Apache License 2.0
10
- **Maven Coordinates**: com.tngtech.java:junit-dataprovider
11

12
### Installation
13

14
Maven:
15
```xml
16
<dependency>
17
    <groupId>com.tngtech.java</groupId>
18
    <artifactId>junit-dataprovider</artifactId>
19
    <version>1.13.1</version>
20
    <scope>test</scope>
21
</dependency>
22
```
23

24
Gradle:
25
```groovy
26
testImplementation 'com.tngtech.java:junit-dataprovider:1.13.1'
27
```
28

29
## Core Imports
30

31
```java
32
import com.tngtech.java.junit.dataprovider.DataProvider;
33
import com.tngtech.java.junit.dataprovider.DataProviderRunner;
34
import com.tngtech.java.junit.dataprovider.DataProviderFilter;
35
import com.tngtech.java.junit.dataprovider.UseDataProvider;
36
import com.tngtech.java.junit.dataprovider.Placeholders;
37
import org.junit.Test;
38
import org.junit.runner.RunWith;
39
```
40

41
## Basic Usage
42

43
The most common usage pattern involves defining a data provider method and using it in a test:
44

45
```java
46
@RunWith(DataProviderRunner.class)
47
public class ExampleTest {
48
    
49
    @DataProvider
50
    public static Object[][] stringLengthData() {
51
        return new Object[][] {
52
            { "hello", 5 },
53
            { "world", 5 },
54
            { "", 0 },
55
            { "testing", 7 }
56
        };
57
    }
58
    
59
    @Test
60
    @UseDataProvider("stringLengthData")
61
    public void testStringLength(String input, int expectedLength) {
62
        assertEquals(expectedLength, input.length());
63
    }
64
}
65
```
66

67
## Capabilities
68

69
### Runner and Basic Annotations
70

71
The foundation of JUnit DataProvider functionality with the custom runner and core annotations.
72

73
```java { .api }
74
@RunWith(DataProviderRunner.class)
75
public class TestClass {
76
    
77
    @DataProvider
78
    public static Object[][] dataProviderMethod() { /* ... */ }
79
    
80
    @Test
81
    @UseDataProvider("dataProviderMethod")
82
    public void testMethod(/* parameters */) { /* ... */ }
83
}
84
```
85

86
**Key APIs:**
87
- `DataProviderRunner` - Custom JUnit runner that enables data provider functionality
88
- `@DataProvider` - Annotation for marking data provider methods or providing inline data
89
- `@UseDataProvider` - Annotation for test methods to specify which data provider to use
90

91
[Runner and Basic Annotations](./runner-annotations.md)
92

93
### Data Provider Formats and Types
94

95
Support for multiple data formats including arrays, iterables, and string-based data providers.
96

97
```java { .api }
98
// Array format
99
@DataProvider
100
public static Object[][] arrayData() {
101
    return new Object[][] { {"test", 4}, {"hello", 5} };
102
}
103

104
// Iterable format  
105
@DataProvider
106
public static Iterable<Object[]> iterableData() {
107
    return Arrays.asList(new Object[]{"test", 4}, new Object[]{"hello", 5});
108
}
109

110
// String format with inline data
111
@Test
112
@DataProvider({"test, 4", "hello, 5"})
113
public void testWithInlineData(String input, int length) { /* ... */ }
114
```
115

116
**Key features:**
117
- Multiple return type support (Object[][], Iterable variations, String[])
118
- Configurable string parsing with custom delimiters
119
- Automatic type conversion for primitives, enums, and custom types
120
- Null value handling and string trimming options
121

122
[Data Provider Formats and Types](./data-formats.md)
123

124
### Utility Methods and Helper Classes
125

126
Utility classes and methods for creating and manipulating data provider arrays.
127

128
```java { .api }
129
import static com.tngtech.java.junit.dataprovider.DataProviders.*;
130

131
// Helper methods for creating data
132
Object[] row = $("param1", "param2", 123);
133
Object[][] data = $$($("test1", 1), $("test2", 2));
134

135
// Utility methods
136
Object[][] enumTests = DataProviders.testForEach(MyEnum.class);
137
Object[][] crossProduct = DataProviders.crossProduct(data1, data2);
138
```
139

140
**Key utilities:**
141
- DataProviders helper class with $() and $$() methods
142
- testForEach() methods for arrays, iterables, and enum classes
143
- crossProduct() for combining multiple data providers
144

145
[Utility Methods and Helper Classes](./utilities.md)
146

147
### Custom Resolution and Configuration
148

149
Advanced features including custom data provider method resolvers and test name formatting.
150

151
```java { .api }
152
// Custom resolver
153
@UseDataProvider(value = "customName", 
154
                location = OtherClass.class,
155
                resolver = CustomDataProviderMethodResolver.class)
156

157
// Custom formatting
158
@DataProvider(format = "%m[%i: %p[0]]")
159
public static Object[][] formattedData() { /* ... */ }
160

161
// Custom placeholders
162
Placeholders.all().add(0, new CustomPlaceholder());
163
```
164

165
**Key features:**
166
- DataProviderMethodResolver interface for custom resolution strategies
167
- Configurable test method name formatting with placeholder system
168
- Support for data providers in external classes
169
- Multiple resolution strategies (UNTIL_FIRST_MATCH, AGGREGATE_ALL_MATCHES)
170

171
[Custom Resolution and Configuration](./custom-config.md)