Interface TestDescriptor

All Known Implementing Classes:
AbstractTestDescriptor, ClassBasedTestDescriptor, ClassTemplateInvocationTestDescriptor, ClassTemplateTestDescriptor, ClassTestDescriptor, EngineDescriptor, JupiterEngineDescriptor, JupiterTestDescriptor, MethodBasedTestDescriptor, NestedClassTestDescriptor, RunnerTestDescriptor, TestFactoryTestDescriptor, TestMethodTestDescriptor, TestTemplateInvocationTestDescriptor, TestTemplateTestDescriptor, VintageEngineDescriptor, VintageTestDescriptor
@API(status=STABLE, since="1.0") public interface TestDescriptor
Mutable descriptor for a test or container that has been discovered by a TestEngine.
Since:
1.0
See Also:

  • Method Details

    • 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

      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:

    • getLegacyReportingName

      default 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 delegates to getDisplayName().

      Returns:
      the legacy reporting name; never null or blank

    • getTags

      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:

    • getSource

      Optional<TestSource> getSource()
      Get the source of the test or container described by this descriptor, if available.
      See Also:

    • getParent

      Optional<TestDescriptor> getParent()
      Get the parent of this descriptor, if available.

    • setParent

      void setParent(@Nullable TestDescriptor parent)
      Set the parent of this descriptor.
      Parameters:
      parent - the new parent of this descriptor; may be null.

    • getChildren

      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:

    • getAncestors

      @API(status=STABLE, since="1.10") default Set<? extends TestDescriptor> getAncestors()
      Get the immutable set of all ancestors of this descriptor.

      An ancestor is the parent of this descriptor or the parent of one of its parents, recursively.

      See Also:

    • getDescendants

      default 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:

    • 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.

    • orderChildren

      @API(status=MAINTAINED, since="1.13.3") default void orderChildren(UnaryOperator<List<TestDescriptor>> orderer)
      Order the children of this descriptor.

      The orderer is provided a modifiable list of child test descriptors of this test descriptor; never null. The orderer must return a list containing the same descriptors in any order; potentially the same list, but never null. If descriptors are added or removed, an exception is thrown.

      Parameters:
      orderer - a unary operator to order the children of this test descriptor
      Since:
      1.12

    • 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

      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().

    • mayRegisterTests

      default boolean mayRegisterTests()
      Determine if this descriptor may register dynamic tests during execution.

      The default implementation assumes tests are usually known during discovery and thus returns false.

    • containsTests

      static boolean containsTests(TestDescriptor testDescriptor)
      Determine if the supplied descriptor (or any of its descendants) is a test or may potentially register tests dynamically.
      Parameters:
      testDescriptor - the TestDescriptor to check for tests; never null
      Returns:
      true if the descriptor is a test, contains tests, or may later register tests dynamically

    • prune

      default void prune()
      Remove this descriptor from the hierarchy unless it is a root or contains tests.

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

      See Also:

    • findByUniqueId

      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 TestDescriptor.Visitor to the subtree starting with this descriptor.
      Parameters:
      visitor - the Visitor to accept; never null