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