Add List-based support to Arguments API

[mariokhoury4]

Overview

This PR adds List-based support to the Arguments API for parameterized tests.

New additions:

• Arguments.of(List<@Nullable Object>)
• Arguments.arguments(List<@Nullable Object>) (alias)
• Arguments.argumentSet(String, List<@Nullable Object>)
• Arguments.toList() — returns a mutable List<@Nullable Object>

These additions make it easier to dynamically build arguments from collections when using @ParameterizedTest.

All additions are tested in ArgumentsTests.java.

Fixes #4535

---

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

[marcphilipp]

Please move these next to the other static factory methods above.

[mariokhoury4]

Thanks for the suggestion! I'll move the method next to the other static factory methods to keep things consistent.

[vlsi]

Just wondering: have you considered Iterable<? extends @Nullable Object> rather than using a plain List?

---

Based on my experience with checkerframework's @Nullable, I would suggest List<? extends @Nullable Object> rather than List<Object>.

I've asked jspecify to clarify the documentation anyways: jspecify/jspecify#748

At the same time, it would be nice to add tests that pass something like List<String> to the newly added methods.

For instance, from(Files.readAllLines("path")). I guess the code won't compile if the method uses List<Object> signatures.

[vlsi]

One more thing: List<?> is a good enough replacement for List<? extends @Nullable Object>. In this case, the method should probably have a signature like from(Iterable<?>)

[marcphilipp]

One more thing: List<?> is a good enough replacement for List<? extends @Nullable Object>

I didn't know that but sounds like you're right, according to the spec:

If an unbounded wildcard appears in a null-marked scope, then it has a single upper bound whose base type is Object and whose nullness operator is UNION_NULL.

Therefore, I think using List<?> as method parameter and return type of toList() makes sense.

Just wondering: have you considered Iterable rather than using a plain List?

The use case we're addressing here is constructing new Arguments instances from existing ones so I don't think that flexibility is needed. Moreover, we could introduce it later, if necessary.

[vlsi]

@marcphilipp , sorry for asking the same thing twice, however, could you please clarify why do you mean Arguments.from(List), Arguments argumentsFrom(List), and ArgumentSet argumentSetFrom(String name, List) relate to "from existing ones"?

To me the second case of #4535 sounds like a natural case for using argumentsFrom(Iterable<?>) rather than a pure List.

2. An Arguments can only be created from an array, not a collection.

I've no issues if Arguments.toList returns List. However, I believe on the consumption side, Arguments.from should accept Iterable so the users could supply various types of collections they have.

Of course, it would be great if Java had something like IterableWithPredefinedIterationOrder, so users don't accidentally pass HashSet and get their arguments shuffled.

---

If you mean you force List so the users do not supply collections like Stream...parallel()... and somehow complain "the order of arguments is wrong sometimes"? If that is the case, it is probably worth documenting as "this List<?> could have been Iterable<?>" is a typical code review case.

[marcphilipp]

sorry for asking the same thing twice, however, could you please clarify why do you mean Arguments.from(List), Arguments argumentsFrom(List), and ArgumentSet argumentSetFrom(String name, List) relate to "from existing ones"?

The use case we're trying to address here is to go from an existing Arguments instance to a new one without re-inventing a new collection API.

I've no issues if Arguments.toList returns List. However, I believe on the consumption side, Arguments.from should accept Iterable so the users could supply various types of collections they have.

We'll discuss that in one of our next team calls.

[marcphilipp]

Team decision: Use Iterable<?> as parameter types and documentation that the iteration order should be deterministic since it will be converted to an array.

[mpkorstanje]

@mariokhoury4 thanks for working on this! Unfortunately we took a long time before we could discuss this and imagine you'll have moved on. So I'll pick up the remaining changes and do some polishing to wrap this up in the next few weeks.

[mpkorstanje]

Therefore, I think using List<?> as method parameter and return type of toList() makes sense.

Using wildcards in the method parameter is fine, but for the return type of toList(), List<@Nullable Object> is preferable. List<?> can't be passed to function that expect a List<? extends T>.

[testlens-app]

🔎 No tests executed 🔎

🏷️ Commit: 55720a1
▶️ Tests: 0 executed
⚪️ Checks: 1/1 completed