001    package org.junit;
002    
003    import org.junit.function.ThrowingRunnable;
004    
005    import java.lang.annotation.ElementType;
006    import java.lang.annotation.Retention;
007    import java.lang.annotation.RetentionPolicy;
008    import java.lang.annotation.Target;
009    
010    /**
011     * The <code>Test</code> annotation tells JUnit that the <code>public void</code> method
012     * to which it is attached can be run as a test case. To run the method,
013     * JUnit first constructs a fresh instance of the class then invokes the
014     * annotated method. Any exceptions thrown by the test will be reported
015     * by JUnit as a failure. If no exceptions are thrown, the test is assumed
016     * to have succeeded.
017     * <p>
018     * A simple test looks like this:
019     * <pre>
020     * public class Example {
021     *    <b>&#064;Test</b>
022     *    public void method() {
023     *       org.junit.Assert.assertTrue( new ArrayList().isEmpty() );
024     *    }
025     * }
026     * </pre>
027     * <p>
028     * The <code>Test</code> annotation supports two optional parameters for
029     * exception testing and for limiting test execution time.
030     *
031     * <h3>Exception Testing</h3>
032     * <p>
033     * The parameter <code>expected</code> declares that a test method should throw
034     * an exception. If it doesn't throw an exception or if it throws a different exception
035     * than the one declared, the test fails. For example, the following test succeeds:
036     * <pre>
037     *    &#064;Test(<b>expected=IndexOutOfBoundsException.class</b>)
038     *    public void outOfBounds() {
039     *       new ArrayList&lt;Object&gt;().get(1);
040     *    }
041     * </pre>
042     *
043     * Using the parameter <code>expected</code> for exception testing comes with
044     * some limitations: only the exception's type can be checked and it is not
045     * possible to precisely specify the code that throws the exception. Therefore
046     * JUnit 4 has improved its support for exception testing with
047     * {@link Assert#assertThrows(Class, ThrowingRunnable)} and the
048     * {@link org.junit.rules.ExpectedException ExpectedException} rule.
049     * With <code>assertThrows</code> the code that throws the exception can be
050     * precisely specified. If the exception's message or one of its properties
051     * should be verified, the <code>ExpectedException</code> rule can be used. Further
052     * information about exception testing can be found at the
053     * <a href="https://github.com/junit-team/junit4/wiki/Exception-testing">JUnit Wiki</a>.
054     *
055     * <h3>Timeout</h3>
056     * <p>
057     * The parameter <code>timeout</code> causes a test to fail if it takes
058     * longer than a specified amount of clock time (measured in milliseconds). The following test fails:
059     * <pre>
060     *    &#064;Test(<b>timeout=100</b>)
061     *    public void infinity() {
062     *       while(true);
063     *    }
064     * </pre>
065     * <b>Warning</b>: while <code>timeout</code> is useful to catch and terminate
066     * infinite loops, it should <em>not</em> be considered deterministic. The
067     * following test may or may not fail depending on how the operating system
068     * schedules threads:
069     * <pre>
070     *    &#064;Test(<b>timeout=100</b>)
071     *    public void sleep100() {
072     *       Thread.sleep(100);
073     *    }
074     * </pre>
075     * <b>THREAD SAFETY WARNING:</b> Test methods with a timeout parameter are run in a thread other than the
076     * thread which runs the fixture's @Before and @After methods. This may yield different behavior for
077     * code that is not thread safe when compared to the same test method without a timeout parameter.
078     * <b>Consider using the {@link org.junit.rules.Timeout} rule instead</b>, which ensures a test method is run on the
079     * same thread as the fixture's @Before and @After methods.
080     *
081     * @since 4.0
082     */
083    @Retention(RetentionPolicy.RUNTIME)
084    @Target({ElementType.METHOD})
085    public @interface Test {
086    
087        /**
088         * Default empty exception.
089         */
090        static class None extends Throwable {
091            private static final long serialVersionUID = 1L;
092    
093            private None() {
094            }
095        }
096    
097        /**
098         * Optionally specify <code>expected</code>, a Throwable, to cause a test method to succeed if
099         * and only if an exception of the specified class is thrown by the method. If the Throwable's
100         * message or one of its properties should be verified, the
101         * {@link org.junit.rules.ExpectedException ExpectedException} rule can be used instead.
102         */
103        Class<? extends Throwable> expected() default None.class;
104    
105        /**
106         * Optionally specify <code>timeout</code> in milliseconds to cause a test method to fail if it
107         * takes longer than that number of milliseconds.
108         * <p>
109         * <b>THREAD SAFETY WARNING:</b> Test methods with a timeout parameter are run in a thread other than the
110         * thread which runs the fixture's @Before and @After methods. This may yield different behavior for
111         * code that is not thread safe when compared to the same test method without a timeout parameter.
112         * <b>Consider using the {@link org.junit.rules.Timeout} rule instead</b>, which ensures a test method is run on the
113         * same thread as the fixture's @Before and @After methods.
114         * </p>
115         */
116        long timeout() default 0L;
117    }