• Home
• org.junit.jupiter
• junit-jupiter-params
• 5.11.0-M2
• source code
• MethodSource.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

org.junit.jupiter.params.provider.MethodSource Maven / Gradle / Ivy

/*
 * Copyright 2015-2024 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.Repeatable;
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 a {@linkplain Repeatable repeatable}
 * {@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. 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 value if the parameterized test
 * method accepts a single argument.
 *
 * 
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 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 factory()}
 * and {@code static Stream factory()} methods: the
 * {@code @ParameterizedTest} methods for those factories accept individual
 * {@code int[][]} and {@code Object[][]} arguments, respectively.
 *
 * 
Examples
 *
 * 
The following table displays compatible method signatures for parameterized
 * test methods and their corresponding factory methods.
 *
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
Compatible method signatures and 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, String)}
{@code static String[][] 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()}
{@code void test(int[])}
{@code static int[][] factory()}
{@code void test(int[])}
{@code static Stream factory()}
{@code void test(int[][])}
{@code static Stream factory()}
{@code void test(Object[][])}
{@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}.
 *
 * 
Factory methods can declare parameters, which will be provided by registered
 * implementations of {@link org.junit.jupiter.api.extension.ParameterResolver}.
 *
 * @since 5.0
 * @see FieldSource
 * @see Arguments
 * @see ArgumentsSource
 * @see ParameterizedTest
 * @see org.junit.jupiter.api.TestInstance
 */
@Target({ ElementType.ANNOTATION_TYPE, ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Repeatable(MethodSources.class)
@API(status = STABLE, since = "5.7")
@ArgumentsSource(MethodArgumentsProvider.class)
@SuppressWarnings("exports")
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"} or
	 * {@code "com.example.TopLevelClass$NestedClass#classMethod"} for a factory
	 * method in a static nested class.
	 *
	 * 
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.
	 *
	 * 
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 "";

}