Writing a custom @Source for Parameterized Tests

Overview

While the built-in source annotations cover many use cases for @ParameterizedTest, it's possible to write a custom source, too. In this lesson, we implement a custom source for JSON-based data with the help of a third-party library, going through all the required steps to extend JUnit Jupiter with new functionality.

Writing a custom source only requires two steps: First, the source annotation itself, alongside its configuration. Furthermore, an ArgumentsProvider is needed to host the logic of processing the annotation's values into a meaningful stream of Arguments, which are then handed to the parameterized test method. In this example, a JSON structure is parsed into a JsonNode object, which the @ParameterizedTest declares as its method parameter.

The connection between the custom source annotation and its ArgumentsProvider gives a first look at the powerful extension model of the JUnit Jupiter API. Using the generic AnnotationConsumer interface, our JsonArgumentsProvider can receive a callback from the TestEngine while the annotation is processed at runtime. This allows us to read the values from the annotation.

Summary

• Custom source annotations utilize @ArgumentsSource and the implementation of an ArgumentsProvider
• The ArgumentsProvider exposes the data for a @ParameterizedTest through a stream of Arguments
• The connection between the provider and annotation can be achieved through AnnotationConsumer<T>