0
# Value-Based Sources
1

2
Simple and convenient argument providers for literal values, null values, and empty collections.
3

4
## Capabilities
5

6
### @ValueSource Annotation
7

8
Provides arrays of literal values as test arguments, supporting all primitive types, strings, and classes.
9

10
```java { .api }
11
/**
12
 * Provides an array of literal values as arguments to parameterized tests
13
 */
14
@Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD})
15
@Retention(RetentionPolicy.RUNTIME)
16
@Documented
17
@API(status = STABLE, since = "5.0")
18
@ArgumentsSource(ValueArgumentsProvider.class)
19
@Repeatable(ValueSources.class)
20
@interface ValueSource {
21
    /**
22
     * Array of short values
23
     */
24
    short[] shorts() default {};
25
    
26
    /**
27
     * Array of byte values  
28
     */
29
    byte[] bytes() default {};
30
    
31
    /**
32
     * Array of int values
33
     */
34
    int[] ints() default {};
35
    
36
    /**
37
     * Array of long values
38
     */
39
    long[] longs() default {};
40
    
41
    /**
42
     * Array of float values
43
     */
44
    float[] floats() default {};
45
    
46
    /**
47
     * Array of double values
48
     */
49
    double[] doubles() default {};
50
    
51
    /**
52
     * Array of char values
53
     */
54
    char[] chars() default {};
55
    
56
    /**
57
     * Array of boolean values
58
     */
59
    boolean[] booleans() default {};
60
    
61
    /**
62
     * Array of String values
63
     */
64
    String[] strings() default {};
65
    
66
    /**
67
     * Array of Class values
68
     */
69
    Class<?>[] classes() default {};
70
}
71
```
72

73
**Usage Examples:**
74

75
```java
76
import org.junit.jupiter.params.ParameterizedTest;
77
import org.junit.jupiter.params.provider.ValueSource;
78

79
class ValueSourceExamples {
80

81
    @ParameterizedTest
82
    @ValueSource(ints = {1, 2, 3, 5, 8})
83
    void testWithIntegers(int value) {
84
        assertTrue(value > 0);
85
        assertTrue(value < 10);
86
    }
87

88
    @ParameterizedTest
89
    @ValueSource(strings = {"apple", "banana", "cherry"})
90
    void testWithStrings(String fruit) {
91
        assertNotNull(fruit);
92
        assertTrue(fruit.length() > 3);
93
    }
94

95
    @ParameterizedTest  
96
    @ValueSource(doubles = {1.5, 2.7, 3.14159})
97
    void testWithDoubles(double value) {
98
        assertTrue(value > 1.0);
99
    }
100

101
    @ParameterizedTest
102
    @ValueSource(booleans = {true, false})
103
    void testWithBooleans(boolean flag) {
104
        // Test both true and false cases
105
        if (flag) {
106
            assertTrue(flag);
107
        } else {
108
            assertFalse(flag);
109
        }
110
    }
111

112
    @ParameterizedTest
113
    @ValueSource(classes = {String.class, Integer.class, List.class})
114
    void testWithClasses(Class<?> clazz) {
115
        assertNotNull(clazz);
116
        assertNotNull(clazz.getName());
117
    }
118

119
    @ParameterizedTest
120
    @ValueSource(chars = {'a', 'b', 'c'})
121
    void testWithCharacters(char letter) {
122
        assertTrue(Character.isLetter(letter));
123
        assertTrue(Character.isLowerCase(letter));
124
    }
125
}
126
```
127

128
### @NullSource Annotation
129

130
Provides a single `null` argument to parameterized tests.
131

132
```java { .api }
133
/**
134
 * Provides a single null argument to parameterized tests
135
 * Cannot be used with primitive parameter types
136
 */
137
@Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD})
138
@Retention(RetentionPolicy.RUNTIME)
139
@Documented
140
@API(status = STABLE, since = "5.0")
141
@ArgumentsSource(NullArgumentsProvider.class)
142
@interface NullSource {
143
}
144
```
145

146
**Usage Examples:**
147

148
```java
149
import org.junit.jupiter.params.ParameterizedTest;
150
import org.junit.jupiter.params.provider.NullSource;
151
import org.junit.jupiter.params.provider.ValueSource;
152

153
class NullSourceExamples {
154

155
    @ParameterizedTest
156
    @NullSource
157
    void testWithNull(String value) {
158
        assertNull(value);
159
    }
160

161
    // Combine with other sources
162
    @ParameterizedTest
163
    @NullSource
164
    @ValueSource(strings = {"", "  ", "apple"})  
165
    void testNullAndValues(String input) {
166
        // Tests null, empty string, whitespace, and valid string
167
        if (input == null) {
168
            assertNull(input);
169
        } else if (input.trim().isEmpty()) {
170
            assertTrue(input.isEmpty() || input.trim().isEmpty());
171
        } else {
172
            assertFalse(input.trim().isEmpty());
173
        }
174
    }
175

176
    @ParameterizedTest
177
    @NullSource
178
    void testNullCollection(List<String> list) {
179
        assertNull(list);
180
    }
181
}
182
```
183

184
### @EmptySource Annotation
185

186
Provides empty values for supported types including strings, collections, maps, and arrays.
187

188
```java { .api }
189
/**
190
 * Provides empty values for supported types:
191
 * - String: empty string ""
192
 * - Collections: empty List, Set, SortedSet, NavigableSet
193
 * - Maps: empty Map, SortedMap, NavigableMap  
194
 * - Arrays: empty primitive and object arrays
195
 */
196
@Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD})
197
@Retention(RetentionPolicy.RUNTIME)
198
@Documented
199
@API(status = STABLE, since = "5.0")
200
@ArgumentsSource(EmptyArgumentsProvider.class)
201
@interface EmptySource {
202
}
203
```
204

205
**Usage Examples:**
206

207
```java
208
import org.junit.jupiter.params.ParameterizedTest;
209
import org.junit.jupiter.params.provider.EmptySource;
210
import org.junit.jupiter.params.provider.ValueSource;
211
import java.util.*;
212

213
class EmptySourceExamples {
214

215
    @ParameterizedTest
216
    @EmptySource
217
    void testWithEmptyString(String value) {
218
        assertEquals("", value);
219
        assertTrue(value.isEmpty());
220
    }
221

222
    @ParameterizedTest
223
    @EmptySource
224
    void testWithEmptyList(List<String> list) {
225
        assertNotNull(list);
226
        assertTrue(list.isEmpty());
227
        assertEquals(0, list.size());
228
    }
229

230
    @ParameterizedTest
231
    @EmptySource  
232
    void testWithEmptyArray(String[] array) {
233
        assertNotNull(array);
234
        assertEquals(0, array.length);
235
    }
236

237
    @ParameterizedTest
238
    @EmptySource
239
    void testWithEmptyMap(Map<String, Integer> map) {
240
        assertNotNull(map);
241
        assertTrue(map.isEmpty());
242
        assertEquals(0, map.size());
243
    }
244

245
    // Combine with other sources
246
    @ParameterizedTest
247
    @EmptySource
248
    @ValueSource(strings = {"apple", "banana"})
249
    void testEmptyAndValues(String input) {
250
        assertNotNull(input);
251
        if (input.isEmpty()) {
252
            assertEquals("", input);
253
        } else {
254
            assertFalse(input.isEmpty());
255
        }
256
    }
257
}
258
```
259

260
### @NullAndEmptySource Annotation
261

262
Composite annotation that combines `@NullSource` and `@EmptySource` functionality.
263

264
```java { .api }
265
/**
266
 * Composite annotation equivalent to combining @NullSource and @EmptySource
267
 * Provides both null and empty values for the parameter type
268
 */
269
@Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD})
270
@Retention(RetentionPolicy.RUNTIME)
271
@Documented
272
@API(status = STABLE, since = "5.0")
273
@NullSource
274
@EmptySource
275
@interface NullAndEmptySource {
276
}
277
```
278

279
**Usage Examples:**
280

281
```java
282
import org.junit.jupiter.params.ParameterizedTest;
283
import org.junit.jupiter.params.provider.NullAndEmptySource;
284
import org.junit.jupiter.params.provider.ValueSource;
285

286
class NullAndEmptySourceExamples {
287

288
    @ParameterizedTest
289
    @NullAndEmptySource
290
    void testNullAndEmpty(String value) {
291
        // Tests both null and empty string
292
        assertTrue(value == null || value.isEmpty());
293
    }
294

295
    @ParameterizedTest
296
    @NullAndEmptySource
297
    void testNullAndEmptyList(List<String> list) {
298
        // Tests both null and empty list
299
        assertTrue(list == null || list.isEmpty());
300
    }
301

302
    // Combine with additional values
303
    @ParameterizedTest
304
    @NullAndEmptySource
305
    @ValueSource(strings = {"  ", "apple", "banana"})
306
    void testNullEmptyAndValues(String input) {
307
        // Tests null, empty, whitespace, and regular values
308
        if (input == null) {
309
            assertNull(input);
310
        } else if (input.isEmpty()) {
311
            assertEquals("", input);
312
        } else if (input.trim().isEmpty()) {
313
            assertFalse(input.isEmpty());
314
            assertTrue(input.trim().isEmpty());
315
        } else {
316
            assertFalse(input.trim().isEmpty());
317
        }
318
    }
319

320
    @ParameterizedTest
321
    @NullAndEmptySource
322
    @ValueSource(strings = {"valid"})
323
    void testInputValidation(String input) {
324
        boolean isValid = input != null && !input.trim().isEmpty();
325
        
326
        if (input == null || input.isEmpty()) {
327
            assertFalse(isValid);
328
        } else {
329
            assertTrue(isValid);
330
        }
331
    }
332
}
333
```
334

335
### Container Annotations
336

337
Container annotations for multiple instances of repeatable value source annotations.
338

339
```java { .api }
340
/**
341
 * Container annotation for multiple @ValueSource annotations
342
 */
343
@Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD})
344
@Retention(RetentionPolicy.RUNTIME)
345
@Documented
346
@API(status = STABLE, since = "5.0")
347
@interface ValueSources {
348
    ValueSource[] value();
349
}
350
```
351

352
**Usage Example:**
353

354
```java
355
class ContainerAnnotationExample {
356

357
    // Multiple @ValueSource annotations automatically use container
358
    @ParameterizedTest
359
    @ValueSource(ints = {1, 2, 3})
360
    @ValueSource(ints = {10, 20, 30})
361
    void testMultipleValueSources(int value) {
362
        assertTrue(value > 0);
363
        // Tests: 1, 2, 3, 10, 20, 30
364
    }
365
}
366
```
367

368
These value-based sources provide the foundation for simple parameterized testing scenarios and are often combined with other argument sources for comprehensive test coverage.