Package org.junit.platform.launcher

Class TestPlan

  • Direct Known Subclasses:
    InternalTestPlan
    @API(status=STABLE,
     since="1.0")
public class TestPlan
extends java.lang.Object
    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

    • Method Detail

      • from

        @API(status=INTERNAL,
     since="1.14")
public static TestPlan from​(boolean containsTests,
                            java.util.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 - whether the test plan contains tests
        engineDescriptors - the engine test descriptors from which the test plan should be created; never null
        configurationParameters - the ConfigurationParameters for this test plan; never null
        outputDirectoryCreator - the OutputDirectoryProvider for this test plan; never null
        Returns:
        a new test plan

      • add

        @Deprecated
@API(status=DEPRECATED,
     since="1.4")
public void add​(TestIdentifier testIdentifier)
        Deprecated.
        Calling this method is no longer supported and will throw an exception.
        Add the supplied TestIdentifier to this test plan.
        Parameters:
        testIdentifier - the identifier to add; never null
        Throws:
        org.junit.platform.commons.JUnitException - always

      • addInternal

        @API(status=INTERNAL,
     since="1.8")
public void addInternal​(TestIdentifier testIdentifier)

      • getRoots

        public java.util.Set<TestIdentifier> getRoots()
        Get the root TestIdentifiers for this test plan.
        Returns:
        an unmodifiable set of the root identifiers

      • getParent

        public java.util.Optional<TestIdentifier> getParent​(TestIdentifier child)
        Get the parent of the supplied TestIdentifier.
        Parameters:
        child - the identifier to look up the parent for; never null
        Returns:
        an Optional containing the parent, if present

      • getChildren

        public java.util.Set<TestIdentifier> getChildren​(TestIdentifier parent)
        Get the children of the supplied TestIdentifier.
        Parameters:
        parent - the identifier to look up the children for; never null
        Returns:
        an unmodifiable set of the parent's children, potentially empty
        See Also:
        getChildren(UniqueId)

      • getChildren

        @API(status=DEPRECATED,
     since="1.10")
@Deprecated
public java.util.Set<TestIdentifier> getChildren​(java.lang.String parentId)
        Deprecated.
        Use getChildren(UniqueId)
        Get the children of the supplied unique ID.
        Parameters:
        parentId - the unique ID to look up the children for; never null or blank
        Returns:
        an unmodifiable set of the parent's children, potentially empty
        See Also:
        getChildren(TestIdentifier)

      • getChildren

        @API(status=MAINTAINED,
     since="1.10")
public java.util.Set<TestIdentifier> getChildren​(UniqueId parentId)
        Get the children of the supplied unique ID.
        Parameters:
        parentId - the unique ID to look up the children for; never null
        Returns:
        an unmodifiable set of the parent's children, potentially empty
        See Also:
        getChildren(TestIdentifier)

      • getTestIdentifier

        @API(status=DEPRECATED,
     since="1.10")
@Deprecated
public TestIdentifier getTestIdentifier​(java.lang.String uniqueId)
                                 throws org.junit.platform.commons.PreconditionViolationException
        Deprecated.
        Use getTestIdentifier(UniqueId)
        Get the TestIdentifier with the supplied unique ID.
        Parameters:
        uniqueId - the unique ID to look up the identifier for; never null or blank
        Returns:
        the identifier with the supplied unique ID; never null
        Throws:
        org.junit.platform.commons.PreconditionViolationException - if no TestIdentifier with the supplied unique ID is present in this test plan

      • getTestIdentifier

        @API(status=MAINTAINED,
     since="1.10")
public TestIdentifier getTestIdentifier​(UniqueId uniqueId)
        Get the TestIdentifier with the supplied unique ID.
        Parameters:
        uniqueId - the unique ID to look up the identifier for; never null
        Returns:
        the identifier with the supplied unique ID; never null
        Throws:
        org.junit.platform.commons.PreconditionViolationException - if no TestIdentifier with the supplied unique ID is present in this test plan

      • countTestIdentifiers

        public long countTestIdentifiers​(java.util.function.Predicate<? super TestIdentifier> predicate)
        Count all TestIdentifiers that satisfy the given predicate.
        Parameters:
        predicate - a predicate which returns true for identifiers to be counted; never null
        Returns:
        the number of identifiers that satisfy the supplied predicate

      • getDescendants

        public java.util.Set<TestIdentifier> getDescendants​(TestIdentifier parent)
        Get all descendants of the supplied TestIdentifier (i.e., all of its children and their children, recursively).
        Parameters:
        parent - the identifier to look up the descendants for; never null
        Returns:
        an unmodifiable set of the parent's descendants, potentially empty

      • containsTests

        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:
        true if this test plan contains tests
        See Also:
        TestDescriptor.containsTests(TestDescriptor)

      • getConfigurationParameters

        @API(status=MAINTAINED,
     since="1.8")
public ConfigurationParameters getConfigurationParameters()
        Get the ConfigurationParameters for this test plan.
        Returns:
        the configuration parameters; never null
        Since:
        1.8

      • getOutputDirectoryCreator

        @API(status=MAINTAINED,
     since="1.14")
public OutputDirectoryCreator getOutputDirectoryCreator()
        Get the OutputDirectoryCreator for this test plan.
        Returns:
        the output directory creator; never null
        Since:
        1.14

      • accept

        @API(status=MAINTAINED,
     since="1.13.3")
public void accept​(TestPlan.Visitor visitor)
        Accept the supplied TestPlan.Visitor for a depth-first traversal of the test plan.
        Parameters:
        visitor - the visitor to accept; never null
        Since:
        1.10