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

org.junit.rules

## Class Stopwatch

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

- All Implemented Interfaces:
    TestRule

      public abstract class Stopwatch
      extends java.lang.Object
      implements TestRule

  The Stopwatch Rule notifies one of its own protected methods of the time spent by a test.

  Override them to get the time in nanoseconds. For example, this class will keep logging the time spent by each passed, failed, skipped, and finished test:

       public static class StopwatchTest {
           private static final Logger logger = Logger.getLogger("");

           private static void logInfo(Description description, String status, long nanos) {
               String testName = description.getMethodName();
               logger.info(String.format("Test %s %s, spent %d microseconds",
                                         testName, status, TimeUnit.NANOSECONDS.toMicros(nanos)));
           }

           @Rule
           public Stopwatch stopwatch = new Stopwatch() {
               @Override
               protected void succeeded(long nanos, Description description) {
                   logInfo(description, "succeeded", nanos);
               }

               @Override
               protected void failed(long nanos, Throwable e, Description description) {
                   logInfo(description, "failed", nanos);
               }

               @Override
               protected void skipped(long nanos, AssumptionViolatedException e, Description description) {
                   logInfo(description, "skipped", nanos);
               }

               @Override
               protected void finished(long nanos, Description description) {
                   logInfo(description, "finished", nanos);
               }
           };

           @Test
           public void succeeds() {
           }

           @Test
           public void fails() {
               fail();
           }

           @Test
           public void skips() {
               assumeTrue(false);
           }
       }

  An example to assert runtime:

       @Test
       public void performanceTest() throws InterruptedException {
           long delta = 30;
           Thread.sleep(300L);
           assertEquals(300d, stopwatch.runtime(MILLISECONDS), delta);
           Thread.sleep(500L);
           assertEquals(800d, stopwatch.runtime(MILLISECONDS), delta);
       }

  Since:
    4.12

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Stopwatch()`

  - ### 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.
    `protected void` | `failed(long nanos, java.lang.Throwable e, Description description)` Invoked when a test fails
    `protected void` | `finished(long nanos, Description description)` Invoked when a test method finishes (whether passing or failing)
    `long` | `runtime(java.util.concurrent.TimeUnit unit)` Gets the runtime for the test.
    `protected void` | `skipped(long nanos, AssumptionViolatedException e, Description description)` Invoked when a test is skipped due to a failed assumption.
    `protected void` | `succeeded(long nanos, Description description)` Invoked when a test succeeds

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

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

- - ### Constructor Detail

    - #### Stopwatch

          public Stopwatch()

  - ### Method Detail

    - #### runtime

          public long runtime(java.util.concurrent.TimeUnit unit)

      Gets the runtime for the test.
      Parameters:
        `unit` - time unit for returned runtime
      Returns:
        runtime measured during the test

    - #### succeeded

          protected void succeeded(long nanos,
                       Description description)

      Invoked when a test succeeds

    - #### failed

          protected void failed(long nanos,
                    java.lang.Throwable e,
                    Description description)

      Invoked when a test fails

    - #### skipped

          protected void skipped(long nanos,
                     AssumptionViolatedException e,
                     Description description)

      Invoked when a test is skipped due to a failed assumption.

    - #### finished

          protected void finished(long nanos,
                      Description description)

      Invoked when a test method finishes (whether passing or failing)

    - #### apply

          public final 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.