1 /*
2 * MIT License
3 * Copyright (c) 2006-2025 JMockit developers
4 * See LICENSE file for full license text.
5 */
6 package mockit.integration.junit5;
7
8 import java.lang.annotation.ElementType;
9 import java.lang.annotation.Retention;
10 import java.lang.annotation.RetentionPolicy;
11 import java.lang.annotation.Target;
12
13 /**
14 * Annotation for specifying expected exceptions in JUnit 5 tests using JMockit.
15 * <p>
16 * This annotation allows you to declare that a test method is expected to throw a specific exception type, optionally
17 * with a specific message or message fragment. It is designed to help migrate JMockit-based tests from JUnit 4 to JUnit
18 * 5 and flexible message matching.
19 * <p>
20 * <b>Usage examples:</b>
21 *
22 * <pre>
23 * // Expect a MissingInvocation exception (type only)
24 * @Test
25 * @ExpectedException(MissingInvocation.class)
26 * public void testMissingInvocation() { ... }
27 *
28 * // Expect a MissingInvocation exception with a message containing "missing call"
29 * @Test
30 * @ExpectedException(value = MissingInvocation.class, expectedMessages = {"missing call"})
31 * public void testMissingInvocationWithMessage() { ... }
32 *
33 * // Expect either of two message fragments
34 * @Test
35 * @ExpectedException(value = MissingInvocation.class, expectedMessages = {"missing call", "not called"})
36 * public void testMultipleMessages() { ... }
37 *
38 * // Use exact message matching
39 * @Test
40 * @ExpectedException(value = MissingInvocation.class, expectedMessages = {"Exact error message"}, messageContains = false)
41 * public void testExactMessage() { ... }
42 * </pre>
43 * <p>
44 * For standard exception assertions unrelated to JMockit, use JUnit 5's {@code assertThrows}.
45 */
46 @Retention(RetentionPolicy.RUNTIME)
47 @Target(ElementType.METHOD)
48 public @interface ExpectedException {
49
50 /**
51 * Specifies the type of exception expected to be thrown by the test method.
52 * <p>
53 * Example:
54 *
55 * <pre>{@code
56 * @ExpectedException(MissingInvocation.class)
57 * }</pre>
58 *
59 * @return the expected exception class
60 */
61 Class<? extends Throwable> value();
62
63 /**
64 * Specifies one or more expected message fragments or exact messages for the exception.
65 * <p>
66 * If multiple values are provided, the test passes if any fragment matches the exception message.
67 *
68 * @return array of expected message fragments or exact messages
69 */
70 String[] expectedMessages() default {};
71
72 /**
73 * If true, matches exception messages using {@code String.contains}; if false, uses {@code String.equals}.
74 * <p>
75 * Default is true for compatibility with JUnit 4's contains-style matching.
76 *
77 * @return true for contains matching; false for exact matching
78 */
79 boolean messageContains() default true;
80
81 }