001package org.junit;
002
003import org.junit.function.ThrowingRunnable;
004
005import java.lang.annotation.ElementType;
006import java.lang.annotation.Retention;
007import java.lang.annotation.RetentionPolicy;
008import 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})
085public @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}