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
    String
    value
    Defines the message to show when a test is aborted because it is failing.
    Class<? extends Throwable>[]
    withExceptions
    Specifies which exceptions are expected to be thrown and will cause the test to be aborted rather than fail.

  • Element Details

    • value

      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

      Class<? extends 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}