This version is still in development and is not considered stable yet.
For the latest stable version, please use JUnit 6.0.1!

API Evolution

One of the major goals of the JUnit Platform architecture is to improve maintainers' capabilities to evolve JUnit despite its being used in many projects. With JUnit 4 a lot of stuff that was originally added as an internal construct only got used by external extension writers and tool builders. That made changing JUnit 4 especially difficult and sometimes impossible.

That’s why JUnit now uses a defined lifecycle for all publicly available interfaces, classes, and methods.

API Version and Status

Every published artifact has a version number <major>.<minor>.<patch>, and all publicly available interfaces, classes, and methods are annotated with @API from the @API Guardian project. The annotation’s status attribute can be assigned one of the following values.

Status Description

INTERNAL

Must not be used by any code other than JUnit itself. Might be removed without prior notice.

DEPRECATED

Should no longer be used; might disappear in the next minor release.

EXPERIMENTAL

Intended for new, experimental features where we are looking for feedback.
Use this element with caution; it might be promoted to MAINTAINED or STABLE in the future, but might also be removed without prior notice, even in a patch.

MAINTAINED

Intended for features that will not be changed in a backwards- incompatible way for at least the next minor release of the current major version. If scheduled for removal, it will be demoted to DEPRECATED first.

STABLE

Intended for features that will not be changed in a backwards- incompatible way in the current major version (6.*).

If the @API annotation is present on a type, it is considered to be applicable for all public members of that type as well. A member is allowed to declare a different status value of lower stability.

Experimental APIs

The following tables list which APIs are currently designated as experimental via @API(status = EXPERIMENTAL). Caution should be taken when relying on such APIs.

Module org.junit.jupiter.api

Package org.junit.jupiter.api

Name Since

ClassOrderer.​Default (class)

6.0

@ClassTemplate (annotation)

6.0

@DisplayNameGenerator.​IndicativeSentences.​SentenceFragment (annotation)

6.0

MethodOrderer.​Default (class)

6.0

Package org.junit.jupiter.api.extension

Name Since

AfterClassTemplateInvocationCallback (interface)

6.0

BeforeClassTemplateInvocationCallback (interface)

6.0

ClassTemplateInvocationContext (interface)

6.0

ClassTemplateInvocationContextProvider (interface)

6.0

ExtensionContext.​StoreScope (enum)

6.0

ExtensionContext.​getStore(StoreScope, Namespace) (method)

6.0

TemplateInvocationValidationException (class)

6.0

TestTemplateInvocationContext.​prepareInvocation(ExtensionContext) (method)

6.0

Module org.junit.jupiter.params

Package org.junit.jupiter.params

Name Since

@AfterParameterizedClassInvocation (annotation)

6.0

@BeforeParameterizedClassInvocation (annotation)

6.0

@Parameter (annotation)

6.0

ParameterInfo (interface)

5.14

@ParameterizedClass (annotation)

6.0

@ParameterizedTest(quoteTextArguments=.​.​.​) (annotation attribute)

6.0

Package org.junit.jupiter.params.aggregator

Name Since

ArgumentsAggregator.​aggregateArguments(ArgumentsAccessor, FieldContext) (method)

6.0

SimpleArgumentsAggregator (class)

6.0

Package org.junit.jupiter.params.converter

Name Since

ArgumentConverter.​convert(@Nullable Object, FieldContext) (method)

6.0

Package org.junit.jupiter.params.provider

Name Since

ArgumentsProvider.​provideArguments(ParameterDeclarations, ExtensionContext) (method)

6.0

@CsvFileSource(commentCharacter=.​.​.​) (annotation attribute)

6.0.1

@CsvSource(commentCharacter=.​.​.​) (annotation attribute)

6.0.1

Package org.junit.jupiter.params.support

Name Since

FieldContext (interface)

6.0

ParameterDeclaration (interface)

6.0

ParameterDeclarations (interface)

6.0

Module org.junit.platform.commons

Package org.junit.platform.commons.function

Name Since

Try.​getNonNull() (method)

6.0

Try.​getNonNullOrThrow(Function<@Nullable Exception, E>) (method)

6.0

Package org.junit.platform.commons.support

Name Since

ModifierSupport.​isNotAbstract(Class<?>) (method)

6.0

ModifierSupport.​isNotAbstract(Member) (method)

6.0

Module org.junit.platform.engine

Package org.junit.platform.engine

Name Since

CancellationToken (interface)

6.0

DiscoveryIssue (interface)

6.0

EngineDiscoveryListener.​issueEncountered(UniqueId, DiscoveryIssue) (method)

6.0

ExecutionRequest.​getCancellationToken() (method)

6.0

ExecutionRequest.​getStore() (method)

6.0

TestDescriptor.​Visitor.​composite(Visitor[]) (method)

6.0

Package org.junit.platform.engine.discovery

Name Since

DiscoverySelectors.​selectClasses(Class<?>[]) (method)

6.0

DiscoverySelectors.​selectClasses(List<Class<?>>) (method)

6.0

DiscoverySelectors.​selectClassesByName(@Nullable ClassLoader, List<String>) (method)

6.0

DiscoverySelectors.​selectClassesByName(@Nullable ClassLoader, String[]) (method)

6.0

DiscoverySelectors.​selectClassesByName(List<String>) (method)

6.0

DiscoverySelectors.​selectClassesByName(String[]) (method)

6.0

Package org.junit.platform.engine.support.descriptor

Name Since

FileSource.​withPosition(@Nullable FilePosition) (method)

1.14

Package org.junit.platform.engine.support.discovery

Name Since

DiscoveryIssueReporter (interface)

6.0

EngineDiscoveryRequestResolver.​Builder.​addClassContainerSelectorResolverWithContext(Function<InitializationContext<T>, Predicate<Class<?>>>) (method)

6.0

EngineDiscoveryRequestResolver.​InitializationContext.​getIssueReporter() (method)

6.0

EngineDiscoveryRequestResolver.​resolve(EngineDiscoveryRequest, T, DiscoveryIssueReporter) (method)

6.0

Package org.junit.platform.engine.support.hierarchical

Name Since

HierarchicalTestExecutorService.​TestTask.​getTestDescriptor() (method)

6.0

Package org.junit.platform.engine.support.store

Name Since

Namespace (class)

6.0

NamespacedHierarchicalStore.​CloseAction.​closeAutoCloseables() (method)

6.0

NamespacedHierarchicalStore.​getParent() (method)

6.0

Module org.junit.platform.launcher

Package org.junit.platform.launcher.core

Name Since

DiscoveryIssueException (class)

6.0

LauncherDiscoveryRequestBuilder.​forExecution() (method)

6.0

Module org.junit.platform.testkit

Package org.junit.platform.testkit.engine

Name Since

EngineDiscoveryResults (class)

6.0

EngineTestKit.​Builder.​cancellationToken(CancellationToken) (method)

6.0

EngineTestKit.​Builder.​discover() (method)

6.0

EngineTestKit.​discover(String, LauncherDiscoveryRequest) (method)

6.0

EngineTestKit.​discover(TestEngine, LauncherDiscoveryRequest) (method)

6.0

EventConditions.​legacyReportingName(String) (method)

6.0

EventConditions.​uniqueId(Condition<? super UniqueId>) (method)

6.0

EventConditions.​uniqueId(String) (method)

6.0

EventConditions.​uniqueId(UniqueId) (method)

6.0

Deprecated APIs

The following tables list which APIs are currently designated as deprecated via @API(status = DEPRECATED). You should avoid using deprecated APIs whenever possible, since such APIs will likely be removed in an upcoming release.

Module org.junit.jupiter.api

Package org.junit.jupiter.api

Name Since

DisplayNameGenerator.​generateDisplayNameForMethod(Class<?>, Method) (method)

5.12

DisplayNameGenerator.​generateDisplayNameForNestedClass(Class<?>) (method)

5.12

TestReporter.​publishFile(Path, MediaType) (method)

5.14

TestReporter.​publishFile(String, MediaType, ThrowingConsumer<Path>) (method)

5.14

Package org.junit.jupiter.api.condition

Name Since

JRE.​currentVersion() (method)

5.12

Package org.junit.jupiter.api.extension

Name Since

ExtensionContext.​Store.​CloseableResource (interface)

5.13

ExtensionContext.​Store.​getOrComputeIfAbsent(Class<V>) (method)

6.0

ExtensionContext.​Store.​getOrComputeIfAbsent(K, Function<? super K, ? extends V>) (method)

6.0

ExtensionContext.​Store.​getOrComputeIfAbsent(K, Function<? super K, ? extends V>, Class<V>) (method)

6.0

ExtensionContext.​publishFile(String, MediaType, ThrowingConsumer<Path>) (method)

5.14

MediaType (class)

5.14

Module org.junit.jupiter.migrationsupport

Package org.junit.jupiter.migrationsupport

Name Since

@EnableJUnit4MigrationSupport (annotation)

6.0

Package org.junit.jupiter.migrationsupport.conditions

Name Since

IgnoreCondition (class)

6.0

Package org.junit.jupiter.migrationsupport.rules

Name Since

@EnableRuleMigrationSupport (annotation)

6.0

ExpectedExceptionSupport (class)

6.0

ExternalResourceSupport (class)

6.0

VerifierSupport (class)

6.0

Module org.junit.jupiter.params

Package org.junit.jupiter.params.provider

Name Since

ArgumentsProvider.​provideArguments(ExtensionContext) (method)

5.13

Package org.junit.jupiter.params.support

Name Since

ParameterInfo (interface)

5.14

Module org.junit.platform.commons

Package org.junit.platform.commons.support

Name Since

AnnotationSupport.​findAnnotation(@Nullable Class<?>, Class<A>, SearchOption) (method)

1.12

ReflectionSupport.​findAllResourcesInClasspathRoot(URI, Predicate<Resource>) (method)

1.14

ReflectionSupport.​findAllResourcesInModule(String, Predicate<Resource>) (method)

1.14

ReflectionSupport.​findAllResourcesInPackage(String, Predicate<Resource>) (method)

1.14

ReflectionSupport.​streamAllResourcesInClasspathRoot(URI, Predicate<Resource>) (method)

1.14

ReflectionSupport.​streamAllResourcesInModule(String, Predicate<Resource>) (method)

1.14

ReflectionSupport.​streamAllResourcesInPackage(String, Predicate<Resource>) (method)

1.14

ReflectionSupport.​tryToGetResources(String) (method)

1.14

ReflectionSupport.​tryToGetResources(String, ClassLoader) (method)

1.14

Resource (interface)

1.14

SearchOption (enum)

1.12

Package org.junit.platform.commons.support.scanning

Name Since

ClasspathScanner.​scanForResourcesInClasspathRoot(URI, Predicate<Resource>) (method)

1.14

ClasspathScanner.​scanForResourcesInPackage(String, Predicate<Resource>) (method)

1.14

Module org.junit.platform.engine

Package org.junit.platform.engine

Name Since

EngineDiscoveryRequest.​getOutputDirectoryProvider() (method)

1.14

ExecutionRequest(TestDescriptor, EngineExecutionListener, ConfigurationParameters) (constructor)

1.11

ExecutionRequest.​create(TestDescriptor, EngineExecutionListener, ConfigurationParameters) (method)

1.11

ExecutionRequest.​getOutputDirectoryProvider() (method)

1.14

Filter.​adaptFilter(Filter<V>, Function<T, V>) (method)

6.0

Package org.junit.platform.engine.discovery

Name Since

ClasspathResourceSelector.​getClasspathResources() (method)

1.14

DiscoverySelectors.​selectClasspathResource(Set<Resource>) (method)

1.14

Package org.junit.platform.engine.reporting

Name Since

OutputDirectoryProvider (interface)

1.14

Package org.junit.platform.engine.support.discovery

Name Since

EngineDiscoveryRequestResolver.​Builder.​addResourceContainerSelectorResolver(Predicate<Resource>) (method)

1.14

Package org.junit.platform.engine.support.store

Name Since

NamespacedHierarchicalStore.​getOrComputeIfAbsent(N, K, Function<? super K, ? extends V>) (method)

6.0

NamespacedHierarchicalStore.​getOrComputeIfAbsent(N, K, Function<? super K, ? extends V>, Class<V>) (method)

6.0

Module org.junit.platform.launcher

Package org.junit.platform.launcher

Name Since

TestPlan.​getOutputDirectoryProvider() (method)

1.14

TestPlan.​getTestIdentifier(String) (method)

1.10

Package org.junit.platform.launcher.core

Name Since

LauncherDiscoveryRequestBuilder.​outputDirectoryProvider(OutputDirectoryProvider) (method)

1.14

Module org.junit.platform.testkit

Package org.junit.platform.testkit.engine

Name Since

EngineTestKit.​Builder.​outputDirectoryProvider(OutputDirectoryProvider) (method)

1.14

Module org.junit.vintage.engine

Package org.junit.vintage.engine

Name Since

Constants (class)

6.0

VintageTestEngine (class)

6.0

@API Tooling Support

The @API Guardian project plans to provide tooling support for publishers and consumers of APIs annotated with @API. For example, the tooling support will likely provide a means to check if JUnit APIs are being used in accordance with @API annotation declarations.