org.junit.jupiter.api.DynamicContainer Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of junit-jupiter-api Show documentation
Module "junit-jupiter-api" of JUnit 5.
The newest version!
/*
 * 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.api;

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

import java.net.URI;
import java.util.stream.Stream;
import java.util.stream.StreamSupport;

import org.apiguardian.api.API;
import org.junit.platform.commons.util.Preconditions;

/**
 * A {@code DynamicContainer} is a container generated at runtime.
 *
 * It is composed of a {@linkplain DynamicNode#getDisplayName display name}
 * and an {@link Iterable} or {@link Stream} of {@link DynamicNode DynamicNodes}.
 *
 * 
Instances of {@code DynamicContainer} must be generated by factory methods
 * annotated with {@link TestFactory @TestFactory}.
 *
 * @since 5.0
 * @see #dynamicContainer(String, Iterable)
 * @see #dynamicContainer(String, Stream)
 * @see TestFactory
 * @see DynamicTest
 */
@API(status = MAINTAINED, since = "5.3")
public class DynamicContainer extends DynamicNode {

	/**
	 * Factory for creating a new {@code DynamicContainer} for the supplied display
	 * name and collection of dynamic nodes.
	 *
	 * 
The collection of dynamic nodes must not contain {@code null} elements.
	 *
	 * @param displayName the display name for the dynamic container; never
	 * {@code null} or blank
	 * @param dynamicNodes collection of dynamic nodes to execute;
	 * never {@code null}
	 * @see #dynamicContainer(String, Stream)
	 */
	public static DynamicContainer dynamicContainer(String displayName, Iterable dynamicNodes) {
		return dynamicContainer(displayName, null, StreamSupport.stream(dynamicNodes.spliterator(), false));
	}

	/**
	 * Factory for creating a new {@code DynamicContainer} for the supplied display
	 * name and stream of dynamic nodes.
	 *
	 * 
The stream of dynamic nodes must not contain {@code null} elements.
	 *
	 * @param displayName the display name for the dynamic container; never
	 * {@code null} or blank
	 * @param dynamicNodes stream of dynamic nodes to execute;
	 * never {@code null}
	 * @see #dynamicContainer(String, Iterable)
	 */
	public static DynamicContainer dynamicContainer(String displayName, Stream dynamicNodes) {
		return dynamicContainer(displayName, null, dynamicNodes);
	}

	/**
	 * Factory for creating a new {@code DynamicContainer} for the supplied display
	 * name, custom test source {@link URI}, and stream of dynamic nodes.
	 *
	 * The stream of dynamic nodes must not contain {@code null} elements.
	 *
	 * @param displayName the display name for the dynamic container; never
	 * {@code null} or blank
	 * @param testSourceUri a custom test source URI for the dynamic container;
	 * may be {@code null} if the framework should generate the test source based
	 * on the {@code @TestFactory} method
	 * @param dynamicNodes stream of dynamic nodes to execute; never {@code null}
	 * @since 5.3
	 * @see #dynamicContainer(String, Iterable)
	 */
	public static DynamicContainer dynamicContainer(String displayName, URI testSourceUri,
			Stream dynamicNodes) {

		return new DynamicContainer(displayName, testSourceUri, dynamicNodes);
	}

	private final Stream children;

	private DynamicContainer(String displayName, URI testSourceUri, Stream children) {
		super(displayName, testSourceUri);
		Preconditions.notNull(children, "children must not be null");
		this.children = children;
	}

	/**
	 * Get the {@link Stream} of {@link DynamicNode DynamicNodes} associated
	 * with this {@code DynamicContainer}.
	 */
	public Stream getChildren() {
		return children;
	}

}