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 } 99
