/*
 * Copyright 2015-2019 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.api;

import static org.apiguardian.api.API.Status.MAINTAINED;

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.platform.commons.annotation.Testable;

@TestFactory is used to signal that the annotated method is a test factory method.
In contrast to @Test methods, a test factory is not itself a test case but rather a factory for test cases. 
@TestFactory methods must not be private or static and must return a Stream, Collection, Iterable, Iterator, or array of DynamicNode instances. Supported subclasses of DynamicNode include DynamicContainer and DynamicTest. Dynamic tests will be executed lazily,
enabling dynamic and even non-deterministic generation of test cases.
Any Stream returned by a @TestFactory will be properly closed by calling stream.close(), making it safe to use a resource such as Files.lines() as the initial source of the stream. 
@TestFactory methods may optionally declare parameters to be resolved by 
ParameterResolvers. 
Test Execution Order
By default, test methods will be ordered using an algorithm that is
deterministic but intentionally nonobvious. This ensures that subsequent runs
of a test suite execute test methods in the same order, thereby allowing for
repeatable builds. In this context, a test method is any instance method that is directly annotated or meta-annotated with @Test, @RepeatedTest, @ParameterizedTest, @TestFactory, or @TestTemplate. 
Although true unit tests typically should not rely on the order
in which they are executed, there are times when it is necessary to enforce
a specific test method execution order — for example, when writing
integration tests or functional tests where the sequence of the tests is important, especially in conjunction with @TestInstance(Lifecycle.PER_CLASS). 
To control the order in which test methods are executed, annotate your test class or test interface with @TestMethodOrder and specify the desired MethodOrderer implementation. 
See Also:
Test
DynamicNode
DynamicTest
DynamicContainer
Since:
5.0/**
 * {@code @TestFactory} is used to signal that the annotated method is a
 * <em>test factory</em> method.
 *
 * <p>In contrast to {@link Test @Test} methods, a test factory is not itself
 * a test case but rather a factory for test cases.
 *
 * <p>{@code @TestFactory} methods must not be {@code private} or {@code static}
 * and must return a {@code Stream}, {@code Collection}, {@code Iterable},
 * {@code Iterator}, or array of {@link DynamicNode} instances. Supported
 * subclasses of {@code DynamicNode} include {@link DynamicContainer} and
 * {@link DynamicTest}. <em>Dynamic tests</em> will be executed lazily,
 * enabling dynamic and even non-deterministic generation of test cases.
 *
 * <p>Any {@code Stream} returned by a {@code @TestFactory} will be properly
 * closed by calling {@code stream.close()}, making it safe to use a resource
 * such as {@code Files.lines()} as the initial source of the stream.
 *
 * <p>{@code @TestFactory} methods may optionally declare parameters to be
 * resolved by {@link org.junit.jupiter.api.extension.ParameterResolver
 * ParameterResolvers}.
 *
 * <h3>Test Execution Order</h3>
 *
 * <p>By default, test methods will be ordered using an algorithm that is
 * deterministic but intentionally nonobvious. This ensures that subsequent runs
 * of a test suite execute test methods in the same order, thereby allowing for
 * repeatable builds. In this context, a <em>test method</em> is any instance
 * method that is directly annotated or meta-annotated with {@code @Test},
 * {@code @RepeatedTest}, {@code @ParameterizedTest}, {@code @TestFactory}, or
 * {@code @TestTemplate}.
 *
 * <p>Although true <em>unit tests</em> typically should not rely on the order
 * in which they are executed, there are times when it is necessary to enforce
 * a specific test method execution order &mdash; for example, when writing
 * <em>integration tests</em> or <em>functional tests</em> where the sequence of
 * the tests is important, especially in conjunction with
 * {@link TestInstance @TestInstance(Lifecycle.PER_CLASS)}.
 *
 * <p>To control the order in which test methods are executed, annotate your
 * test class or test interface with {@link TestMethodOrder @TestMethodOrder}
 * and specify the desired {@link MethodOrderer} implementation.
 *
 * @since 5.0
 * @see Test
 * @see DynamicNode
 * @see DynamicTest
 * @see DynamicContainer
 */
@Target({ ElementType.ANNOTATION_TYPE, ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
@Documented
@API(status = MAINTAINED, since = "5.3")
@Testable
public @interface TestFactory {
}