Argument aggregation in JUnit

Introduction

Argument aggregation helps combine multiple inputs into one place for easier testing. It makes tests cleaner and easier to read.

When you want to test a method with many input values together.

When you want to pass multiple arguments from a data source to a test method.

When you want to organize test inputs clearly in parameterized tests.

When you want to reduce repeated code by grouping arguments.

When you want to improve readability of tests that use many parameters.

Syntax

JUnit

@ArgumentsAggregator
public class MyAggregator implements ArgumentsAggregator {
    @Override
    public Object aggregateArguments(ArgumentsAccessor accessor, ParameterContext context) {
        // Combine arguments from accessor and return one object
    }
}

The @ArgumentsAggregator annotation marks a class that combines arguments.

The aggregateArguments method receives all arguments and returns a single combined object.

Examples

This aggregator combines two arguments (name and age) into one Person object.

JUnit

@ArgumentsAggregator
public class PersonAggregator implements ArgumentsAggregator {
    @Override
    public Person aggregateArguments(ArgumentsAccessor accessor, ParameterContext context) {
        String name = accessor.getString(0);
        int age = accessor.getInteger(1);
        return new Person(name, age);
    }
}

This test uses the aggregator to convert CSV input into Person objects automatically.

JUnit

@ParameterizedTest
@CsvSource({"John,30", "Jane,25"})
void testPerson(@AggregateWith(PersonAggregator.class) Person person) {
    assertNotNull(person);
}

Sample Program

This test uses argument aggregation to convert CSV inputs into Person objects. It checks that the person is not null and age is over 20.

JUnit

import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.aggregator.ArgumentsAccessor;
import org.junit.jupiter.params.aggregator.ArgumentsAggregator;
import org.junit.jupiter.params.aggregator.AggregateWith;
import org.junit.jupiter.params.provider.CsvSource;
import static org.junit.jupiter.api.Assertions.*;

class Person {
    String name;
    int age;
    Person(String name, int age) {
        this.name = name;
        this.age = age;
    }
}

@ArgumentsAggregator
class PersonAggregator implements ArgumentsAggregator {
    @Override
    public Person aggregateArguments(ArgumentsAccessor accessor, org.junit.jupiter.params.aggregator.ParameterContext context) {
        return new Person(accessor.getString(0), accessor.getInteger(1));
    }
}

public class PersonTest {
    @ParameterizedTest
    @CsvSource({"Alice,30", "Bob,25"})
    void testPerson(@AggregateWith(PersonAggregator.class) Person person) {
        assertNotNull(person);
        assertTrue(person.age > 20);
    }
}

Important Notes

Argument aggregation works only with parameterized tests in JUnit 5.

Use @AggregateWith on the test method parameter to apply your aggregator.

Aggregators help keep test methods clean when many inputs are involved.

Summary

Argument aggregation groups multiple inputs into one object for easier testing.

Use @ArgumentsAggregator and implement ArgumentsAggregator interface.

Apply aggregators with @AggregateWith in parameterized tests.