1 package org.junit;
2
3 import java.lang.annotation.ElementType;
4 import java.lang.annotation.Retention;
5 import java.lang.annotation.RetentionPolicy;
6 import java.lang.annotation.Target;
7
8 /**
9 * The <code>Test</code> annotation tells JUnit that the <code>public void</code> method
10 * to which it is attached can be run as a test case. To run the method,
11 * JUnit first constructs a fresh instance of the class then invokes the
12 * annotated method. Any exceptions thrown by the test will be reported
13 * by JUnit as a failure. If no exceptions are thrown, the test is assumed
14 * to have succeeded.
15 * <p>
16 * A simple test looks like this:
17 * <pre>
18 * public class Example {
19 * <b>@Test</b>
20 * public void method() {
21 * org.junit.Assert.assertTrue( new ArrayList().isEmpty() );
22 * }
23 * }
24 * </pre>
25 * <p>
26 * The <code>Test</code> annotation supports two optional parameters.
27 * The first, <code>expected</code>, declares that a test method should throw
28 * an exception. If it doesn't throw an exception or if it throws a different exception
29 * than the one declared, the test fails. For example, the following test succeeds:
30 * <pre>
31 * @Test(<b>expected=IndexOutOfBoundsException.class</b>) public void outOfBounds() {
32 * new ArrayList<Object>().get(1);
33 * }
34 * </pre>
35 * If the exception's message or one of its properties should be verified, the
36 * {@link org.junit.rules.ExpectedException ExpectedException} rule can be used. Further
37 * information about exception testing can be found at the
38 * <a href="https://github.com/junit-team/junit/wiki/Exception-testing">JUnit Wiki</a>.
39 * <p>
40 * The second optional parameter, <code>timeout</code>, causes a test to fail if it takes
41 * longer than a specified amount of clock time (measured in milliseconds). The following test fails:
42 * <pre>
43 * @Test(<b>timeout=100</b>) public void infinity() {
44 * while(true);
45 * }
46 * </pre>
47 * <b>Warning</b>: while <code>timeout</code> is useful to catch and terminate
48 * infinite loops, it should <em>not</em> be considered deterministic. The
49 * following test may or may not fail depending on how the operating system
50 * schedules threads:
51 * <pre>
52 * @Test(<b>timeout=100</b>) public void sleep100() {
53 * Thread.sleep(100);
54 * }
55 * </pre>
56 * <b>THREAD SAFETY WARNING:</b> Test methods with a timeout parameter are run in a thread other than the
57 * thread which runs the fixture's @Before and @After methods. This may yield different behavior for
58 * code that is not thread safe when compared to the same test method without a timeout parameter.
59 * <b>Consider using the {@link org.junit.rules.Timeout} rule instead</b>, which ensures a test method is run on the
60 * same thread as the fixture's @Before and @After methods.
61 *
62 * @since 4.0
63 */
64 @Retention(RetentionPolicy.RUNTIME)
65 @Target({ElementType.METHOD})
66 public @interface Test {
67
68 /**
69 * Default empty exception
70 */
71 static class None extends Throwable {
72 private static final long serialVersionUID = 1L;
73
74 private None() {
75 }
76 }
77
78 /**
79 * Optionally specify <code>expected</code>, a Throwable, to cause a test method to succeed if
80 * and only if an exception of the specified class is thrown by the method. If the Throwable's
81 * message or one of its properties should be verified, the
82 * {@link org.junit.rules.ExpectedException ExpectedException} rule can be used instead.
83 */
84 Class<? extends Throwable> expected() default None.class;
85
86 /**
87 * Optionally specify <code>timeout</code> in milliseconds to cause a test method to fail if it
88 * takes longer than that number of milliseconds.
89 * <p>
90 * <b>THREAD SAFETY WARNING:</b> Test methods with a timeout parameter are run in a thread other than the
91 * thread which runs the fixture's @Before and @After methods. This may yield different behavior for
92 * code that is not thread safe when compared to the same test method without a timeout parameter.
93 * <b>Consider using the {@link org.junit.rules.Timeout} rule instead</b>, which ensures a test method is run on the
94 * same thread as the fixture's @Before and @After methods.
95 * </p>
96 */
97 long timeout() default 0L;
98 }