There is a newer version available.
For the latest stable version, please use JUnit 6.0.1!

API Evolution

One of the major goals of JUnit 5 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 5 introduces 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 (5.*).

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

Package org.junit.jupiter.params

Name Since

ParameterInfo (interface)

5.14

Module org.junit.platform.engine

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

Name Since

FileSource.​withPosition(FilePosition) (method)

1.14

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

MethodOrderer.​Alphanumeric (class)

5.7

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.​publishFile(String, MediaType, ThrowingConsumer<Path>) (method)

5.14

InvocationInterceptor.​interceptDynamicTest(Invocation<Void>, ExtensionContext) (method)

5.8

MediaType (class)

5.14

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(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.​loadClass(String) (method)

1.4

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

ConfigurationParameters.​size() (method)

1.9

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

Package org.junit.platform.engine.discovery

Name Since

ClasspathResourceSelector.​getClasspathResources() (method)

1.14

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

1.14

MethodSelector.​getMethodParameterTypes() (method)

1.10

NestedMethodSelector.​getMethodParameterTypes() (method)

1.10

Package org.junit.platform.engine.reporting

Name Since

OutputDirectoryProvider (interface)

1.14

ReportEntry() (constructor)

1.8

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

Name Since

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

1.14

Package org.junit.platform.engine.support.filter

Name Since

ClasspathScanningSupport (class)

1.5

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

Name Since

SingleTestExecutor (class)

1.2

Module org.junit.platform.launcher

Package org.junit.platform.launcher

Name Since

TestPlan.​add(TestIdentifier) (method)

1.4

TestPlan.​getChildren(String) (method)

1.10

TestPlan.​getOutputDirectoryProvider() (method)

1.14

TestPlan.​getTestIdentifier(String) (method)

1.10

Package org.junit.platform.launcher.core

Name Since

LauncherDiscoveryRequestBuilder() (constructor)

1.8

LauncherDiscoveryRequestBuilder.​outputDirectoryProvider(OutputDirectoryProvider) (method)

1.14

Package org.junit.platform.launcher.listeners

Name Since

LegacyReportingUtils (class)

1.6

Module org.junit.platform.runner

Package org.junit.platform.runner

Name Since

JUnitPlatform (class)

1.8

Module org.junit.platform.suite.api

Package org.junit.platform.suite.api

Name Since

@UseTechnicalNames (annotation)

1.8

Module org.junit.platform.suite.commons

Package org.junit.platform.suite.commons

Name Since

SuiteLauncherDiscoveryRequestBuilder.​suite(Class<?>) (method)

1.11

Module org.junit.platform.testkit

Package org.junit.platform.testkit.engine

Name Since

EngineTestKit.​Builder.​filters(DiscoveryFilter<?>[]) (method)

1.7

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

1.14

EngineTestKit.​execute(String, EngineDiscoveryRequest) (method)

1.7

EngineTestKit.​execute(TestEngine, EngineDiscoveryRequest) (method)

1.7

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