Skip to content

Clarify test descriptor implementation requirements #5170

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Dec 1, 2025
+48 −8
Merged

Clarify test descriptor implementation requirements #5170

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
492cbb5
Document test and container are non-exclusive properties
mpkorstanje Nov 22, 2025
365ad02
Require isContainer and isTest to be consistent with getType
mpkorstanje Nov 28, 2025
ee1252a
Clarify that the only hierarchy is intended to be mutable
mpkorstanje Nov 28, 2025
3481b2f
Spotless
mpkorstanje Nov 28, 2025
c2702d9
Use consistent language
mpkorstanje Nov 28, 2025
41fac5d
Update release notes
mpkorstanje Nov 28, 2025
c05d549
Document immutable test descriptor requirement with mutable hierarchy
mpkorstanje Nov 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion documentation/src/docs/asciidoc/release-notes/release-notes-6.1.0-M2.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ repository on GitHub.
[[release-notes-6.1.0-M2-junit-platform-bug-fixes]]
==== Bug Fixes

* ❓
* Clarify `TestDescriptor` implementation requirements.

[[release-notes-6.1.0-M2-junit-platform-deprecations-and-breaking-changes]]
==== Deprecations and Breaking Changes
Expand Down
2 changes: 2 additions & 0 deletions documentation/src/docs/asciidoc/user-guide/advanced-topics/engines.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,8 @@ to the following requirements:
* The `TestDescriptor` returned from `TestEngine.discover()` _must_ be the root of a tree
of `TestDescriptor` instances. This implies that there _must not_ be any cycles between
a node and its descendants.
* The hierarchy of test descriptors returned from `TestEngine.discover()` _must_ be
mutable, but the test descriptors _must_ otherwise be immutable after discovery.
* A `TestEngine` _must_ be able to discover `UniqueIdSelectors` for any unique ID that it
previously generated and returned from `TestEngine.discover()`. This enables selecting a
subset of tests to execute or rerun.
Expand Down
52 changes: 45 additions & 7 deletions junit-platform-engine/src/main/java/org/junit/platform/engine/TestDescriptor.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,8 @@
import org.junit.platform.commons.util.Preconditions;

/**
* Mutable descriptor for a test or container that has been discovered by a
* {@link TestEngine}.
* A descriptor with a mutable hierarchy for a test or container that has been
* discovered by a {@link TestEngine}.
*
* @since 1.0
* @see TestEngine
Expand All @@ -42,6 +42,9 @@ public interface TestDescriptor {
* <p>Uniqueness must be guaranteed across an entire test plan,
* regardless of how many engines are used behind the scenes.
*
* <p>The implementation must treat this property as immutable after test
* discovery has completed.
*
* @return the {@code UniqueId} for this descriptor; never {@code null}
*/
UniqueId getUniqueId();
Expand Down Expand Up @@ -77,6 +80,9 @@ default String getLegacyReportingName() {
/**
* Get the set of {@linkplain TestTag tags} associated with this descriptor.
*
* <p>The implementation must treat this property as immutable after test
* discovery has completed.
*
* @return the set of tags associated with this descriptor; never {@code null}
* but potentially empty
* @see TestTag
Expand All @@ -87,6 +93,9 @@ default String getLegacyReportingName() {
* Get the {@linkplain TestSource source} of the test or container described
* by this descriptor, if available.
*
* <p>The implementation must treat this property as immutable after test
* discovery has completed.
*
* @see TestSource
*/
Optional<TestSource> getSource();
Expand All @@ -106,6 +115,9 @@ default String getLegacyReportingName() {
/**
* Get the immutable set of <em>children</em> of this descriptor.
*
* <p>The implementation must be consistent with {@link #isContainer()} such that
* {@code !x.container()} implies {@code x.getChildren().isEmpty()}.
*
* @return the set of children of this descriptor; neither {@code null}
* nor mutable, but potentially empty
* @see #getDescendants()
Expand Down Expand Up @@ -141,6 +153,9 @@ default Set<? extends TestDescriptor> getAncestors() {
* <p>A <em>descendant</em> is a child of this descriptor or a child of one of
* its children, recursively.
*
* <p>The implementation must be consistent with {@link #isContainer()} such that
* {@code !x.container()} implies {@code x.getDescendants().isEmpty()}.
*
* @see #getChildren()
*/
default Set<? extends TestDescriptor> getDescendants() {
Expand Down Expand Up @@ -223,14 +238,24 @@ default boolean isRoot() {
/**
* Determine the {@link Type} of this descriptor.
*
* <p>The implementation must treat this property as immutable after test
* discovery has completed.
*
* @return the descriptor type; never {@code null}.
* @see #isContainer()
* @see #isTest()
*/
Type getType();

/**
* Determine if this descriptor describes a container.
* Determine if this descriptor describes a <em>container</em>.
*
* <p>A test descriptor is a <em>container</em> when it may contain other
* containers or tests as its children. In addition to being a
* <em>container</em> this test descriptor may also be a <em>test</em>.
*
* <p>The implementation must be consistent with {@link #getType()} such
* that {@code x.isContainer()} equals {@code x.getType().isContainer()}.
*
* <p>The default implementation delegates to {@link Type#isContainer()}.
*/
Expand All @@ -239,7 +264,14 @@ default boolean isContainer() {
}

/**
* Determine if this descriptor describes a test.
* Determine if this descriptor describes a <em>test</em>.
*
* <p>A test descriptor is a <em>test</em> when it verifies expected
* behavior when executed. In addition to being a <em>test</em> this
* test descriptor may also be a <em>container</em>.
*
* <p>The implementation must be consistent with {@link #getType()} such
* that {@code x.isTest()} equals {@code x.getType().isTest()}.
*
* <p>The default implementation delegates to {@link Type#isTest()}.
*/
Expand All @@ -250,6 +282,10 @@ default boolean isTest() {
/**
* Determine if this descriptor may register dynamic tests during execution.
*
* <p>The implementation must treat this property as immutable after test
* discovery has completed and must be consistent with {@link #isContainer()}
* such that {@code !x.container()} implies {@code !x.mayRegisterTests()}.
*
* <p>The default implementation assumes tests are usually known during
* discovery and thus returns {@code false}.
*/
Expand All @@ -259,7 +295,7 @@ default boolean mayRegisterTests() {

/**
* Determine if the supplied descriptor (or any of its descendants)
* {@linkplain TestDescriptor#isTest() is a test} or
* {@linkplain TestDescriptor#isTest() is a <em>test</em>} or
* {@linkplain TestDescriptor#mayRegisterTests() may potentially register
* tests dynamically}.
*
Expand Down Expand Up @@ -355,12 +391,14 @@ static Visitor composite(Visitor... visitors) {
enum Type {

/**
* Denotes that the {@link TestDescriptor} is for a <em>container</em>.
* Denotes that the {@link TestDescriptor} is strictly for a
* <em>container</em>. I.e. it is not also a <em>test</em>.
*/
CONTAINER,

/**
* Denotes that the {@link TestDescriptor} is for a <em>test</em>.
* Denotes that the {@link TestDescriptor} is strictly for a
* <em>test</em>. I.e. it is not also a <em>container</em>.
*/
TEST,

Expand Down