@Documented
@Incubating
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})
@ExtendWith(ExpectedToFailExtension.class)
public @interface ExpectedToFail

Inverts the pass/fail outcome of the annotated test method (or every test method on the annotated class): a test that throws is reported as passing, and a test that completes normally is reported as failing.

Useful for asserting that some condition reliably fails, and for testing test-infrastructure code that should propagate failures.

Optionally constrain the expected failure by exception type or by a closure predicate evaluated against the thrown exception:

 @Test
 @ExpectedToFail(IllegalStateException)
 void mustThrowIse() { throw new IllegalStateException("boom") }

 @Test
 @ExpectedToFail({ ex instanceof RuntimeException && message.contains('boom') })
 void mustMatchPredicate() { throw new RuntimeException("kaboom!") }
 

Closure predicates are evaluated with three bindings: ex (the thrown exception), message (its message, possibly null), and cause (its cause, possibly null). The test is reported as passing iff the predicate returns a Groovy-truthy value.

For callers who want compile-time enforcement that the configured class is a Throwable subclass, set exception() instead of (or alongside) value(). exception and a closure value compose: the type acts as a guard that runs before the predicate, so the closure body can drop the ex instanceof X boilerplate. exception and a Throwable value are mutually exclusive (they would specify the type twice).

TestAbortedException (the exception thrown by JUnit Assumptions) is never treated as the expected failure; it's always rethrown so the test is reported as aborted.

Composition with ForkedJvm: works in either declaration order via explicit coordination between the two extensions (no reliance on annotation iteration order). When @ExpectedToFail is declared before @ForkedJvm (i.e., outer), the inversion happens in the parent JVM after the failure propagates from the fork — exercising @ForkedJvm's serialization. When declared after (inner), the inversion happens inside the forked child.

Since:

6.0.0