    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    }