[[migrating-from-junit4]]
== Migrating from JUnit 4

Although the JUnit Jupiter programming model and extension model will not support JUnit 4
features such as `Rules` and `Runners` natively, it is not expected that source code
maintainers will need to update all of their existing tests, test extensions, and custom
build test infrastructure to migrate to JUnit Jupiter.

Instead, JUnit provides a gentle migration path via a _JUnit Vintage test engine_ which
allows existing tests based on JUnit 3 and JUnit 4 to be executed using the JUnit
Platform infrastructure. Since all classes and annotations specific to JUnit Jupiter
reside under a new `org.junit.jupiter` base package, having both JUnit 4 and JUnit
Jupiter in the classpath does not lead to any conflicts. It is therefore safe to maintain
existing JUnit 4 tests alongside JUnit Jupiter tests. Furthermore, since the JUnit team
will continue to provide maintenance and bug fix releases for the JUnit 4.x baseline,
developers have plenty of time to migrate to JUnit Jupiter on their own schedule.

[[migrating-from-junit4-running]]
=== Running JUnit 4 Tests on the JUnit Platform

Just make sure that the `junit-vintage-engine` artifact is in your test runtime path. In
that case JUnit 3 and JUnit 4 tests will automatically be picked up by the JUnit Platform
launcher.

See the example projects in the {junit5-samples-repo}[`junit5-samples`] repository to
find out how this is done with Gradle and Maven.

[[migrating-from-junit4-categories-support]]
==== Categories Support

For test classes or methods that are annotated with `@Category`, the
_JUnit Vintage test engine_ exposes the category's fully qualified class name as a tag
of the corresponding test identifier. For example, if a test method is annotated with
`@Category(Example.class)`, it will be tagged with `"com.acme.Example"`. Similar to the
`Categories` runner in JUnit 4, this information can be used to filter the discovered
tests before executing them (see <<running-tests>> for details).

[[migrating-from-junit4-tips]]
=== Migration Tips

The following are things you have to watch out for when migrating existing JUnit 4 tests
to JUnit Jupiter.

* Annotations reside in the `org.junit.jupiter.api` package.
* Assertions reside in `org.junit.jupiter.api.Assertions`.
* Assumptions reside in `org.junit.jupiter.api.Assumptions`.
* `@Before` and `@After` no longer exist; use `@BeforeEach` and `@AfterEach` instead.
* `@BeforeClass` and `@AfterClass` no longer exist; use `@BeforeAll` and `@AfterAll` instead.
* `@Ignore` no longer exists: use `@Disabled` instead.
* `@Category` no longer exists; use `@Tag` instead.
* `@RunWith` no longer exists; superseded by `@ExtendWith`.
* `@Rule` and `@ClassRule` no longer exist; superseded by `@ExtendWith`;
   see the following section for partial rule support.

[[migrating-from-junit4-rule-support]]
=== Limited JUnit 4 Rule Support

As stated above, JUnit Jupiter does not and will not support JUnit 4 rules natively. The
JUnit team realizes, however, that many organizations, especially large ones, are likely
to have large JUnit 4 code bases that make use of custom rules. To serve these
organizations and enable a gradual migration path the JUnit team has decided to support a
selection of JUnit 4 rules verbatim within JUnit Jupiter. This support is based on
adapters and is limited to those rules that are semantically compatible to the JUnit
Jupiter extension model, i.e. those that do not completely change the overall execution
flow of the test.

The `junit-jupiter-migrationsupport` module from JUnit Jupiter currently supports the
following three `Rule` types including subclasses of those types:

* `org.junit.rules.ExternalResource` (including `org.junit.rules.TemporaryFolder`)
* `org.junit.rules.Verifier` (including `org.junit.rules.ErrorCollector`)
* `org.junit.rules.ExpectedException`

As in JUnit 4, Rule-annotated fields as well as methods are supported. By using these
class-level extensions on a test class such `Rule` implementations in legacy code bases
can be _left unchanged_ including the JUnit 4 rule import statements.

This limited form of `Rule` support can be switched on by the class-level annotation
`org.junit.jupiter.migrationsupport.rules.EnableRuleMigrationSupport`. This annotation is
a _composed annotation_ which enables all migration support extensions:
`VerifierSupport`, `ExternalResourceSupport`, and `ExpectedExceptionSupport`.

However, if you intend to develop a new extension for JUnit 5 please use the new
extension model of JUnit Jupiter instead of the rule-based model of JUnit 4.

WARNING: JUnit 4 `Rule` support in JUnit Jupiter is currently an _experimental_ feature.
Consult the table in <<api-evolution-experimental-apis>> for detail.
