Timeout (JUnit API)
Date: 2018-08-04

org.junit.rules

## Class Timeout

- java.lang.Object
- - org.junit.rules.Timeout

- All Implemented Interfaces:
    TestRule

      public class Timeout
      extends java.lang.Object
      implements TestRule

  The Timeout Rule applies the same timeout to all test methods in a class:

       public static class HasGlobalLongTimeout {

        @Rule
        public Timeout globalTimeout= new Timeout(20);

        @Test
        public void run1() throws InterruptedException {
            Thread.sleep(100);
        }

        @Test
        public void infiniteLoop() {
            while (true) {}
        }
       }

  Each test is run in a new thread. If the specified timeout elapses before the test completes, its execution is interrupted via `Thread.interrupt()`. This happens in interruptable I/O and locks, and methods in `Object` and `Thread` throwing `InterruptedException`.

  A specified timeout of 0 will be interpreted as not set, however tests will still launch from separate threads. This can be useful for disabling timeouts in environments where they are dynamically set based on some property.

  Since:
    4.7

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Timeout.Builder` Builder for `Timeout`.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `Timeout(int millis)` Deprecated.
    `` | `Timeout(long timeout, java.util.concurrent.TimeUnit timeUnit)` Create a `Timeout` instance with the timeout specified at the timeUnit of granularity of the provided `TimeUnit`.
    `protected` | `Timeout(Timeout.Builder builder)` Create a `Timeout` instance initialized with values form a builder.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Statement` | `apply(Statement base, Description description)` Modifies the method-running `Statement` to implement this test-running rule.
    `static Timeout.Builder` | `builder()` Returns a new builder for building an instance.
    `protected Statement` | `createFailOnTimeoutStatement(Statement statement)` Creates a `Statement` that will run the given `statement`, and timeout the operation based on the values configured in this rule.
    `protected boolean` | `getLookingForStuckThread()` Gets whether this `Timeout` will look for a stuck thread when the test times out.
    `protected long` | `getTimeout(java.util.concurrent.TimeUnit unit)` Gets the timeout configured for this rule, in the given units.
    `static Timeout` | `millis(long millis)` Creates a `Timeout` that will timeout a test after the given duration, in milliseconds.
    `static Timeout` | `seconds(long seconds)` Creates a `Timeout` that will timeout a test after the given duration, in seconds.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### Timeout

          @Deprecated
          public Timeout(int millis)

      Deprecated.
      Create a `Timeout` instance with the timeout specified in milliseconds.

      This constructor is deprecated.

      Instead use `Timeout(long, java.util.concurrent.TimeUnit)`, `millis(long)`, or `seconds(long)`.

      Parameters:
        `millis` - the maximum time in milliseconds to allow the test to run before it should timeout

    - #### Timeout

          public Timeout(long timeout,
                 java.util.concurrent.TimeUnit timeUnit)

      Create a `Timeout` instance with the timeout specified at the timeUnit of granularity of the provided `TimeUnit`.
      Parameters:
        `timeout` - the maximum time to allow the test to run before it should timeout
        `timeUnit` - the time unit for the `timeout`
      Since:
        4.12

    - #### Timeout

          protected Timeout(Timeout.Builder builder)

      Create a `Timeout` instance initialized with values form a builder.
      Since:
        4.12

  - ### Method Detail

    - #### builder

          public static Timeout.Builder builder()

      Returns a new builder for building an instance.
      Since:
        4.12

    - #### millis

          public static Timeout millis(long millis)

      Creates a `Timeout` that will timeout a test after the given duration, in milliseconds.
      Since:
        4.12

    - #### seconds

          public static Timeout seconds(long seconds)

      Creates a `Timeout` that will timeout a test after the given duration, in seconds.
      Since:
        4.12

    - #### getTimeout

          protected final long getTimeout(java.util.concurrent.TimeUnit unit)

      Gets the timeout configured for this rule, in the given units.
      Since:
        4.12

    - #### getLookingForStuckThread

          protected final boolean getLookingForStuckThread()

      Gets whether this `Timeout` will look for a stuck thread when the test times out.
      Since:
        4.12

    - #### createFailOnTimeoutStatement

          protected Statement createFailOnTimeoutStatement(Statement statement)
                                                    throws java.lang.Exception

      Creates a `Statement` that will run the given `statement`, and timeout the operation based on the values configured in this rule. Subclasses can override this method for different behavior.
      Throws:
        `java.lang.Exception`
      Since:
        4.12

    - #### apply

          public Statement apply(Statement base,
                        Description description)

      Description copied from interface: `TestRule`
      Modifies the method-running `Statement` to implement this test-running rule.
      Specified by:
        `apply` in interface `TestRule`
      Parameters:
        `base` - The `Statement` to be modified
        `description` - A `Description` of the test implemented in `base`
      Returns:
        a new statement, which may be the same as `base`, a wrapper around `base`, or a completely new Statement.