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/** 9b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * <p>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 14b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * to have succeeded.</p> 15b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * 16b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * <p>A simple test looks like this: 17b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * <pre> 18b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * public class Example { 19b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * <b>@Test</b> 20b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * public void method() { 21b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * org.junit.Assert.assertTrue( new ArrayList().isEmpty() ); 22b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * } 23b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * } 24b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * </pre> 25b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * </p> 26b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * 27b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * <p>The <code>Test</code> annotation supports two optional parameters. 28b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * The first, <code>expected</code>, declares that a test method should throw 29b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * an exception. If it doesn't throw an exception or if it throws a different exception 30b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * than the one declared, the test fails. For example, the following test succeeds: 31b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * <pre> 32b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * @Test(<b>expected=IndexOutOfBoundsException.class</b>) public void outOfBounds() { 33b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * new ArrayList<Object>().get(1); 34b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * } 35b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * </pre></p> 36b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * 37b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * <p>The second optional parameter, <code>timeout</code>, causes a test to fail if it takes 38b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * longer than a specified amount of clock time (measured in milliseconds). The following test fails: 39b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * <pre> 40b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * @Test(<b>timeout=100</b>) public void infinity() { 41b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * while(true); 42b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * } 43b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * </pre></p> 44b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot */ 45b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot@Retention(RetentionPolicy.RUNTIME) 46b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot@Target({ElementType.METHOD}) 47b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabotpublic @interface Test { 48b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot 49b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot /** 50b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * Default empty exception 51b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot */ 52b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot static class None extends Throwable { 53b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot private static final long serialVersionUID= 1L; 54b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot private None() { 55b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot } 56b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot } 57b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot 58b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot /** 59b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * Optionally specify <code>expected</code>, a Throwable, to cause a test method to succeed iff 60b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * an exception of the specified class is thrown by the method. 61b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot */ 62b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot Class<? extends Throwable> expected() default None.class; 63b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot 64b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot /** 65b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * Optionally specify <code>timeout</code> in milliseconds to cause a test method to fail if it 66b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * takes longer than that number of milliseconds.*/ 67b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot long timeout() default 0L; 68b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot} 69