Top Description Inners Fields Constructors Methods
org.junit.platform.launcher

public Class TestPlan

extends Object
Class Inheritance
Known Direct Subclasses
org.junit.platform.launcher.core.InternalTestPlan
Annotations
@API
status:STABLE
since:1.0
Static Imports
java.util.Collections.emptySet, .Collections.synchronizedSet, .Collections.unmodifiableSet, org.apiguardian.api.API.Status.DEPRECATED, .API.Status.INTERNAL, .API.Status.MAINTAINED, .API.Status.STABLE
TestPlan describes the tree of tests and containers as discovered by a Launcher.

Tests and containers are represented by TestIdentifier instances. The complete set of identifiers comprises a tree-like structure. However, each identifier only stores the unique ID of its parent. This class provides a number of helpful methods to retrieve the parent, children, and descendants of an identifier.

While the contained instances of TestIdentifier are immutable, instances of this class contain mutable state. For example, when a dynamic test is registered at runtime, it is added to the original test plan and reported to TestExecutionListener implementations.

This class is not intended to be extended by clients.

Since
1.0
See Also
Launcher, TestExecutionListener

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static interface
TestPlan.Visitor

Visitor for TestIdentifiers in a TestPlan.

Field Summary

Modifier and TypeField and Description
private final Map<UniqueId, TestIdentifier>
allIdentifiers

private final Map<UniqueId, Set<TestIdentifier>>
children

private final ConfigurationParameters
configurationParameters

private final boolean
containsTests

private final OutputDirectoryCreator
outputDirectoryCreator

private final Set<TestIdentifier>
roots

Constructor Summary

AccessConstructor and Description
protected
TestPlan(boolean containsTests, ConfigurationParameters configurationParameters, OutputDirectoryCreator outputDirectoryCreator)

Method Summary

Modifier and TypeMethod and Description
public void
accept(TestPlan.Visitor
the visitor to accept; never null
visitor)

Accept the supplied Visitor for a depth-first traversal of the test plan.

private void
accept(TestPlan.Visitor visitor, TestIdentifier testIdentifier)

public void
addInternal(TestIdentifier testIdentifier)

public boolean

Returns:

true if this test plan contains tests
containsTests()

Return whether this test plan contains any tests.

public long

Returns:

the number of identifiers that satisfy the supplied predicate
countTestIdentifiers(Predicate<? super TestIdentifier>
a predicate which returns true for identifiers to be counted; never null
predicate)

Count all TestIdentifiers that satisfy the given predicate.

public static TestPlan

Returns:

a new test plan
from(boolean
whether the test plan contains tests
containsTests, Collection<TestDescriptor>
the engine test descriptors from which the test plan should be created; never null
engineDescriptors, ConfigurationParameters
the ConfigurationParameters for this test plan; never null
configurationParameters, OutputDirectoryCreator
the OutputDirectoryProvider for this test plan; never null
outputDirectoryCreator)

Construct a new TestPlan from the supplied collection of TestDescriptors.

public Set<TestIdentifier>

Returns:

an unmodifiable set of the parent's children, potentially empty
getChildren(TestIdentifier
the identifier to look up the children for; never null
parent)

Get the children of the supplied TestIdentifier.

public Set<TestIdentifier>

Returns:

an unmodifiable set of the parent's children, potentially empty
getChildren(UniqueId
the unique ID to look up the children for; never null
parentId)

Get the children of the supplied unique ID.

public ConfigurationParameters

Returns:

the configuration parameters; never null
getConfigurationParameters()

Get the ConfigurationParameters for this test plan.

public Set<TestIdentifier>

Returns:

an unmodifiable set of the parent's descendants, potentially empty
getDescendants(TestIdentifier
the identifier to look up the descendants for; never null
parent)

Get all descendants of the supplied TestIdentifier (i.e., all of its children and their children, recursively).

public OutputDirectoryCreator

Returns:

the output directory creator; never null
getOutputDirectoryCreator()

Get the OutputDirectoryCreator for this test plan.

public OutputDirectoryProvider

Returns:

the output directory provider; never null
getOutputDirectoryProvider()
Deprecated for removal since 1.14. Please use getOutputDirectoryCreator() instead

Get the org.junit.platform.engine.reporting.OutputDirectoryProvider for this test plan.

public Optional<TestIdentifier>

Returns:

an Optional containing the parent, if present
getParent(TestIdentifier
the identifier to look up the parent for; never null
child)

Get the parent of the supplied TestIdentifier.

public Set<TestIdentifier>

Returns:

an unmodifiable set of the root identifiers
getRoots()

Get the root TestIdentifiers for this test plan.

public TestIdentifier

Returns:

the identifier with the supplied unique ID; never null
getTestIdentifier(String
the unique ID to look up the identifier for; never null or blank
uniqueId)
Deprecated since 1.10. Use getTestIdentifier(UniqueId) instead.

Get the TestIdentifier with the supplied unique ID.

public TestIdentifier

Returns:

the identifier with the supplied unique ID; never null
getTestIdentifier(UniqueId
the unique ID to look up the identifier for; never null
uniqueId)

Get the TestIdentifier with the supplied unique ID.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

allIdentifiersback to summary
private final Map<UniqueId, TestIdentifier> allIdentifiers
childrenback to summary
private final Map<UniqueId, Set<TestIdentifier>> children
configurationParametersback to summary
private final ConfigurationParameters configurationParameters
containsTestsback to summary
private final boolean containsTests
outputDirectoryCreatorback to summary
private final OutputDirectoryCreator outputDirectoryCreator
rootsback to summary
private final Set<TestIdentifier> roots

Constructor Detail

TestPlanback to summary
protected TestPlan(boolean containsTests, ConfigurationParameters configurationParameters, OutputDirectoryCreator outputDirectoryCreator)
Annotations
@API
status:INTERNAL
since:1.4

Method Detail

acceptback to summary
public void accept(TestPlan.Visitor visitor)

Accept the supplied Visitor for a depth-first traversal of the test plan.

Parameters
visitor:TestPlan.Visitor

the visitor to accept; never null

Annotations
@API
status:MAINTAINED
since:1.13.3
Since
1.10
acceptback to summary
private void accept(TestPlan.Visitor visitor, TestIdentifier testIdentifier)
addInternalback to summary
public void addInternal(TestIdentifier testIdentifier)
Annotations
@API
status:INTERNAL
since:1.8
containsTestsback to summary
public boolean containsTests()

Return whether this test plan contains any tests.

A test plan contains tests, if at least one of the contained engine descriptors contains tests.

Returns:boolean

true if this test plan contains tests

See Also
TestDescriptor#containsTests(TestDescriptor)
countTestIdentifiersback to summary
public long countTestIdentifiers(Predicate<? super TestIdentifier> predicate)

Count all TestIdentifiers that satisfy the given predicate.

Parameters
predicate:Predicate<? super TestIdentifier>

a predicate which returns true for identifiers to be counted; never null

Returns:long

the number of identifiers that satisfy the supplied predicate

fromback to summary
public static TestPlan from(boolean containsTests, Collection<TestDescriptor> engineDescriptors, ConfigurationParameters configurationParameters, OutputDirectoryCreator outputDirectoryCreator)

Construct a new TestPlan from the supplied collection of TestDescriptors.

Each supplied TestDescriptor is expected to be a descriptor for a TestEngine.

Parameters
containsTests:boolean

whether the test plan contains tests

engineDescriptors:Collection<TestDescriptor>

the engine test descriptors from which the test plan should be created; never null

configurationParameters:ConfigurationParameters

the ConfigurationParameters for this test plan; never null

outputDirectoryCreator:OutputDirectoryCreator

the OutputDirectoryProvider for this test plan; never null

Returns:TestPlan

a new test plan

Annotations
@API
status:INTERNAL
since:1.14
getChildrenback to summary
public Set<TestIdentifier> getChildren(TestIdentifier parent)

Get the children of the supplied TestIdentifier.

Parameters
parent:TestIdentifier

the identifier to look up the children for; never null

Returns:Set<TestIdentifier>

an unmodifiable set of the parent's children, potentially empty

See Also
getChildren(UniqueId)
getChildrenback to summary
public Set<TestIdentifier> getChildren(UniqueId parentId)

Get the children of the supplied unique ID.

Parameters
parentId:UniqueId

the unique ID to look up the children for; never null

Returns:Set<TestIdentifier>

an unmodifiable set of the parent's children, potentially empty

Annotations
@API
status:MAINTAINED
since:1.10
See Also
getChildren(TestIdentifier)
getConfigurationParametersback to summary
public ConfigurationParameters getConfigurationParameters()

Get the ConfigurationParameters for this test plan.

Returns:ConfigurationParameters

the configuration parameters; never null

Annotations
@API
status:MAINTAINED
since:1.8
Since
1.8
getDescendantsback to summary
public Set<TestIdentifier> getDescendants(TestIdentifier parent)

Get all descendants of the supplied TestIdentifier (i.e., all of its children and their children, recursively).

Parameters
parent:TestIdentifier

the identifier to look up the descendants for; never null

Returns:Set<TestIdentifier>

an unmodifiable set of the parent's descendants, potentially empty

getOutputDirectoryCreatorback to summary
public OutputDirectoryCreator getOutputDirectoryCreator()

Get the OutputDirectoryCreator for this test plan.

Returns:OutputDirectoryCreator

the output directory creator; never null

Annotations
@API
status:MAINTAINED
since:1.14
Since
1.14
getOutputDirectoryProviderback to summary
public OutputDirectoryProvider getOutputDirectoryProvider()

Deprecated

for removal since 1.14.

Please use getOutputDirectoryCreator() instead

Get the org.junit.platform.engine.reporting.OutputDirectoryProvider for this test plan.

Returns:OutputDirectoryProvider

the output directory provider; never null

Annotations
@SuppressWarnings:removal
@API
status:DEPRECATED
since:1.14
@Deprecated
since:1.14
forRemoval:true
Since
1.12
getParentback to summary
public Optional<TestIdentifier> getParent(TestIdentifier child)

Get the parent of the supplied TestIdentifier.

Parameters
child:TestIdentifier

the identifier to look up the parent for; never null

Returns:Optional<TestIdentifier>

an Optional containing the parent, if present

getRootsback to summary
public Set<TestIdentifier> getRoots()

Get the root TestIdentifiers for this test plan.

Returns:Set<TestIdentifier>

an unmodifiable set of the root identifiers

getTestIdentifierback to summary
public TestIdentifier getTestIdentifier(String uniqueId) throws PreconditionViolationException

Deprecated

since 1.10.

Use getTestIdentifier(UniqueId) instead.

Get the TestIdentifier with the supplied unique ID.

Parameters
uniqueId:String

the unique ID to look up the identifier for; never null or blank

Returns:TestIdentifier

the identifier with the supplied unique ID; never null

Annotations
@API
status:DEPRECATED
since:1.10
consumers:Gradle
@Deprecated
since:1.10
Exceptions
PreconditionViolationException:
if no TestIdentifier with the supplied unique ID is present in this test plan
getTestIdentifierback to summary
public TestIdentifier getTestIdentifier(UniqueId uniqueId)

Get the TestIdentifier with the supplied unique ID.

Parameters
uniqueId:UniqueId

the unique ID to look up the identifier for; never null

Returns:TestIdentifier

the identifier with the supplied unique ID; never null

Annotations
@API
status:MAINTAINED
since:1.10
Exceptions
PreconditionViolationException:
if no TestIdentifier with the supplied unique ID is present in this test plan
org.junit.platform.launcher back to summary

public Interface TestPlan.Visitor

Annotations
@API
status:MAINTAINED
since:1.13.3
Visitor for TestIdentifiers in a TestPlan.
Since
1.10

Method Summary

Modifier and TypeMethod and Description
public default void
postVisitContainer(TestIdentifier testIdentifier)

Called after visiting a container.

public default void
preVisitContainer(TestIdentifier testIdentifier)

Called before visiting a container.

public default void
visit(TestIdentifier testIdentifier)

Called for all test identifiers regardless of their type.

Method Detail

postVisitContainerback to summary
public default void postVisitContainer(TestIdentifier testIdentifier)

Called after visiting a container.

See Also
TestIdentifier#isContainer()
preVisitContainerback to summary
public default void preVisitContainer(TestIdentifier testIdentifier)

Called before visiting a container.

See Also
TestIdentifier#isContainer()
visitback to summary
public default void visit(TestIdentifier testIdentifier)

Called for all test identifiers regardless of their type.