Module org.junitpioneer

Package org.junitpioneer.jupiter

Annotation Type ExpectedToFail

@Documented
@Retention(RUNTIME)
@Target({METHOD,ANNOTATION_TYPE})
@ExtendWith(ExpectedToFailExtension.class)
public @interface ExpectedToFail

@ExpectedToFail is a JUnit Jupiter extension to mark test methods as temporarily 'expected to fail'. Such test methods will still be executed but when they result in a test failure or error the test will be aborted. However, if the test method unexpectedly executes successfully, it is marked as failure to let the developer know that the test is now successful and that the @ExpectedToFail annotation can be removed.

The big difference compared to JUnit's @Disabled annotation is that the developer is informed as soon as a test is successful again. This helps to avoid creating duplicate tests by accident and counteracts the accumulation of disabled tests over time.

Further, the withExceptions() attribute can be used to restrict the extension's behavior to specific exceptions. That is, only if the test method ends up throwing one of the specified exceptions will the test be aborted. This can, for example, be used when the production code temporarily throws an UnsupportedOperationException because some feature has not been implemented yet, but the test method is already implemented and should not fail on a failing assertion.

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 assertThrows or similar means to explicitly test for a specific exception class being thrown by a specific action.

For more details and examples, see the documentation on @ExpectedToFail.

Since:

1.8.0

See Also:

Disabled

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
java.lang.String	value	Defines the message to show when a test is aborted because it is failing.
java.lang.Class<? extends java.lang.Throwable>[]	withExceptions	Specifies which exceptions are expected to be thrown and will cause the test to be aborted rather than fail.

Element Detail

value

java.lang.String value

Defines the message to show when a test is aborted because it is failing. This can be used for example to briefly explain why the tested code is not working as intended at the moment. An empty string (the default) causes a generic default message to be used.

Default:

""

withExceptions

java.lang.Class<? extends java.lang.Throwable>[] withExceptions

Specifies which exceptions are expected to be thrown and will cause the test to be aborted rather than fail. An empty array is considered a configuration error and will cause the test to fail. Instead, consider leaving the attribute set to the default value when any exception should cause the test to be aborted.

Default:

{java.lang.Throwable.class}