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>@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 * @Test(<b>expected=IndexOutOfBoundsException.class</b>)
038 * public void outOfBounds() {
039 * new ArrayList<Object>().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 * @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 * @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 }