001    package org.junit;
002    
003    import java.lang.annotation.ElementType;
004    import java.lang.annotation.Retention;
005    import java.lang.annotation.RetentionPolicy;
006    import java.lang.annotation.Target;
007    
008    /**
009     * 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.
015     * <p>
016     * 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     * The <code>Test</code> annotation supports two optional parameters.
027     * The first, <code>expected</code>, declares that a test method should throw
028     * an exception. If it doesn't throw an exception or if it throws a different exception
029     * than the one declared, the test fails. For example, the following test succeeds:
030     * <pre>
031     *    &#064;Test(<b>expected=IndexOutOfBoundsException.class</b>) public void outOfBounds() {
032     *       new ArrayList&lt;Object&gt;().get(1);
033     *    }
034     * </pre>
035     * If the exception's message or one of its properties should be verified, the
036     * {@link org.junit.rules.ExpectedException ExpectedException} rule can be used. Further
037     * information about exception testing can be found at the
038     * <a href="https://github.com/junit-team/junit4/wiki/Exception-testing">JUnit Wiki</a>.
039     * <p>
040     * The second optional parameter, <code>timeout</code>, causes a test to fail if it takes
041     * longer than a specified amount of clock time (measured in milliseconds). The following test fails:
042     * <pre>
043     *    &#064;Test(<b>timeout=100</b>) public void infinity() {
044     *       while(true);
045     *    }
046     * </pre>
047     * <b>Warning</b>: while <code>timeout</code> is useful to catch and terminate
048     * infinite loops, it should <em>not</em> be considered deterministic. The
049     * following test may or may not fail depending on how the operating system
050     * schedules threads:
051     * <pre>
052     *    &#064;Test(<b>timeout=100</b>) public void sleep100() {
053     *       Thread.sleep(100);
054     *    }
055     * </pre>
056     * <b>THREAD SAFETY WARNING:</b> Test methods with a timeout parameter are run in a thread other than the
057     * thread which runs the fixture's @Before and @After methods. This may yield different behavior for
058     * code that is not thread safe when compared to the same test method without a timeout parameter.
059     * <b>Consider using the {@link org.junit.rules.Timeout} rule instead</b>, which ensures a test method is run on the
060     * same thread as the fixture's @Before and @After methods.
061     *
062     * @since 4.0
063     */
064    @Retention(RetentionPolicy.RUNTIME)
065    @Target({ElementType.METHOD})
066    public @interface Test {
067    
068        /**
069         * Default empty exception.
070         */
071        static class None extends Throwable {
072            private static final long serialVersionUID = 1L;
073    
074            private None() {
075            }
076        }
077    
078        /**
079         * Optionally specify <code>expected</code>, a Throwable, to cause a test method to succeed if
080         * and only if an exception of the specified class is thrown by the method. If the Throwable's
081         * message or one of its properties should be verified, the
082         * {@link org.junit.rules.ExpectedException ExpectedException} rule can be used instead.
083         */
084        Class<? extends Throwable> expected() default None.class;
085    
086        /**
087         * Optionally specify <code>timeout</code> in milliseconds to cause a test method to fail if it
088         * takes longer than that number of milliseconds.
089         * <p>
090         * <b>THREAD SAFETY WARNING:</b> Test methods with a timeout parameter are run in a thread other than the
091         * thread which runs the fixture's @Before and @After methods. This may yield different behavior for
092         * code that is not thread safe when compared to the same test method without a timeout parameter.
093         * <b>Consider using the {@link org.junit.rules.Timeout} rule instead</b>, which ensures a test method is run on the
094         * same thread as the fixture's @Before and @After methods.
095         * </p>
096         */
097        long timeout() default 0L;
098    }