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 * 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/junit/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})
066public @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}