From 37790c61168ea17b2431430c2403a7fb087c43d0 Mon Sep 17 00:00:00 2001 From: Jason Penilla <11360596+jpenilla@users.noreply.github.com> Date: Thu, 21 Dec 2023 12:13:40 -0800 Subject: [PATCH] Start docs for `@CartesianTest.MethodParameterSource` --- README.adoc | 1 + docs/cartesian-product.adoc | 36 ++++++++++++++++++- .../cartesian/CartesianTestExtensionDemo.java | 18 ++++++++++ 3 files changed, 54 insertions(+), 1 deletion(-) diff --git a/README.adoc b/README.adoc index aa5bc00ea..13471e759 100644 --- a/README.adoc +++ b/README.adoc @@ -125,6 +125,7 @@ The least we can do is to thank them and list some of their accomplishments here * https://github.com/eeverman[Eric Everman] added `@RestoreSystemProperties` and `@RestoreEnvironmentVariables` annotations to the https://junit-pioneer.org/docs/system-properties/[System Properties] and https://junit-pioneer.org/docs/environment-variables/[Environment Variables] extensions (#574 / #700) * https://github.com/meredrica[Florian Westreicher] contributed to the JSON argument source extension (#704 / #724) * https://github.com/IlyasYOY[Ilya Ilyinykh] found unused demo tests (#791) +* https://github.com/jpenilla[Jason Penilla] added https://junit-pioneer.org/docs/cartesian-product/#cartesiantest-methodparametersource[`@CartesianTest.MethodParameterSource`] (#796 / #797) * https://github.com/petrandreev[Pёtr Andreev] added back support for NULL values to `@CartesianTestExtension` (#764 / #765) ==== 2022 diff --git a/docs/cartesian-product.adoc b/docs/cartesian-product.adoc index ec25e9927..d7d51ba8a 100644 --- a/docs/cartesian-product.adoc +++ b/docs/cartesian-product.adoc @@ -197,6 +197,40 @@ To demonstrate with a table: For more information, please see the link:/docs/range-sources[separate documentation about range sources]. +=== `@CartesianTest.MethodParameterSource` + +`@CartesianTest.MethodParameterSource` can be used to specify factory methods that supply arguments for a single parameter of a `@CartesianTest`. + +Similar to https://junit.org/junit5/docs/current/user-guide/#writing-tests-parameterized-tests-sources-MethodSource[JUnit's `@MethodSource`], methods can be specified with their simple name when in the same class, (i.e. `methodName`), or their fully qualified name otherwise (i.e. `com.example.Class#methodName`). +Methods must be static, except for methods in the same class when the test class is annotated with `@TestInstance(Lifecycle.PER_CLASS)`. +Methods may return a `Stream` (including the primitive-specialized variants), `Iterable`, `Iterator`, or array of values. + +Let's look at an example. + +[source,java,indent=0] +---- +include::{demo}[tag=cartesian_parameter_source_basic] +---- + +In this example, the test method would be invoked 12 times. To demonstrate with a table: + +|=== +| # of test | value of `name` | value of `points` + +| 1st test | "John" | 12 +| 2nd test | "John" | 18 +| 3rd test | "John" | 22 +| 4th test | "Annie" | 12 +| 5th test | "Annie" | 18 +| 6th test | "Annie" | 22 +| 7th test | "Bob" | 12 +| 8th test | "Bob" | 18 +| 9th test | "Bob" | 22 +| 10th test | "Sofia" | 12 +| 11th test | "Sofia" | 18 +| 12th test | "Sofia" | 22 +|=== + == Defining arguments with factories You can annotate your test method to supply arguments to all parameters simultaneously. @@ -205,7 +239,7 @@ You can annotate your test method to supply arguments to all parameters simultan `@CartesianTest.MethodFactory` can be used to name a factory method that supplies your arguments. The `value` annotation parameter is mandatory. -Just like with JUnit's `@MethodSource`, you can specify the factory method with its fully-qualified name (including the class), e.g. `com.example.Class#factory`. +Just like with https://junit.org/junit5/docs/current/user-guide/#writing-tests-parameterized-tests-sources-MethodSource[JUnit's `@MethodSource`], you can specify the factory method with its fully-qualified name (including the class), e.g. `com.example.Class#factory`. This method must return `ArgumentSets`. `ArgumentSets` is a helper class, specifically for creating sets for `@CartesianTest`. diff --git a/src/demo/java/org/junitpioneer/jupiter/cartesian/CartesianTestExtensionDemo.java b/src/demo/java/org/junitpioneer/jupiter/cartesian/CartesianTestExtensionDemo.java index d747b2c54..ee342a412 100644 --- a/src/demo/java/org/junitpioneer/jupiter/cartesian/CartesianTestExtensionDemo.java +++ b/src/demo/java/org/junitpioneer/jupiter/cartesian/CartesianTestExtensionDemo.java @@ -23,9 +23,11 @@ import java.time.temporal.TemporalUnit; import java.util.Arrays; import java.util.EnumSet; +import java.util.List; import java.util.Objects; import java.util.concurrent.TimeUnit; import java.util.function.Predicate; +import java.util.stream.IntStream; import java.util.stream.Stream; import org.junit.jupiter.api.DisplayName; @@ -35,6 +37,7 @@ import org.junit.jupiter.api.TestReporter; import org.junit.jupiter.api.extension.ExtensionContext; import org.junitpioneer.jupiter.cartesian.CartesianTest.Enum; +import org.junitpioneer.jupiter.cartesian.CartesianTest.MethodParameterSource; import org.junitpioneer.jupiter.cartesian.CartesianTest.Values; import org.junitpioneer.jupiter.params.LongRangeSource; import org.junitpioneer.jupiter.params.ShortRangeSource; @@ -178,6 +181,21 @@ static ArgumentSets stringIntFactory() { } // end::cartesian_argument_sets_reuse[] + // tag::cartesian_parameter_source_basic[] + @CartesianTest + void testScores(@MethodParameterSource("names") String name, @MethodParameterSource("points") int points) { + // test code + } + + static List names() { + return List.of("John", "Annie", "Bob", "Sofia"); + } + + static IntStream points() { + return IntStream.of(12, 18, 22); + } + // end::cartesian_parameter_source_basic[] + static class MisconfiguredExamples { // tag::cartesian_bad_examples[]