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