0
# JUnit Jupiter Params
1

2
JUnit Jupiter Params provides a comprehensive parameterized testing extension for JUnit 5, enabling developers to run the same test method multiple times with different input parameters. It offers a rich set of argument providers, automatic type conversion, and argument aggregation capabilities to significantly reduce code duplication and improve test coverage.
3

4
## Package Information
5

6
- **Package Name**: org.junit.jupiter:junit-jupiter-params
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: `implementation 'org.junit.jupiter:junit-jupiter-params:5.12.2'` (Gradle) or `<dependency><groupId>org.junit.jupiter</groupId><artifactId>junit-jupiter-params</artifactId><version>5.12.2</version></dependency>` (Maven)
10

11
## Core Imports
12

13
```java
14
import org.junit.jupiter.params.ParameterizedTest;
15
import org.junit.jupiter.params.provider.ValueSource;
16
import org.junit.jupiter.params.provider.CsvSource;
17
import org.junit.jupiter.params.provider.MethodSource;
18
```
19

20
## Basic Usage
21

22
```java
23
import org.junit.jupiter.params.ParameterizedTest;
24
import org.junit.jupiter.params.provider.ValueSource;
25
import org.junit.jupiter.params.provider.CsvSource;
26

27
class ParameterizedTestExamples {
28

29
    @ParameterizedTest
30
    @ValueSource(strings = {"apple", "banana", "cherry"})
31
    void testWithStringValues(String fruit) {
32
        assertNotNull(fruit);
33
        assertTrue(fruit.length() > 3);
34
    }
35

36
    @ParameterizedTest
37
    @CsvSource({
38
        "1, apple, true",
39
        "2, banana, false", 
40
        "3, cherry, true"
41
    })
42
    void testWithCsvSource(int id, String name, boolean active) {
43
        assertTrue(id > 0);
44
        assertNotNull(name);
45
    }
46
}
47
```
48

49
## Architecture
50

51
JUnit Jupiter Params is built around several key components:
52

53
- **Core Annotation**: `@ParameterizedTest` marks test methods for parameterized execution
54
- **Argument Sources**: Annotations that provide test arguments from various data sources
55
- **Argument Conversion**: Automatic and explicit conversion between argument types
56
- **Argument Aggregation**: Combining multiple arguments into single parameter objects
57
- **Provider SPI**: Extension points for custom argument providers and converters
58

59
## Capabilities
60

61
### Core Testing Annotation
62

63
The fundamental annotation for creating parameterized tests with customizable display names and validation modes.
64

65
```java { .api }
66
@Target(ElementType.METHOD)
67
@Retention(RetentionPolicy.RUNTIME)
68
@interface ParameterizedTest {
69
    String name() default "[{index}] {argumentSetNameOrArgumentsWithNames}";
70
    boolean autoCloseArguments() default true;
71
    boolean allowZeroInvocations() default false;
72
    ArgumentCountValidationMode argumentCountValidation() default DEFAULT;
73
}
74

75
enum ArgumentCountValidationMode {
76
    DEFAULT, NONE, STRICT
77
}
78
```
79

80
[Core Testing](./core-testing.md)
81

82
### Value-Based Sources
83

84
Simple argument providers for literal values, null values, and empty collections.
85

86
```java { .api }
87
@interface ValueSource {
88
    short[] shorts() default {};
89
    byte[] bytes() default {};
90
    int[] ints() default {};
91
    long[] longs() default {};
92
    float[] floats() default {};
93
    double[] doubles() default {};
94
    char[] chars() default {};
95
    boolean[] booleans() default {};
96
    String[] strings() default {};
97
    Class<?>[] classes() default {};
98
}
99

100
@interface NullSource { }
101
@interface EmptySource { }
102
@interface NullAndEmptySource { }
103
```
104

105
[Value-Based Sources](./value-sources.md)
106

107
### CSV Data Sources
108

109
Comprehensive CSV data support for inline data and external files with extensive parsing customization.
110

111
```java { .api }
112
@interface CsvSource {
113
    String[] value() default {};
114
    String textBlock() default "";
115
    boolean useHeadersInDisplayName() default false;
116
    char quoteCharacter() default '\'';
117
    char delimiter() default ',';
118
    String delimiterString() default "";
119
    String emptyValue() default "";
120
    String[] nullValues() default "";
121
    int maxCharsPerColumn() default 4096;
122
    boolean ignoreLeadingAndTrailingWhitespace() default true;
123
}
124

125
@interface CsvFileSource {
126
    String[] resources() default {};
127
    String[] files() default {};
128
    String encoding() default "UTF-8";
129
    String lineSeparator() default "\n";
130
    int numLinesToSkip() default 0;
131
    // ... plus all CsvSource parsing attributes
132
}
133
```
134

135
[CSV Data Sources](./csv-sources.md)
136

137
### Enum and Method Sources
138

139
Advanced argument providers for enum constants and method-generated arguments.
140

141
```java { .api }
142
@interface EnumSource {
143
    Class<? extends Enum<?>> value() default Enum.class;
144
    String[] names() default {};
145
    Mode mode() default INCLUDE;
146
    
147
    enum Mode {
148
        INCLUDE, EXCLUDE, MATCH_ALL, MATCH_ANY, MATCH_NONE
149
    }
150
}
151

152
@interface MethodSource {
153
    String[] value() default "";
154
}
155

156
@interface FieldSource {
157
    String[] value() default "";
158
}
159
```
160

161
[Enum and Method Sources](./enum-method-sources.md)
162

163
### Custom Sources and Core Interfaces
164

165
Extension points for custom argument providers and the fundamental interfaces.
166

167
```java { .api }
168
@interface ArgumentsSource {
169
    Class<? extends ArgumentsProvider> value();
170
}
171

172
interface ArgumentsProvider {
173
    Stream<? extends Arguments> provideArguments(ExtensionContext context) 
174
        throws Exception;
175
}
176

177
interface Arguments {
178
    Object[] get();
179
    
180
    static Arguments of(Object... arguments) { /* ... */ }
181
    static Arguments arguments(Object... arguments) { /* ... */ }
182
}
183
```
184

185
[Custom Sources](./custom-sources.md)
186

187
### Argument Conversion
188

189
Type conversion system with built-in converters and extension points for custom conversions.
190

191
```java { .api }
192
@interface ConvertWith {
193
    Class<? extends ArgumentConverter> value();
194
}
195

196
interface ArgumentConverter {
197
    Object convert(Object source, ParameterContext context) 
198
        throws ArgumentConversionException;
199
}
200

201
abstract class SimpleArgumentConverter implements ArgumentConverter {
202
    protected abstract Object convert(Object source, Class<?> targetType) 
203
        throws ArgumentConversionException;
204
}
205

206
abstract class TypedArgumentConverter<S, T> implements ArgumentConverter {
207
    protected TypedArgumentConverter(Class<S> sourceType, Class<T> targetType) { }
208
    protected abstract T convert(S source) throws ArgumentConversionException;
209
}
210
```
211

212
[Argument Conversion](./argument-conversion.md)
213

214
### Argument Aggregation
215

216
System for combining multiple arguments into single parameter objects with type-safe access.
217

218
```java { .api }
219
@interface AggregateWith {
220
    Class<? extends ArgumentsAggregator> value();
221
}
222

223
interface ArgumentsAccessor {
224
    Object get(int index);
225
    <T> T get(int index, Class<T> requiredType);
226
    
227
    // Typed getters
228
    Character getCharacter(int index);
229
    Boolean getBoolean(int index);
230
    Byte getByte(int index);
231
    Short getShort(int index);
232
    Integer getInteger(int index);
233
    Long getLong(int index);
234
    Float getFloat(int index);
235
    Double getDouble(int index);
236
    String getString(int index);
237
    
238
    int size();
239
    Object[] toArray();
240
    List<Object> toList();
241
}
242

243
interface ArgumentsAggregator {
244
    Object aggregateArguments(ArgumentsAccessor accessor, ParameterContext context)
245
        throws ArgumentsAggregationException;
246
}
247
```
248

249
[Argument Aggregation](./argument-aggregation.md)
250

251
## Exception Types
252

253
```java { .api }
254
class ArgumentConversionException extends JUnitException { }
255
class ArgumentsAggregationException extends JUnitException { }
256
class ArgumentAccessException extends JUnitException { }
257
class CsvParsingException extends JUnitException { }
258
```
259

260
These exceptions provide detailed error information when argument processing fails, helping developers debug parameterized test issues effectively.