@ValueSource for simple values in JUnit - Deep Dive

Overview - @ValueSource for simple values

What is it?

@ValueSource is an annotation in JUnit that lets you run the same test multiple times with different simple input values. It helps you test how your code behaves with various inputs without writing separate tests for each. You provide a list of values like strings, ints, or doubles, and JUnit runs the test once for each value.

Why it matters

Without @ValueSource, you would write many similar tests that differ only by input values, making your code longer and harder to maintain. @ValueSource saves time and reduces mistakes by automating repeated tests with different inputs. This means bugs related to specific inputs are more likely to be caught early.

Where it fits

Before learning @ValueSource, you should understand basic JUnit tests and how to write simple test methods. After mastering @ValueSource, you can explore more advanced parameterized tests like @CsvSource or @MethodSource for complex inputs.

Mental Model

Core Idea

@ValueSource runs one test method multiple times, each time with a different simple input value you provide.

Think of it like...

It's like testing a recipe by cooking it several times, each time using a different spice to see how the flavor changes.

┌───────────────┐
│ Test Method   │
│ with @ValueSource │
└──────┬────────┘
       │ runs once per value
       ▼
┌───────────────┐
│ Input Value 1 │
└───────────────┘
       │
       ▼
┌───────────────┐
│ Input Value 2 │
└───────────────┘
       │
      ...
       │
       ▼
┌───────────────┐
│ Input Value N │
└───────────────┘

Build-Up - 7 Steps

1

Foundation

Basic JUnit Test Method

Concept: Understanding how to write a simple test method in JUnit.

A JUnit test method is a Java method annotated with @Test. It contains code to check if a part of your program works as expected. For example: @Test void testIsPositive() { assertTrue(5 > 0); }

Result

JUnit runs this method once and reports if the assertion passes or fails.

Knowing how to write a basic test method is essential before adding input variations.

2

Foundation

Introduction to Parameterized Tests

Concept: Running the same test multiple times with different inputs using JUnit's parameterized tests.

JUnit allows tests to run repeatedly with different inputs by using @ParameterizedTest instead of @Test. This tells JUnit to expect multiple runs with varying parameters.

Result

The test method runs once for each input value provided by a source.

This approach avoids writing many similar tests and keeps code concise.

3

Intermediate

Using @ValueSource for Simple Inputs

🤔Before reading on: do you think @ValueSource can provide multiple types of simple values in one annotation? Commit to your answer.

Concept: @ValueSource lets you supply a list of simple values like ints, strings, or doubles to a parameterized test.

Example: @ParameterizedTest @ValueSource(strings = {"apple", "banana", "cherry"}) void testFruits(String fruit) { assertNotNull(fruit); } JUnit runs testFruits three times, each time with a different fruit string.

Result

The test runs three times, once per fruit, passing if none are null.

Understanding that @ValueSource supports only simple types helps you choose it for straightforward input lists.

4

Intermediate

Supported Data Types in @ValueSource

🤔Before reading on: do you think @ValueSource supports complex objects like lists or custom classes? Commit to your answer.

Concept: @ValueSource supports only simple data types like int, long, double, float, short, byte, char, boolean, and String arrays.

You can write: @ValueSource(ints = {1, 2, 3}) void testNumbers(int number) { assertTrue(number > 0); } But you cannot pass complex objects directly with @ValueSource.

Result

Tests run once per simple value, but complex inputs require other sources.

Knowing the data type limits prevents confusion and guides you to use other parameter sources when needed.

5

Intermediate

Combining @ValueSource with Assertions

🤔Before reading on: do you think assertions inside parameterized tests behave differently than in regular tests? Commit to your answer.

Concept: Assertions inside parameterized tests check each input value separately, so failures show which input caused the problem.

Example: @ParameterizedTest @ValueSource(strings = {"hello", "", "world"}) void testNonEmptyStrings(String input) { assertFalse(input.isEmpty()); } This test will fail for the empty string input.

Result

JUnit reports failure only for the input that breaks the assertion.

Understanding this helps you quickly identify problematic inputs during test runs.

6

Advanced

Limitations and Alternatives to @ValueSource

🤔Before reading on: do you think @ValueSource can handle null values? Commit to your answer.

Concept: @ValueSource cannot provide null values or complex objects; for those, use @NullSource, @EmptySource, or @MethodSource.

If you want to test null inputs: @ParameterizedTest @NullSource void testNullInput(String input) { assertNull(input); } For complex objects, @MethodSource lets you supply any data.

Result

You learn when to switch from @ValueSource to other parameter sources.

Knowing @ValueSource's limits prevents test failures and guides better test design.

7

Expert

How JUnit Executes @ValueSource Tests Internally

🤔Before reading on: do you think JUnit creates a new test instance for each @ValueSource input? Commit to your answer.

Concept: JUnit creates a new test instance for each input value and injects the parameter before running the test method.

When JUnit sees @ValueSource, it reads the values, then for each value: 1. Creates a fresh test class instance. 2. Passes the value to the test method parameter. 3. Runs the test method. 4. Reports the result. This isolation ensures tests don't affect each other.

Result

Tests are independent and results clearly show which input passed or failed.

Understanding this isolation helps explain why tests remain reliable and side-effect free.

Under the Hood

JUnit's parameterized test engine scans for @ValueSource annotations and extracts the array of values. For each value, it creates a new instance of the test class, injects the value into the test method parameter, and executes the test method. This process repeats for all values, collecting results separately. The test runner then aggregates these results into a single report showing which inputs passed or failed.

Why designed this way?

JUnit was designed to keep tests isolated to avoid shared state bugs. Running each parameterized test with a fresh instance prevents side effects between runs. Using annotations like @ValueSource makes it easy to declare simple input sets without extra boilerplate, improving developer productivity and test clarity.

┌───────────────┐
│ Test Class    │
│ with @ValueSource │
└──────┬────────┘
       │ Extract values
       ▼
┌───────────────┐
│ Value 1       │
└──────┬────────┘
       │ Create new test instance
       ▼
┌───────────────┐
│ Run test with │
│ Value 1       │
└──────┬────────┘
       │ Result 1
       ▼
┌───────────────┐
│ Value 2       │
└──────┬────────┘
       │ Create new test instance
       ▼
┌───────────────┐
│ Run test with │
│ Value 2       │
└──────┬────────┘
       │ Result 2
      ...
       ▼
┌───────────────┐
│ Aggregate     │
│ Results       │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Can @ValueSource provide null values to a test method? Commit to yes or no before reading on.

Common Belief: Yes, @ValueSource can provide null values just like any other value.

Reality: @ValueSource cannot provide null values; you must use @NullSource or @NullAndEmptySource for null inputs.

Why it matters: Trying to pass null with @ValueSource causes test failures or errors, confusing beginners and wasting debugging time.

Quick: Does @ValueSource support passing complex objects like lists or custom classes? Commit to yes or no before reading on.

Common Belief: Yes, you can pass any object type with @ValueSource by listing them directly.

Reality: @ValueSource supports only simple primitive types and strings, not complex objects. For complex inputs, use @MethodSource or @CsvSource.

Why it matters: Misusing @ValueSource for complex objects leads to compilation errors or runtime failures, blocking test progress.

Quick: Does a failure in one @ValueSource input stop the entire parameterized test? Commit to yes or no before reading on.

Common Belief: If one input fails, the whole parameterized test stops running further inputs.

Reality: JUnit runs all inputs independently; a failure in one input does not stop other inputs from running.

Why it matters: Knowing this helps testers trust that all inputs are checked, improving test coverage and debugging.

Quick: Does @ValueSource allow mixing different data types in one annotation? Commit to yes or no before reading on.

Common Belief: Yes, you can mix ints, strings, and booleans together in one @ValueSource annotation.

Reality: No, each @ValueSource annotation supports only one data type array at a time.

Why it matters: Trying to mix types causes compilation errors, so tests must be split or use other parameter sources.

Expert Zone

1

JUnit creates a new test instance per input value to guarantee test isolation, which can affect tests relying on shared state or expensive setup.

2

When stacking multiple parameter sources, @ValueSource is often combined with @NullSource or @EmptySource to cover edge cases efficiently.

3

The order of values in @ValueSource matters for test reporting and debugging; placing common or critical cases first can speed up failure detection.

When NOT to use

@ValueSource is not suitable when you need to test complex objects, null values, or multiple parameters simultaneously. In those cases, use @MethodSource for custom objects or @CsvSource for multiple parameters.

Production Patterns

In real projects, @ValueSource is commonly used for quick sanity checks with simple inputs like numbers or strings. For example, testing input validation methods with various valid and invalid strings. It is often combined with other parameter sources to cover null and empty cases without extra code.

Connections

Data-Driven Testing

Builds-on

Understanding @ValueSource helps grasp the broader idea of running tests repeatedly with different data sets to improve coverage.

Function Parameterization in Programming

Same pattern

Just like functions accept parameters to behave differently, @ValueSource feeds parameters to tests to check multiple scenarios with one method.

Scientific Experiment Replication

Builds-on

Running tests with different inputs is like repeating experiments with varied conditions to confirm results are consistent and reliable.

Common Pitfalls

#1 Trying to pass null values using @ValueSource.

Wrong approach:

@ParameterizedTest
@ValueSource(strings = {null, "test"})
void testWithNull(String input) {
assertNotNull(input);
}

Correct approach:

@ParameterizedTest
@NullSource
@ValueSource(strings = {"test"})
void testWithNull(String input) {
assertNotNull(input);
}

Root cause:

Misunderstanding that @ValueSource cannot handle null values, which require a separate annotation.

#2 Mixing different data types in one @ValueSource annotation.

Wrong approach:

@ParameterizedTest
@ValueSource(strings = {"one"}, ints = {1})
void testMixedTypes(Object input) {
assertNotNull(input);
}

Correct approach:

@ParameterizedTest
@ValueSource(strings = {"one"})
void testStrings(String input) {
assertNotNull(input);
}

@ParameterizedTest
@ValueSource(ints = {1})
void testInts(int input) {
assertTrue(input > 0);
}

Root cause:

Incorrect assumption that @ValueSource supports multiple types in one annotation; it supports only one type per annotation.

#3 Expecting parameterized tests to stop after first failure.

Wrong approach:

Assuming test execution halts on first failed input and ignoring later inputs.

Correct approach:

Understanding that JUnit runs all inputs independently and reports all failures separately.

Root cause:

Misconception about test runner behavior leading to incomplete test coverage.

Key Takeaways

@ValueSource is a simple way to run the same test multiple times with different simple input values like strings or numbers.

It supports only one data type per annotation and cannot provide null or complex objects directly.

JUnit creates a new test instance for each input value to keep tests isolated and reliable.

Failures in one input do not stop other inputs from being tested, ensuring full coverage.

For more complex inputs or null values, other parameter sources like @MethodSource or @NullSource should be used.