Start docs for @CartesianTest.MethodParameterSource

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 `@CartesianTest.MethodParameterSource`
 * https://github.com/petrandreev[Pёtr Andreev] added back support for NULL values to `@CartesianTestExtension` (#764 / #765)
 
 ==== 2022

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`.

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<String> 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[]