7. API Evolution

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

###

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

7.2. Experimental APIs

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

Package Name	Type Name	Since
`org.junit.jupiter.api`	`DisplayNameGenerator.IndicativeSentences` (class)	`5.7`
`org.junit.jupiter.api`	`IndicativeSentencesGeneration` (annotation)	`5.7`
`org.junit.jupiter.api`	`MethodOrderer.DisplayName` (class)	`5.7`
`org.junit.jupiter.api`	`MethodOrderer.MethodName` (class)	`5.7`
`org.junit.jupiter.api`	`Order` (annotation)	`5.4`
`org.junit.jupiter.api.extension`	`InvocationInterceptor` (interface)	`5.5`
`org.junit.jupiter.api.extension`	`InvocationInterceptor.Invocation` (interface)	`5.5`
`org.junit.jupiter.api.extension`	`LifecycleMethodExecutionExceptionHandler` (interface)	`5.5`
`org.junit.jupiter.api.extension`	`ReflectiveInvocationContext` (interface)	`5.5`
`org.junit.jupiter.api.extension`	`TestInstantiationException` (class)	`5.3`
`org.junit.jupiter.api.extension.support`	`TypeBasedParameterResolver` (class)	`5.6`
`org.junit.jupiter.api.io`	`TempDir` (annotation)	`5.4`
`org.junit.jupiter.api.parallel`	`Execution` (annotation)	`5.3`
`org.junit.jupiter.api.parallel`	`ExecutionMode` (enum)	`5.3`
`org.junit.jupiter.api.parallel`	`Isolated` (annotation)	`5.7`
`org.junit.jupiter.api.parallel`	`ResourceAccessMode` (enum)	`5.3`
`org.junit.jupiter.api.parallel`	`ResourceLock` (annotation)	`5.3`
`org.junit.jupiter.api.parallel`	`ResourceLocks` (annotation)	`5.3`
`org.junit.jupiter.api.parallel`	`Resources` (class)	`5.3`
`org.junit.jupiter.params.converter`	`TypedArgumentConverter` (class)	`5.7`
`org.junit.platform.console`	`ConsoleLauncherToolProvider` (class)	`1.6`
`org.junit.platform.engine`	`EngineDiscoveryListener` (interface)	`1.6`
`org.junit.platform.engine`	`SelectorResolutionResult` (class)	`1.6`
`org.junit.platform.engine.support.config`	`PrefixedConfigurationParameters` (class)	`1.3`
`org.junit.platform.engine.support.discovery`	`EngineDiscoveryRequestResolver` (class)	`1.5`
`org.junit.platform.engine.support.discovery`	`EngineDiscoveryRequestResolver.Builder` (class)	`1.5`
`org.junit.platform.engine.support.discovery`	`EngineDiscoveryRequestResolver.InitializationContext` (interface)	`1.5`
`org.junit.platform.engine.support.discovery`	`SelectorResolver` (interface)	`1.5`
`org.junit.platform.engine.support.discovery`	`SelectorResolver.Context` (interface)	`1.5`
`org.junit.platform.engine.support.discovery`	`SelectorResolver.Match` (class)	`1.5`
`org.junit.platform.engine.support.discovery`	`SelectorResolver.Resolution` (class)	`1.5`
`org.junit.platform.engine.support.hierarchical`	`DefaultParallelExecutionConfigurationStrategy` (enum)	`1.3`
`org.junit.platform.engine.support.hierarchical`	`ExclusiveResource` (class)	`1.3`
`org.junit.platform.engine.support.hierarchical`	`ForkJoinPoolHierarchicalTestExecutorService` (class)	`1.3`
`org.junit.platform.engine.support.hierarchical`	`HierarchicalTestExecutorService` (interface)	`1.3`
`org.junit.platform.engine.support.hierarchical`	`Node.ExecutionMode` (enum)	`1.3`
`org.junit.platform.engine.support.hierarchical`	`Node.Invocation` (interface)	`1.4`
`org.junit.platform.engine.support.hierarchical`	`ParallelExecutionConfiguration` (interface)	`1.3`
`org.junit.platform.engine.support.hierarchical`	`ParallelExecutionConfigurationStrategy` (interface)	`1.3`
`org.junit.platform.engine.support.hierarchical`	`ResourceLock` (interface)	`1.3`
`org.junit.platform.engine.support.hierarchical`	`SameThreadHierarchicalTestExecutorService` (class)	`1.3`
`org.junit.platform.jfr`	`FlightRecordingListener` (class)	`1.7`
`org.junit.platform.launcher`	`EngineDiscoveryResult` (class)	`1.6`
`org.junit.platform.launcher`	`LauncherDiscoveryListener` (class)	`1.6`
`org.junit.platform.launcher.listeners.discovery`	`LauncherDiscoveryListeners` (class)	`1.6`

7.3. Deprecated APIs

The following table lists 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.

Package Name	Type Name	Since
`org.junit.jupiter.api`	`MethodOrderer.Alphanumeric` (class)	`5.7`
`org.junit.platform.commons.util`	`BlacklistedExceptions` (class)	`1.7`
`org.junit.platform.commons.util`	`PreconditionViolationException` (class)	`1.5`
`org.junit.platform.engine.support.filter`	`ClasspathScanningSupport` (class)	`1.5`
`org.junit.platform.engine.support.hierarchical`	`SingleTestExecutor` (class)	`1.2`
`org.junit.platform.launcher.listeners`	`LegacyReportingUtils` (class)	`1.6`

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