0
# Core Testing
1

2
The fundamental annotation and configuration for creating parameterized tests in JUnit Jupiter.
3

4
## Capabilities
5

6
### @ParameterizedTest Annotation
7

8
The primary annotation that marks a test method as parameterized, enabling multiple invocations with different argument sets.
9

10
```java { .api }
11
/**
12
 * Marks a test method as parameterized, enabling execution with multiple argument sets
13
 */
14
@Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD})
15
@Retention(RetentionPolicy.RUNTIME)
16
@Documented
17
@API(status = STABLE, since = "5.0")
18
@TestTemplate
19
@ExtendWith(ParameterizedTestExtension.class)
20
@interface ParameterizedTest {
21
    /**
22
     * Custom display name pattern for test invocations.
23
     * Supports placeholders: {displayName}, {index}, {arguments}, {argumentsWithNames}, 
24
     * {argumentSetName}, {argumentSetNameOrArgumentsWithNames}
25
     */
26
    String name() default "[{index}] {argumentSetNameOrArgumentsWithNames}";
27
    
28
    /**
29
     * Whether to automatically close AutoCloseable arguments after test execution
30
     */
31
    boolean autoCloseArguments() default true;
32
    
33
    /**
34
     * Whether to allow test execution when no argument sources provide arguments
35
     */
36
    boolean allowZeroInvocations() default false;
37
    
38
    /**
39
     * Controls how argument count is validated against parameter count
40
     */
41
    ArgumentCountValidationMode argumentCountValidation() default DEFAULT;
42
}
43
```
44

45
**Usage Examples:**
46

47
```java
48
import org.junit.jupiter.params.ParameterizedTest;
49
import org.junit.jupiter.params.provider.ValueSource;
50

51
class CoreTestingExample {
52

53
    // Basic parameterized test
54
    @ParameterizedTest
55
    @ValueSource(ints = {1, 2, 3})
56
    void testWithDefaultName(int value) {
57
        assertTrue(value > 0);
58
    }
59

60
    // Custom display name
61
    @ParameterizedTest(name = "Testing with value: {0}")
62
    @ValueSource(strings = {"apple", "banana"})
63
    void testWithCustomName(String fruit) {
64
        assertNotNull(fruit);
65
    }
66

67
    // Custom display name with placeholders
68
    @ParameterizedTest(name = "[{index}] {displayName} - input: {arguments}")
69
    @ValueSource(doubles = {1.5, 2.5, 3.5})
70
    void testWithDetailedName(double value) {
71
        assertTrue(value > 1.0);
72
    }
73
}
74
```
75

76
### Argument Count Validation Mode
77

78
Controls how the framework validates the number of arguments provided against the number of test method parameters.
79

80
```java { .api }
81
/**
82
 * Validation mode for argument count vs parameter count
83
 */
84
@API(status = EXPERIMENTAL, since = "5.12")
85
enum ArgumentCountValidationMode {
86
    /**
87
     * Default validation behavior - typically strict validation
88
     */
89
    DEFAULT,
90
    
91
    /**
92
     * No argument count validation performed
93
     */
94
    NONE,
95
    
96
    /**
97
     * Strict validation - argument count must exactly match parameter count
98
     */
99
    STRICT
100
}
101
```
102

103
**Usage Examples:**
104

105
```java
106
import org.junit.jupiter.params.ParameterizedTest;
107
import org.junit.jupiter.params.ArgumentCountValidationMode;
108
import org.junit.jupiter.params.provider.CsvSource;
109

110
class ValidationModeExample {
111

112
    // Strict validation (default behavior)
113
    @ParameterizedTest
114
    @CsvSource({"1,apple", "2,banana"})
115
    void testStrictValidation(int id, String name) {
116
        // Must have exactly 2 arguments for 2 parameters
117
    }
118

119
    // No validation - allows mismatched argument counts
120
    @ParameterizedTest(argumentCountValidation = ArgumentCountValidationMode.NONE)
121
    @CsvSource({"1,apple,extra", "2,banana"}) // Mixed argument counts
122
    void testNoValidation(int id, String name) {
123
        // Accepts varying argument counts
124
    }
125

126
    // Explicit strict validation
127
    @ParameterizedTest(argumentCountValidation = ArgumentCountValidationMode.STRICT)
128
    @CsvSource({"1,apple", "2,banana"})
129
    void testExplicitStrictValidation(int id, String name) {
130
        // Enforces exact argument count match
131
    }
132
}
133
```
134

135
### Display Name Patterns
136

137
The `name` attribute supports several placeholder patterns for customizing test display names:
138

139
- `{displayName}` - The display name of the test method
140
- `{index}` - The current invocation index (1-based)
141
- `{arguments}` - Complete argument list as comma-separated string
142
- `{argumentsWithNames}` - Arguments with parameter names if available
143
- `{0}`, `{1}`, ... - Individual arguments by index
144

145
**Display Name Examples:**
146

147
```java
148
class DisplayNameExamples {
149

150
    @ParameterizedTest(name = "Test #{index}: {displayName}")
151
    @ValueSource(ints = {1, 2, 3})
152
    void basicCounter(int value) { }
153
    // Displays: "Test #1: basicCounter", "Test #2: basicCounter", etc.
154

155
    @ParameterizedTest(name = "Value {0} should be positive")
156
    @ValueSource(ints = {1, 2, 3})
157
    void positiveNumbers(int value) { }
158
    // Displays: "Value 1 should be positive", "Value 2 should be positive", etc.
159

160
    @ParameterizedTest(name = "Processing: {arguments}")
161
    @CsvSource({"apple,red", "banana,yellow"})
162
    void colorMapping(String fruit, String color) { }
163
    // Displays: "Processing: apple, red", "Processing: banana, yellow"
164
}
165
```
166

167
### AutoCloseable Resource Management
168

169
When `autoCloseArguments = true` (default), the framework automatically closes any `AutoCloseable` arguments after test execution:
170

171
```java
172
class ResourceManagementExample {
173

174
    @ParameterizedTest
175
    @MethodSource("provideStreams")
176
    void testWithAutoClose(InputStream stream) {
177
        // Stream automatically closed after test execution
178
        assertNotNull(stream);
179
    }
180

181
    @ParameterizedTest(autoCloseArguments = false)
182
    @MethodSource("provideStreams") 
183
    void testWithoutAutoClose(InputStream stream) {
184
        // Must manually close stream if needed
185
        try (stream) {
186
            assertNotNull(stream);
187
        }
188
    }
189

190
    static Stream<InputStream> provideStreams() {
191
        return Stream.of(
192
            new ByteArrayInputStream("test1".getBytes()),
193
            new ByteArrayInputStream("test2".getBytes())
194
        );
195
    }
196
}
197
```
198

199
This feature ensures proper resource cleanup and prevents resource leaks in parameterized tests that work with files, streams, database connections, or other closeable resources.