001package org.junit;
002
003import java.lang.annotation.ElementType;
004import java.lang.annotation.Retention;
005import java.lang.annotation.RetentionPolicy;
006import java.lang.annotation.Target;
007
008/**
009 * <p>The <code>Test</code> annotation tells JUnit that the <code>public void</code> method
010 * to which it is attached can be run as a test case. To run the method,
011 * JUnit first constructs a fresh instance of the class then invokes the
012 * annotated method. Any exceptions thrown by the test will be reported
013 * by JUnit as a failure. If no exceptions are thrown, the test is assumed
014 * to have succeeded.</p>
015 *
016 * <p>A simple test looks like this:
017 * <pre>
018 * public class Example {
019 *    <b>&#064;Test</b>
020 *    public void method() {
021 *       org.junit.Assert.assertTrue( new ArrayList().isEmpty() );
022 *    }
023 * }
024 * </pre>
025 * </p>
026 *
027 * <p>The <code>Test</code> annotation supports two optional parameters.
028 * The first, <code>expected</code>, declares that a test method should throw
029 * an exception. If it doesn't throw an exception or if it throws a different exception
030 * than the one declared, the test fails. For example, the following test succeeds:
031 * <pre>
032 *    &#064;Test(<b>expected=IndexOutOfBoundsException.class</b>) public void outOfBounds() {
033 *       new ArrayList&lt;Object&gt;().get(1);
034 *    }
035 * </pre></p>
036 *
037 * <p>The second optional parameter, <code>timeout</code>, causes a test to fail if it takes
038 * longer than a specified amount of clock time (measured in milliseconds). The following test fails:
039 * <pre>
040 *    &#064;Test(<b>timeout=100</b>) public void infinity() {
041 *       while(true);
042 *    }
043 * </pre></p>
044 *
045 * @since 4.0
046 */
047@Retention(RetentionPolicy.RUNTIME)
048@Target({ElementType.METHOD})
049public @interface Test {
050
051    /**
052     * Default empty exception
053     */
054    static class None extends Throwable {
055        private static final long serialVersionUID = 1L;
056
057        private None() {
058        }
059    }
060
061    /**
062     * Optionally specify <code>expected</code>, a Throwable, to cause a test method to succeed iff
063     * an exception of the specified class is thrown by the method.
064     */
065    Class<? extends Throwable> expected() default None.class;
066
067    /**
068     * Optionally specify <code>timeout</code> in milliseconds to cause a test method to fail if it
069     * takes longer than that number of milliseconds.
070     */
071    long timeout() default 0L;
072}