-
-
Notifications
You must be signed in to change notification settings - Fork 1.4k
/
MethodSource.java
135 lines (128 loc) · 6.73 KB
/
MethodSource.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
/*
* Copyright 2015-2023 the original author or authors.
*
* All rights reserved. This program and the accompanying materials are
* made available under the terms of the Eclipse Public License v2.0 which
* accompanies this distribution and is available at
*
* https://www.eclipse.org/legal/epl-v20.html
*/
package org.junit.jupiter.params.provider;
import static org.apiguardian.api.API.Status.STABLE;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import org.apiguardian.api.API;
import org.junit.jupiter.params.ParameterizedTest;
/**
* {@code @MethodSource} is an {@link ArgumentsSource} which provides access
* to values returned from {@linkplain #value() factory methods} of the class in
* which this annotation is declared or from static factory methods in external
* classes referenced by <em>fully qualified method name</em>.
*
* <p>Each factory method must generate a <em>stream</em> of <em>arguments</em>,
* and each set of "arguments" within the "stream" will be provided as the physical
* arguments for individual invocations of the annotated
* {@link ParameterizedTest @ParameterizedTest} method. Generally speaking this
* translates to a {@link java.util.stream.Stream Stream} of {@link Arguments}
* (i.e., {@code Stream<Arguments>}); however, the actual concrete return type
* can take on many forms. In this context, a "stream" is anything that JUnit
* can reliably convert into a {@code Stream}, such as
* {@link java.util.stream.Stream Stream},
* {@link java.util.stream.DoubleStream DoubleStream},
* {@link java.util.stream.LongStream LongStream},
* {@link java.util.stream.IntStream IntStream},
* {@link java.util.Collection Collection},
* {@link java.util.Iterator Iterator},
* {@link Iterable}, an array of objects, or an array of primitives. Each set of
* "arguments" within the "stream" can be supplied as an instance of
* {@link Arguments}, an array of objects (e.g., {@code Object[]},
* {@code String[]}, etc.), or a single <em>value</em> if the parameterized test
* method accepts a single argument.
*
* <p>Please note that a one-dimensional array of objects supplied as a set of
* "arguments" will be handled differently than other types of arguments.
* Specifically, all of the elements of a one-dimensional array of objects will
* be passed as individual physical arguments to the {@code @ParameterizedTest}
* method. This behavior can be seen in the table below for the
* {@code static Stream<Object[]> factory()} method: the {@code @ParameterizedTest}
* method accepts individual {@code String} and {@code int} arguments rather than
* a single {@code Object[]} array. In contrast, any multidimensional array
* supplied as a set of "arguments" will be passed as a single physical argument
* to the {@code @ParameterizedTest} method without modification. This behavior
* can be seen in the table below for the {@code static Stream<int[][]> factory()}
* and {@code static Stream<Object[][]> factory()} methods: the
* {@code @ParameterizedTest} methods for those factories accept individual
* {@code int[][]} and {@code Object[][]} arguments, respectively.
*
* <h2>Examples</h2>
*
* <p>The following table displays compatible method signatures for parameterized
* test methods and their corresponding factory methods.
*
* <table class="plain">
* <caption>Compatible method signatures and factory methods</caption>
* <tr><th>{@code @ParameterizedTest} method</th><th>Factory method</th></tr>
* <tr><td>{@code void test(int)}</td><td>{@code static int[] factory()}</td></tr>
* <tr><td>{@code void test(int)}</td><td>{@code static IntStream factory()}</td></tr>
* <tr><td>{@code void test(String)}</td><td>{@code static String[] factory()}</td></tr>
* <tr><td>{@code void test(String)}</td><td>{@code static List<String> factory()}</td></tr>
* <tr><td>{@code void test(String)}</td><td>{@code static Stream<String> factory()}</td></tr>
* <tr><td>{@code void test(String, String)}</td><td>{@code static String[][] factory()}</td></tr>
* <tr><td>{@code void test(String, int)}</td><td>{@code static Object[][] factory()}</td></tr>
* <tr><td>{@code void test(String, int)}</td><td>{@code static Stream<Object[]> factory()}</td></tr>
* <tr><td>{@code void test(String, int)}</td><td>{@code static Stream<Arguments> factory()}</td></tr>
* <tr><td>{@code void test(int[])}</td><td>{@code static int[][] factory()}</td></tr>
* <tr><td>{@code void test(int[])}</td><td>{@code static Stream<int[]> factory()}</td></tr>
* <tr><td>{@code void test(int[][])}</td><td>{@code static Stream<int[][]> factory()}</td></tr>
* <tr><td>{@code void test(Object[][])}</td><td>{@code static Stream<Object[][]> factory()}</td></tr>
* </table>
*
* <p>Factory methods within the test class must be {@code static} unless the
* {@link org.junit.jupiter.api.TestInstance.Lifecycle#PER_CLASS PER_CLASS}
* test instance lifecycle mode is used; whereas, factory methods in external
* classes must always be {@code static}.
*
* <p>Factory methods can declare parameters, which will be provided by registered
* implementations of {@link org.junit.jupiter.api.extension.ParameterResolver}.
*
* @since 5.0
* @see Arguments
* @see ArgumentsSource
* @see ParameterizedTest
* @see org.junit.jupiter.api.TestInstance
*/
@Target({ ElementType.ANNOTATION_TYPE, ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
@Documented
@API(status = STABLE, since = "5.7")
@ArgumentsSource(MethodArgumentsProvider.class)
public @interface MethodSource {
/**
* The names of factory methods within the test class or in external classes
* to use as sources for arguments.
*
* <p>Factory methods in external classes must be referenced by
* <em>fully-qualified method name</em> — for example,
* {@code "com.example.StringsProviders#blankStrings"} or
* {@code "com.example.TopLevelClass$NestedClass#classMethod"} for a factory
* method in a static nested class.
*
* <p>If a factory method accepts arguments that are provided by a
* {@link org.junit.jupiter.api.extension.ParameterResolver ParameterResolver},
* you can supply the formal parameter list in the qualified method name to
* disambiguate between overloaded variants of the factory method. For example,
* {@code "blankStrings(int)"} for a local qualified method name or
* {@code "com.example.StringsProviders#blankStrings(int)"} for a fully-qualified
* method name.
*
* <p>If no factory method names are declared, a method within the test class
* that has the same name as the test method will be used as the factory
* method by default.
*
* <p>For further information, see the {@linkplain MethodSource class-level Javadoc}.
*/
String[] value() default "";
}