org.junit.jupiter.params.provider.MethodSource Maven / Gradle / Ivy
Show all versions of junit-jupiter-params Show documentation
/*
* Copyright 2015-2018 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
*
* http://www.eclipse.org/legal/epl-v20.html
*/
package org.junit.jupiter.params.provider;
import static org.apiguardian.api.API.Status.EXPERIMENTAL;
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 fully qualified method name.
*
* Each factory method must generate a stream of arguments,
* 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}); 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. The
* "arguments" within the stream can be supplied as an instance of
* {@link Arguments}, an array of objects (e.g., {@code Object[]}), or a single
* value if the parameterized test method accepts a single argument.
*
* Examples
*
* The following table displays compatible method signatures for parameterized
* test methods and their corresponding factory methods.
*
*
* {@code @ParameterizedTest} method Factory method {@code void test(int)} {@code static int[] factory()} {@code void test(int)} {@code static IntStream factory()} {@code void test(String)} {@code static String[] factory()} {@code void test(String)} {@code static List factory()} {@code void test(String)} {@code static Stream factory()} {@code void test(String, int)} {@code static Object[][] factory()} {@code void test(String, int)} {@code static Stream factory()} {@code void test(String, int)} {@code static Stream factory()}
*
* 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}. In any case, factory methods must not
* declare any parameters.
*
* @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 = EXPERIMENTAL, since = "5.0")
@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.
*
*
Factory methods in external classes must be referenced by fully
* qualified method name — for example,
* {@code com.example.StringsProviders#blankStrings}.
*
*
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.
*
*
For further information, see the {@linkplain MethodSource class-level JavaDoc}.
*/
String[] value() default "";
}