Introduce support for parameterized classes

[marcphilipp]

Overview

This PR introduces @ParameterizedClass which builds on @ContainerTemplate and allows declaring a top-level or @Nested test class as a parameterized container to be invoked multiple times with different arguments. The same @...Source annotations as for @ParameterizedTest may be used to provide arguments via constructor or field injection.

Resolves #878.

---

I hereby agree to the terms of the JUnit Contributor License Agreement.

---

Definition of Done

• There are no TODOs left in the code
• Method preconditions are checked and documented in the method's Javadoc
• Coding conventions (e.g. for logging) have been followed
• Change is covered by automated tests including corner cases, errors, and exception handling
• Public API has Javadoc and @API annotations
• Change is documented in the User Guide and Release Notes

[georgberky]

This works very well for me. My main use case is to test multiple implementations of the same interface with the same suite of tests:

@ParameterizedContainer
@MethodSource("instances")
public class BranchByAbstractionTest {

    public static Stream<Arguments> instances() {
        return Stream.of(
                new FirstImplementation(),
                new SecondImplementation()
        ).map(Arguments::arguments);
    }

    private final Abstraction abstraction;

    public BranchByAbstractionTest(Abstraction abstraction) {
        this.abstraction = abstraction;
    }

    @Test
    void somethingAboutTheAbstraction() {
        assertEquals(23, abstraction.doSomething());
    }
}

I also love that constructor injection works 😍 . Being able to use the same arguments providers is really helpful.

[georgberky]

Maybe for future improvements:

Would it be possible and an improvement for readability to have the @MethodSource directly on the contrustor/field?

The same argument would probably be valid for regular parameterized tests, i.e. should the presence of an argument provider on a class/field/method be sufficient to make it parameterized without requiring the additional @ParameterizedTest or @ParameterizedContainer? For test methods we could keep the usual @Test then.

[marcphilipp]

This works very well for me

I'm glad to hear it! 🙂

My main use case is to test multiple implementations of the same interface with the same suite of tests

If you have a single parameter, you don't have to wrap the arguments in Arguments but can just write:

@ParameterizedClass
@MethodSource("instances")
class BranchByAbstractionTest {

    static List<Abstraction> instances() {
        return List.of(
                new FirstImplementation(),
                new SecondImplementation()
        );
    }

    private final Abstraction abstraction;

    BranchByAbstractionTest(Abstraction abstraction) {
        this.abstraction = abstraction;
    }

    @Test
    void somethingAboutTheAbstraction() {
        assertEquals(23, abstraction.doSomething());
    }
}

Or using @FieldSource:

@ParameterizedClass
@FieldSource("instances")
class BranchByAbstractionTest {

    static final List<Abstraction> instances = List.of(
            new FirstImplementation(),
            new SecondImplementation()
    );

    private final Abstraction abstraction;

    BranchByAbstractionTest(Abstraction abstraction) {
        this.abstraction = abstraction;
    }

    @Test
    void somethingAboutTheAbstraction() {
        assertEquals(23, abstraction.doSomething());
    }
}

If you can use Java records:

@ParameterizedClass
@FieldSource("instances")
record BranchByAbstractionTest(Abstraction abstraction) {

    static final List<Abstraction> instances = List.of(
            new FirstImplementation(),
            new SecondImplementation()
    );

    @Test
    void somethingAboutTheAbstraction() {
        assertEquals(23, abstraction.doSomething());
    }
}

Would it be possible and an improvement for readability to have the @MethodSource directly on the constructor/field?

The same argument would probably be valid for regular parameterized tests, i.e. should the presence of an argument provider on a class/field/method be sufficient to make it parameterized without requiring the additional @ParameterizedTest or @ParameterizedContainer? For test methods we could keep the usual @Test then.

I think we would still require @ParameterizedTest or @ParameterizedClass for clarity. But auto-discovering @MethodSource methods for @ParameterizedClass sounds interesting, maybe via a new @Arguments annotation on fields or methods. Technically, this could be achieved by implementing a new ArgumentsProvider that checks for those fields and registering it on the @ParameterizedClass composed annotation.

[marcphilipp]

Team decision: Merge after renaming the annotation to @ParameterizedClass. Make it @Inherited in a subsequent PR.

[georgberky]

Thanks, Marc! I haven't seen @FieldSource before. That's really cool 🙏🏻 .

[vlsi]

Many thanks for @ParameterizedClass!

I've migrated the remaining junit4 tests in pgjdbc to @ParameterizedClass, so junit4 is no longer on the classpath: pgjdbc/pgjdbc#3652

[marcphilipp]

@vlsi I'm glad to hear it! 🎉