The annotation org.junitpioneer.vintage.@Test is a drop-in replacement for JUnit 4’s org.junit.@Test annotation, but marks the method as a regular JUnit Jupiter test. You can make use of it when migrating tests from JUnit 4 to Jupiter by doing a fulltext search/replace of import org.junit.Test with import org.junitpioneer.vintage.Test. That means you do not need to run JUnit 5’s Vintage engine to execute such tests - Jupiter suffices.

This should be seen as an intermediate step towards a full migration and should be followed up by gradual/manual replacement of org.junitpioneer.vintage.Test with Jupiter’s org.junit.jupiter.api.Test. To emphasize its character as a temporary solution and to reduce risk of accidental use, it’s marked as deprecated.

Since the test is run by Jupiter, JUnit 4 runners and rules will have no effect and you will still have to replace them with JUnit 5 extensions.

Like JUnit 4’s version, @Test has two optional parameters:

  • expected to fail a test unless an exception of the specified type is thrown

  • timeout to fail and abandon a test that runs too long

Expecting exceptions

The optional parameter expected declares that a test method should throw an exception. If it doesn’t throw an exception or if it throws an exception whose type is not the specified one and does not extend it, the test fails.

For example, the following test succeeds because the thrown exception is of the specified type:

@Test(expected = IndexOutOfBoundsException.class)
public void outOfBounds_passes() {
    List.of().get(1);
}

This test succeeds because the thrown exception is a subtype of the specified one:

@Test(expected = RuntimeException.class)
public void outOfBounds_passes_too() {
    List.of().get(1);
}

Finally, this test fails because the thrown exception is neither of the specified type nor a subtype:

@Test(expected = IllegalArgumentException.class)
public void outOfBounds_fails() {
    List.of().get(1);
}

Fail long-running tests

The optional parameter timeout causes a test to fail if it takes longer than a specified amount of clock time, measured in milliseconds. The following test fails:

@Test(timeout = 100)
public void slow_fail() throws InterruptedException {
    Thread.sleep(1_000);
}

Like in JUnit 4, timeout aborts long-running tests. The following test does not run indefinitely - it fails after 100 milliseconds:

@Test(timeout = 100)
public void indefinitely() {
    while (true)
        ;
}

Thread-Safety

This extension is safe to use during parallel test execution.