org.junit.platform.engine

Interface TestDescriptor

All Known Implementing Classes:

AbstractTestDescriptor, EngineDescriptor

@API(value=Experimental)
public interface TestDescriptor

Mutable descriptor for a test or container that has been discovered by a TestEngine.

Since:

1.0

See Also:

TestEngine

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	TestDescriptor.Type Supported types for TestDescriptors.
static interface	TestDescriptor.Visitor Visitor for the tree-like TestDescriptor structure.

Method Summary

Modifier and Type	Method and Description
default void	accept(TestDescriptor.Visitor visitor) Accept a visitor to the subtree starting with this descriptor.
void	addChild(TestDescriptor descriptor) Add a child to this descriptor.
java.util.Optional<? extends TestDescriptor>	findByUniqueId(UniqueId uniqueId) Find the descriptor with the supplied unique ID.
java.util.Set<? extends TestDescriptor>	getChildren() Get the immutable set of children of this descriptor.
default java.util.Set<? extends TestDescriptor>	getDescendants() Get the immutable set of all descendants of this descriptor.
java.lang.String	getDisplayName() Get the display name for this descriptor.
default java.lang.String	getLegacyReportingName() Get the name of this descriptor in a format that is suitable for legacy reporting infrastructure — for example, for reporting systems built on the Ant-based XML reporting format for JUnit 4.
java.util.Optional<TestDescriptor>	getParent() Get the parent of this descriptor, if available.
java.util.Optional<TestSource>	getSource() Get the source of the test or container described by this descriptor, if available.
java.util.Set<TestTag>	getTags() Get the set of tags associated with this descriptor.
TestDescriptor.Type	getType() Determine the TestDescriptor.Type of this descriptor.
UniqueId	getUniqueId() Get the unique identifier (UID) for this descriptor.
default boolean	hasTests() Determine if this descriptor or any of its descendants describes a test.
default boolean	isContainer() Determine if this descriptor describes a container.
default boolean	isRoot() Determine if this descriptor is a root descriptor.
default boolean	isTest() Determine if this descriptor describes a test.
default void	prune() Remove this descriptor from the hierarchy unless it is a root or has tests.
default void	pruneTree() Remove this descriptor and its descendants from the hierarchy.
void	removeChild(TestDescriptor descriptor) Remove a child from this descriptor.
void	removeFromHierarchy() Remove this non-root descriptor from its parent and remove all the children from this descriptor.
void	setParent(TestDescriptor parent) Set the parent of this descriptor.

Method Detail

getUniqueId

UniqueId getUniqueId()

Get the unique identifier (UID) for this descriptor.

Uniqueness must be guaranteed across an entire test plan, regardless of how many engines are used behind the scenes.

Returns:

the UniqueId for this descriptor; never null

getDisplayName

java.lang.String getDisplayName()

Get the display name for this descriptor.

A display name is a human-readable name for a test or container that is typically used for test reporting in IDEs and build tools. Display names may contain spaces, special characters, and emoji, and the format may be customized by TestEngines or potentially by end users as well. Consequently, display names should never be parsed; rather, they should be used for display purposes only.

Returns:

the display name for this descriptor; never null or blank

See Also:

getSource()

getLegacyReportingName

default java.lang.String getLegacyReportingName()

Get the name of this descriptor in a format that is suitable for legacy reporting infrastructure — for example, for reporting systems built on the Ant-based XML reporting format for JUnit 4.

The default implementation simply delegates to getDisplayName().

Returns:

the legacy reporting name; never null or blank

getTags

java.util.Set<TestTag> getTags()

Get the set of tags associated with this descriptor.

Returns:

the set of tags associated with this descriptor; never null but potentially empty

See Also:

TestTag

getSource

java.util.Optional<TestSource> getSource()

Get the source of the test or container described by this descriptor, if available.

See Also:

TestSource

getParent

java.util.Optional<TestDescriptor> getParent()

Get the parent of this descriptor, if available.

setParent

void setParent(TestDescriptor parent)

Set the parent of this descriptor.

Parameters:

parent - the new parent of this descriptor; may be null.

getChildren

java.util.Set<? extends TestDescriptor> getChildren()

Get the immutable set of children of this descriptor.

Returns:

the set of children of this descriptor; neither null nor mutable, but potentially empty

See Also:

getDescendants()

getDescendants

default java.util.Set<? extends TestDescriptor> getDescendants()

Get the immutable set of all descendants of this descriptor.

A descendant is a child of this descriptor or a child of one of its children, recursively.

See Also:

getChildren()

addChild

void addChild(TestDescriptor descriptor)

Add a child to this descriptor.

Parameters:

descriptor - the child to add to this descriptor; never null

removeChild

void removeChild(TestDescriptor descriptor)

Remove a child from this descriptor.

Parameters:

descriptor - the child to remove from this descriptor; never null

removeFromHierarchy

void removeFromHierarchy()

Remove this non-root descriptor from its parent and remove all the children from this descriptor.

If this method is invoked on a root descriptor, this method must throw a JUnitException explaining that a root cannot be removed from the hierarchy.

isRoot

default boolean isRoot()

Determine if this descriptor is a root descriptor.

A root descriptor is a descriptor without a parent.

getType

TestDescriptor.Type getType()

Determine the TestDescriptor.Type of this descriptor.

Returns:

the descriptor type; never null.

See Also:

isContainer(), isTest()

isContainer

default boolean isContainer()

Determine if this descriptor describes a container.

The default implementation delegates to TestDescriptor.Type.isContainer().

isTest

default boolean isTest()

Determine if this descriptor describes a test.

The default implementation delegates to TestDescriptor.Type.isTest().

hasTests

default boolean hasTests()

Determine if this descriptor or any of its descendants describes a test.

The default implementation returns true if isTest() returns true and otherwise recurses through this descriptor's children to determine if they have tests.

prune

default void prune()

Remove this descriptor from the hierarchy unless it is a root or has tests.

A concrete TestEngine may override this method in order to implement a different algorithm or to skip pruning altogether.

See Also:

isRoot(), hasTests(), removeFromHierarchy()

pruneTree

default void pruneTree()

Remove this descriptor and its descendants from the hierarchy.

The default implementation supplies the prune() method as a TestDescriptor.Visitor to this descriptor, thereby effectively removing this descriptor and all of its descendants.

See Also:

accept(Visitor), prune()

findByUniqueId

java.util.Optional<? extends TestDescriptor> findByUniqueId(UniqueId uniqueId)

Find the descriptor with the supplied unique ID.

The search algorithm begins with this descriptor and then searches through its descendants.

Parameters:

uniqueId - the UniqueId to search for; never null

accept

default void accept(TestDescriptor.Visitor visitor)

Accept a visitor to the subtree starting with this descriptor.

Parameters:

visitor - the Visitor to accept; never null