JUnit @ParameterizedTest with @ArgumentsSource

JUnit is a popular testing framework in the Java ecosystem that simplifies writing and running tests. The @ParameterizedTest annotation in JUnit is used to run the same test with different inputs. This guide covers the basics of using the @ParameterizedTest annotation with @ArgumentsSource to write parameterized tests in JUnit.

Table of Contents

1. Introduction
2. Steps to Create a JUnit Parameterized Test
3. Real-World Use Case
4. Conclusion

Introduction

The @ParameterizedTest annotation marks methods that should be executed multiple times with different parameters. The @ArgumentsSource annotation is used to provide a custom source of arguments (as input data) for the parameterized test.

Steps to Create a JUnit Parameterized Test

Step 1: Add Maven Dependency

To use JUnit in your project, you need to add the JUnit dependency to your pom.xml file. Use the latest version of JUnit 5:

<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-engine</artifactId>
    <version>5.9.2</version>
    <scope>test</scope>
</dependency>

Step 2: Create the Class to be Tested

Create a Java class with methods that you want to test. For example, a simple MathUtils class:

public class MathUtils {
    public int add(int a, int b) {
        return a + b;
    }

    public int subtract(int a, int b) {
        return a - b;
    }
}

Step 3: Create a Custom Arguments Provider

Create a custom arguments provider by implementing the ArgumentsProvider interface. This provider will supply the arguments for the parameterized test.

import org.junit.jupiter.api.extension.ExtensionContext;
import org.junit.jupiter.params.provider.Arguments;
import org.junit.jupiter.params.provider.ArgumentsProvider;
import java.util.stream.Stream;

public class AdditionArgumentsProvider implements ArgumentsProvider {
    @Override
    public Stream<? extends Arguments> provideArguments(ExtensionContext context) {
        return Stream.of(
            Arguments.of(1, 2, 3),
            Arguments.of(2, 3, 5),
            Arguments.of(3, 4, 7),
            Arguments.of(4, 5, 9)
        );
    }
}

Step 4: Create the Parameterized Test Class

Create a test class in the src/test/java directory. Use the @ParameterizedTest annotation and specify the custom arguments provider using @ArgumentsSource.

import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ArgumentsSource;
import static org.junit.jupiter.api.Assertions.assertEquals;

public class MathUtilsTest {
    private final MathUtils mathUtils = new MathUtils();

    @ParameterizedTest
    @ArgumentsSource(AdditionArgumentsProvider.class)
    void testAddition(int a, int b, int expected) {
        assertEquals(expected, mathUtils.add(a, b), a + " + " + b + " should equal " + expected);
    }
}

In this example, the testAddition method is annotated with @ParameterizedTest and uses @ArgumentsSource to provide the parameter sets from the custom AdditionArgumentsProvider class. The test method will be executed once for each set of arguments.

Step 5: Run the Test

You can run the test using your IDE, Maven, or Gradle.

Using an IDE:

Most IDEs, like IntelliJ IDEA and Eclipse, have built-in support for running JUnit tests. Simply right-click on your test class or method and select “Run.”

Using Maven:

If you’re using Maven, you can run your tests with the following command:

mvn test

Using Gradle:

If you’re using Gradle, you can run your tests with the following command:

gradle test

Real-World Use Case

In real-world applications, you may need to test methods with various inputs. For instance, a StringUtils class might need to be tested with different string inputs and expected results.

Create the Class to be Tested

Create a Java class that contains business logic. For example, a StringUtils class that capitalizes strings:

public class StringUtils {
    public String capitalize(String str) {
        if (str == null || str.isEmpty()) {
            return str;
        }
        return str.substring(0, 1).toUpperCase() + str.substring(1).toLowerCase();
    }
}

In this class, the capitalize method capitalizes the first letter of a given string.

Create a Custom Arguments Provider

Create a custom arguments provider by implementing the ArgumentsProvider interface. This provider will supply the arguments for the parameterized test.

import org.junit.jupiter.api.extension.ExtensionContext;
import org.junit.jupiter.params.provider.Arguments;
import org.junit.jupiter.params.provider.ArgumentsProvider;
import java.util.stream.Stream;

public class CapitalizeArgumentsProvider implements ArgumentsProvider {
    @Override
    public Stream<? extends Arguments> provideArguments(ExtensionContext context) {
        return Stream.of(
            Arguments.of("hello", "Hello"),
            Arguments.of("world", "World"),
            Arguments.of("java", "Java"),
            Arguments.of("", ""),
            Arguments.of(null, null)
        );
    }
}

Create the Parameterized Test Class

Create a test class for the StringUtils in the src/test/java directory. Use the @ParameterizedTest annotation and specify the custom arguments provider using @ArgumentsSource.

import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ArgumentsSource;
import static org.junit.jupiter.api.Assertions.assertEquals;

public class StringUtilsTest {
    private final StringUtils stringUtils = new StringUtils();

    @ParameterizedTest
    @ArgumentsSource(CapitalizeArgumentsProvider.class)
    void testCapitalize(String input, String expected) {
        assertEquals(expected, stringUtils.capitalize(input), "Capitalizing '" + input + "' should give '" + expected + "'");
    }
}

In this test class, the testCapitalize method is annotated with @ParameterizedTest and uses @ArgumentsSource to provide the parameter sets from the custom CapitalizeArgumentsProvider class. The test method will be executed once for each set of arguments.

Running the Tests

You can run the tests using your IDE, Maven, or Gradle.

Using an IDE:

Most IDEs, like IntelliJ IDEA and Eclipse, have built-in support for running JUnit tests. Simply right-click on your test class or method and select “Run.”

Using Maven:

If you’re using Maven, you can run your tests with the following command:

mvn test

Using Gradle:

If you’re using Gradle, you can run your tests with the following command:

gradle test

Conclusion

The @ParameterizedTest annotation in JUnit makes it easy to run the same test with different inputs. By using @ParameterizedTest with @ArgumentsSource, you can ensure that your methods behave correctly with various inputs without writing multiple test cases.