Stop Writing the Same Test Five Times: Mastering JUnit 5 Parameterized Tests

The Problem: Test Bloat and Missing Edge Cases

You have a validation method that checks if a username is valid. You write one test for a null value, one for an empty string, one for a string that is too short, and one for a string containing illegal characters. Suddenly, you have four test methods that are identical except for the input string and the expected result.

This duplication creates a maintenance burden. If the validation logic changes, you must update four different methods. More dangerously, this friction often discourages developers from adding the "just one more" edge case, leaving gaps in coverage because writing a new method feels like a chore.

The solution is @ParameterizedTest. Instead of writing multiple tests for one logic path, you write one test and feed it a stream of data.

Choosing Your Data Source

JUnit 5 provides several ways to inject data into a test, depending on the complexity of the input.

Simple Literals with @ValueSource

Use @ValueSource when you only need a single argument per execution. It supports arrays of primitives and Strings. This is ideal for basic boundary checks, such as verifying that a list of invalid characters all trigger the same exception.

Mapped Inputs with @CsvSource

When you need to test a pair of inputs and expected outputs (e.g., input → expected), @CsvSource is the most efficient choice. It allows you to define comma-separated values that JUnit automatically maps to the method parameters.

Complex Objects with @MethodSource

For scenarios requiring complex objects, collections, or data generated at runtime, @MethodSource is the standard. It points to a static method that returns a Stream, Iterable, or Iterator of arguments. This keeps your test method clean while allowing the data generation logic to be as complex as necessary.

Worked Example: Validating User Input

Assume we are testing a UserValidator class. We want to ensure that various invalid usernames are rejected while valid ones are accepted.

import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.CsvSource;
import org.junit.jupiter.params.provider.MethodSource;
import org.junit.jupiter.params.provider.ValueSource;
import java.util.stream.Stream;
import static org.junit.jupiter.api.Assertions.*;

class UserValidatorTest {

    // Case 1: Simple check for illegal characters
    @ParameterizedTest
    @ValueSource(strings = {"user!", "user@", "user#"})
    void shouldRejectIllegalCharacters(String username) {
        assertFalse(UserValidator.isValid(username));
    }

    // Case 2: Input vs Expected mapping
    @ParameterizedTest
    @CsvSource({
        "validUser, true",
        "", false",
        "a", false",
        "thisUsernameIsWayTooLongForOurSystem, false"
    })
    void validateUsernameBoundaries(String username, boolean expected) {
        assertEquals(expected, UserValidator.isValid(username));
    }

    // Case 3: Complex objects using a MethodSource
    @ParameterizedTest
    @MethodSource("provideUserProfiles")
    void validateUserProfile(UserProfile profile) {
        assertTrue(UserValidator.isValidProfile(profile));
    }

    static Stream<UserProfile> provideUserProfiles() {
        return Stream.of(
            new UserProfile("Alice", 25),
            new UserProfile("Bob", 30)
        );
    }
}

Implementation Details

• Execution: Run these via Maven (mvn test) or Gradle (./gradlew test).
• Permissions: No special permissions are required beyond standard project build access.
• Verification: Check your IDE's test runner or build logs. Each entry in the @ValueSource or @CsvSource will appear as a separate execution node in the test tree.

Trade-offs and Limitations

While powerful, parameterized tests introduce a few risks:

• Failure Obscurity: If a test fails in a list of 50 inputs, it can be hard to pinpoint the failure if you haven't customized the display name. Use the name attribute in @ParameterizedTest(name = "Test {index}: input {0}") to make reports readable.
• Static Constraints: @MethodSource requires the provider method to be static by default. If you need access to instance variables, you must annotate the class with @TestInstance(Lifecycle.PER_CLASS).
• Readability: Large @CsvSource blocks can clutter the top of your method. If your data exceeds 10-15 lines, consider moving the data to an external file using @CsvFileSource.

Actionable Closing

Next time you find yourself copying and pasting a test method to change a single input value, stop. Replace the duplicate methods with a single @ParameterizedTest. Start with @ValueSource for simple flags, move to @CsvSource for input-output pairs, and use @MethodSource for your domain objects. This shift not only cleans up your codebase but encourages you to test the edge cases you previously ignored.