JUnit 5: When to Use @ParameterizedTest Instead of Separate @Test Methods

The decision: one test method, many inputs

You have a method to test — say, an email validator or a discount calculator — and you need to check it against a dozen inputs. You can write twelve @Test methods, write one @Test with a loop inside, or write one @ParameterizedTest fed by a data source. The third option is usually right, but not always. The real decision hinges on one question: does the assertion logic stay the same for every input? If yes, parameterize. If the setup or assertions branch per case, keep separate tests.

Parameterized tests report each input as its own node in the test tree, so a failure tells you exactly which input broke. A loop inside a single @Test stops at the first failure and reports only one opaque result — this is the pattern parameterized tests exist to replace.

Comparing the supported options

Prerequisite: the extra dependency

@ParameterizedTest lives in a separate artifact, junit-jupiter-params. If you depend only on junit-jupiter-api, the annotation won't resolve. In Maven (run from the project root, no special permissions needed):

<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-params</artifactId>
    <version>5.10.2</version>
    <scope>test</scope>
</dependency>

If you use the junit-jupiter aggregator artifact, the params module is already included. Check with mvn dependency:tree | grep junit (or ./gradlew dependencies --configuration testCompileClasspath for Gradle) before assuming.

Concrete implementation

Here is a validator tested with @CsvSource, pairing each input with its expected result. This assumes JUnit 5.8+ on the classpath and Maven Surefire 2.22+ (or Gradle's useJUnitPlatform()) so the Jupiter engine actually runs:

import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.CsvSource;
import static org.junit.jupiter.api.Assertions.*;

class DiscountCalculatorTest {

    private final DiscountCalculator calculator = new DiscountCalculator();

    @ParameterizedTest(name = "{0} items at {1} cents -> {2} cents")
    @CsvSource({
        "1,  1000, 1000",
        "5,  1000, 4750",   // 5% bulk discount
        "10, 1000, 9000",   // 10% bulk discount
        "0,  1000, 0"
    })
    void computesTotalWithBulkDiscount(int quantity, int unitPriceCents, int expectedCents) {
        assertEquals(expectedCents, calculator.totalCents(quantity, unitPriceCents));
    }
}

The name attribute uses placeholders ({0}, {1}…) so each iteration shows its arguments in the runner — invest in this, because it is what makes a parameterized failure debuggable without re-running under a debugger.

For object inputs, use @MethodSource pointing at a static Stream<Arguments> factory. Keep that factory boring: if it needs loops, conditionals, or file I/O, move the cases into a dedicated fixture class or reconsider whether these are really one test.

When to stay with plain @Test

Keep separate methods when: each case needs different mock stubbing or fixture setup; the expected outcome is a different kind of assertion (one case asserts a return value, another asserts an exception and its message); or the case names carry domain meaning that a row of CSV data would obscure (rejectsOrderWhenCustomerIsSuspended beats a boolean flag column). A mixed suite is normal: one parameterized test for the uniform happy-path matrix, plus a handful of named @Test methods for the special behaviors.

Validating the result

1. Run mvn test -Dtest=DiscountCalculatorTest (or the Gradle equivalent) from the project root.
2. In your IDE's test tree or the Surefire report, confirm you see four distinct iterations, not one test. If you see a single node, the Jupiter engine isn't picking up the parameterized container — check Surefire/Gradle platform configuration first.
3. Deliberately break one expected value and confirm the failure message names the exact iteration (this is where the name pattern pays off), then revert.

Limitations

@ValueSource accepts only literals — no null (use @NullSource or @NullAndEmptySource) and no objects. @CsvSource converts everything from strings, so watch implicit conversions for dates and enums. Parameterized tests also interact awkwardly with per-test state: the test class instance is created fresh per iteration by default, which is usually what you want but surprises people migrating loop-based tests that accumulated state. Debugging a single iteration in an IDE is possible but clunkier than running one named method — another reason to keep genuinely distinct behaviors as distinct tests.