Close

JUnit 5 - @ParameterizedTest with SimpleArgumentConverter

[Last Updated: Dec 5, 2025]

Use a custom SimpleArgumentConverter and annotate the parameter with @ConvertWith in a @ParameterizedTest to transform input values.

Java source and doc

public abstract class SimpleArgumentConverter {

    // Convert the supplied source object into the supplied target type.
    protected abstract Object convert(Object source, Class<?> targetType)
                                              throws ArgumentConversionException;

}

Example Project

package com.logicbig.example;

import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.converter.ConvertWith;
import org.junit.jupiter.params.converter.SimpleArgumentConverter;

import java.time.LocalDate;
import java.time.format.DateTimeFormatter;

import static org.junit.jupiter.api.Assertions.assertEquals;

public class ParameterizedSimpleArgumentConverterTest {

    static class StringToLocalDateConverter extends SimpleArgumentConverter {
        @Override
        protected Object convert(Object source, Class<?> targetType) {
            if (source == null) return null;
            if (!LocalDate.class.equals(targetType)) {
                throw new IllegalArgumentException("Conversion target must be LocalDate");
            }
            return LocalDate.parse(source.toString(), DateTimeFormatter.ISO_LOCAL_DATE);
        }
    }

    @ParameterizedTest(name = "#{index} parsed date: {0}")
    @org.junit.jupiter.params.provider.ValueSource(strings = {"2024-01-01", "2025-12-04"})
    void convertStringToLocalDate(@ConvertWith(StringToLocalDateConverter.class) LocalDate date) {
        // verify round-trip formatting
        assertEquals(date, LocalDate.parse(date.toString()));
    }
}
mvn test -Dtest=ParameterizedSimpleArgumentConverterTest

Output

D:\example-projects\junit-5\junit-5-parameterized-tests\junit-5-parameterized-simpleargumentconverter>mvn test -Dtest=ParameterizedSimpleArgumentConverterTest
[INFO] Scanning for projects...
[INFO]
[INFO] --< com.logicbig.example:junit-5-parameterized-simpleargumentconverter >--
[INFO] Building junit-5-parameterized-simpleargumentconverter 1.0-SNAPSHOT
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- resources:3.3.1:resources (default-resources) @ junit-5-parameterized-simpleargumentconverter ---
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\junit-5-parameterized-tests\junit-5-parameterized-simpleargumentconverter\src\main\resources
[INFO]
[INFO] --- compiler:3.14.1:compile (default-compile) @ junit-5-parameterized-simpleargumentconverter ---
[INFO] No sources to compile
[INFO]
[INFO] --- resources:3.3.1:testResources (default-testResources) @ junit-5-parameterized-simpleargumentconverter ---
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\junit-5-parameterized-tests\junit-5-parameterized-simpleargumentconverter\src\test\resources
[INFO]
[INFO] --- compiler:3.14.1:testCompile (default-testCompile) @ junit-5-parameterized-simpleargumentconverter ---
[INFO] Recompiling the module because of changed source code.
[INFO] Compiling 1 source file with javac [debug target 25] to target\test-classes
[INFO]
[INFO] --- surefire:3.5.0:test (default-test) @ junit-5-parameterized-simpleargumentconverter ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO]
[INFO] -------------------------------------------------------
[INFO] T E S T S
[INFO] -------------------------------------------------------
[INFO] +--com.logicbig.example.ParameterizedSimpleArgumentConverterTest - 0.209 ss
[INFO] | +-- [OK] convertStringToLocalDate(LocalDate) #1 parsed date: "2024-01-01" - 0.070 ss
[INFO] | '-- [OK] convertStringToLocalDate(LocalDate) #2 parsed date: "2025-12-04" - 0.003 ss
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 3.387 s
[INFO] Finished at: 2025-12-04T15:04:16+08:00
[INFO] ------------------------------------------------------------------------

Example Project

Dependencies and Technologies Used:

  • junit-jupiter-engine 6.0.1 (Module "junit-jupiter-engine" of JUnit)
     Version Compatibility: 5.0.0 - 6.0.1Version List
    ×

    Version compatibilities of junit-jupiter-engine with this example:

    • 5.0.0
    • 5.0.1
    • 5.0.2
    • 5.0.3
    • 5.1.0
    • 5.1.1
    • 5.2.0
    • 5.3.0
    • 5.3.1
    • 5.3.2
    • 5.4.0
    • 5.4.1
    • 5.4.2
    • 5.5.0
    • 5.5.1
    • 5.5.2
    • 5.6.0
    • 5.6.1
    • 5.6.2
    • 5.6.3
    • 5.7.0
    • 5.7.1
    • 5.7.2
    • 5.8.0
    • 5.8.1
    • 5.8.2
    • 5.9.0
    • 5.9.1
    • 5.9.2
    • 5.9.3
    • 5.10.0
    • 5.10.1
    • 5.10.2
    • 5.10.3
    • 5.10.4
    • 5.10.5
    • 5.11.0
    • 5.11.1
    • 5.11.2
    • 5.11.3
    • 5.11.4
    • 5.12.0
    • 5.12.1
    • 5.12.2
    • 5.13.0
    • 5.13.1
    • 5.13.2
    • 5.13.3
    • 5.13.4
    • 5.14.0
    • 5.14.1
    • 6.0.0
    • 6.0.1

    Versions in green have been tested.

  • junit-jupiter-params 6.0.1 (Module "junit-jupiter-params" of JUnit)
  • JDK 25
  • Maven 3.9.11

JUnit 5 - Parameterized SimpleArgumentConverter Select All Download
  • junit-5-parameterized-simpleargumentconverter
    • src
      • test
        • java
          • com
            • logicbig
              • example
                • ParameterizedSimpleArgumentConverterTest.java

    See Also