Introduce `@BooleansSource` for use with `@ParameterizedTest`

[overwave]

Our team extensively utilizes JUnit Jupiter, particularly the @ParameterizedTest feature, to streamline our testing processes.

A common pattern we have observed involves the use of the @ValueSource annotation with the booleans attribute. Typically, this attribute is used to check whether our code behaves consistently when a feature flag is enabled versus when it is not. Consequently, the majority of our tests require a boolean array containing both true and false values.

To address this need, we have developed several custom annotations that utilize @ValueSource(booleans = {true, false}). However, we believe this pattern is prevalent enough to warrant inclusion in the standard library, reducing redundancy and simplifying test code across projects.

Would it be possible to consider adding a default boolean array {true, false} option for the @ValueSource annotation in future JUnit releases? We believe this addition would benefit many users by eliminating the need to create custom annotations for such a common use case.

I can implement the feature myself, it it would be any help to this.

Thank you for your consideration of this proposal. I look forward to any feedback or questions you might have.

Rodion.

[sbrannen]

Hi @overwave,

Thanks for the proposal, and congratulations on submitting your first issue for JUnit 5. 👍

Would it be possible to consider adding a default boolean array {true, false} option for the @ValueSource annotation in future JUnit releases?

No, that would not be possible. All of the attributes in @ValueSource are optional (i.e., empty arrays by default), so that developers can choose which attribute the wish to use.

As stated in the Javadoc:

Note, however, that only one of the supported types may be specified per @ValueSource declaration.

Providing a default value other than an empty array would therefore break all other use cases.

However, it would be possible to introduce a dedicated argument source that always provides boolean true and false. That would be somewhat analogous to the @NullAndEmptySource support I introduced in JUnit Jupiter 5.7.

I have therefore changed the title of this issue to reflect that, and we will discuss the proposal within the team.

Note, however, that @BooleansSource is merely intended as a possible name for such an annotation.

Regards,

Sam

[sbrannen]

Such a boolean source can be implemented as a composed annotation as follows.

@Target({ ElementType.ANNOTATION_TYPE, ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
@Documented
@ValueSource(booleans = {true, false})
public @interface BooleansSource {
}

And that can be used as follows.

@ParameterizedTest
@BooleansSource
void test(boolean flag) {
	assertTrue(flag || !flag);
}

[overwave]

Hi, @sbrannen! Thanks for the reply.

Yes, I understand the solution requires a new annotation, as both you and me proposed above.

The request is to add such annotation (as you've mentioned) to the JUnit library so the code for booleans could be more concise.

The JUnit also has this verbose alternative: https://github.com/search?q=repo%3Ajunit-team%2Fjunit5%20%40ValueSource(booleans%20%3D%20%7B%20true%2C%20false%20%7D)&type=code

I will understand if you decide to have more clean API rather than many shortcuts, but this could make our code (and I think someone's too) a little bit tidier.

Best regards,
Rodion