Often tests fail due to a bug in the tested application or in dependencies. Traditionally such a test method would be annotated with JUnit’s @Disabled. However, this has disadvantages when the bug that causes the test failure is fixed:

  • the developer might not notice the existing test method and create a new one

  • the existing test method might not be noticed and remains disabled for a long time after the bug has been fixed, adding no value for the project

@ExpectedToFail solves these issues. Unlike @Disabled it still executes the annotated test method but aborts the test if a test failure or error occurs. However, if the test is executed successfully it will cause a test failure because the test is working. This lets the developer know that they have fixed the bug (possibly by accident) and that they can now remove the @ExpectedToFail annotation from the test method.

The annotation can only be used on methods and as meta-annotation on other annotation types. Similar to @Disabled, it has to be used in addition to a "testable" annotation, such as @Test. Otherwise the annotation has no effect.

Important

This annotation is not intended as a way to mark test methods which intentionally cause exceptions. Such test methods should use JUnit’s assertThrows or similar means to explicitly test for a specific exception class being thrown by a specific action.

Basic Use

The test is aborted because the tested method brokenMethod() returns an incorrect result.

@Test
@ExpectedToFail
void test() {
    int actual = brokenMethod();
    assertEquals(10, actual);
}

An aborted test is no failure and so the test suite passes (if all other tests pass, of course). Should brokenMethod() start returning the correct value, the test invocation passes, but @ExpectedToFail marks the test as failed to draw attention to that change in behavior.

A custom message can be provided, explaining why the tested code is not working as intended at the moment.

@Test
@ExpectedToFail("Implementation bug in brokenMethod()")
void doSomething() {
    int actual = brokenMethod();
    assertEquals(10, actual);
}

Thread-Safety

This extension is safe to use during parallel test execution.