AssertThrows (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.test

## Class AssertThrows

- java.lang.Object
- - org.springframework.test.AssertThrows

- Deprecated.
  favor use of JUnit 4's `@Test(expected=...)` support

      @Deprecated
      public abstract class AssertThrows
      extends Object

  Simple method object encapsulation of the 'test-for-Exception' scenario (for JUnit).

  Used like so:

       // the class under test
       public class Foo {
          public void someBusinessLogic(String name) {
              if (name == null) {
                  throw new IllegalArgumentException("The 'name' argument is required");
              }
              // rest of business logic here...
          }
       }

  The test for the above bad argument path can be expressed using the `AssertThrows` class like so:

       public class FooTest {
          public void testSomeBusinessLogicBadArgumentPath() {
              new AssertThrows(IllegalArgumentException.class) {
                  public void test() {
                      new Foo().someBusinessLogic(null);
                  }
              }.runTest();
          }
       }

  This will result in the test passing if the `Foo.someBusinessLogic(..)` method threw an `IllegalArgumentException`; if it did not, the test would fail with the following message:

       "Must have thrown a [class java.lang.IllegalArgumentException]"

  If the wrong type of `Exception` was thrown, the test will also fail, this time with a message similar to the following:

       "junit.framework.AssertionFailedError: Was expecting a [class java.lang.UnsupportedOperationException] to be thrown, but instead a [class java.lang.IllegalArgumentException] was thrown"

  The test for the correct `Exception` respects polymorphism, so you can test that any old `Exception` is thrown like so:

       public class FooTest {
          public void testSomeBusinessLogicBadArgumentPath() {
              // any Exception will do...
              new AssertThrows(Exception.class) {
                  public void test() {
                      new Foo().someBusinessLogic(null);
                  }
              }.runTest();
          }
       }

  Intended for use with JUnit 4 and TestNG (as of Spring 3.0). You might want to compare this class with the `junit.extensions.ExceptionTestCase` class.
  Since:
    2.0
  Author:
    Rick Evans, Juergen Hoeller

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `AssertThrows(Class expectedException)` Deprecated. Create a new instance of the `AssertThrows` class.
    `AssertThrows(Class expectedException, String failureMessage)` Deprecated. Create a new instance of the `AssertThrows` class.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `checkExceptionExpectations(Exception actualException)` Deprecated. Does the donkey work of checking (verifying) that the `Exception` that was thrown in the body of a test is an instance of the `getExpectedException()` class (or an instance of a subclass).
    `protected String` | `createMessageForNoExceptionThrown()` Deprecated. Creates the failure message used if the test fails (i.e.
    `protected String` | `createMessageForWrongThrownExceptionType(Exception actualException)` Deprecated. Creates the failure message used if the wrong type of `Exception` is thrown in the body of the test.
    `protected void` | `doFail()` Deprecated. Template method called when the test fails; i.e.
    `Exception` | `getActualException()` Deprecated. Expose the actual exception thrown from `test()`, if any.
    `protected Class` | `getExpectedException()` Deprecated. Return the `Exception` expected to be thrown during the execution of the surrounding test.
    `protected String` | `getFailureMessage()` Deprecated. Return the extra, contextual failure message that will be included in the failure text if the text fails.
    `void` | `runTest()` Deprecated. The main template method that drives the running of the `test logic` and the `checking` of the resulting (expected) `Exception`.
    `void` | `setFailureMessage(String failureMessage)` Deprecated. Set the extra, contextual failure message that will be included in the failure text if the text fails.
    `abstract void` | `test()` Deprecated. Subclass must override this `abstract` method and provide the test logic.

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

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

- - ### Constructor Detail

    - #### AssertThrows

          public AssertThrows(Class expectedException)

      Deprecated.
      Create a new instance of the `AssertThrows` class.
      Parameters:
        `expectedException` - the `Exception` expected to be thrown during the execution of the surrounding test
      Throws:
        `IllegalArgumentException` - if the supplied `expectedException` is `null`; or if said argument is not an `Exception`-derived class

    - #### AssertThrows

          public AssertThrows(Class expectedException,
                      String failureMessage)

      Deprecated.
      Create a new instance of the `AssertThrows` class.
      Parameters:
        `expectedException` - the `Exception` expected to be thrown during the execution of the surrounding test
        `failureMessage` - the extra, contextual failure message that will be included in the failure text if the text fails (can be `null`)
      Throws:
        `IllegalArgumentException` - if the supplied `expectedException` is `null`; or if said argument is not an `Exception`-derived class

  - ### Method Detail

    - #### getExpectedException

          protected Class getExpectedException()

      Deprecated.
      Return the `Exception` expected to be thrown during the execution of the surrounding test.

    - #### setFailureMessage

          public void setFailureMessage(String failureMessage)

      Deprecated.
      Set the extra, contextual failure message that will be included in the failure text if the text fails.

    - #### getFailureMessage

          protected String getFailureMessage()

      Deprecated.
      Return the extra, contextual failure message that will be included in the failure text if the text fails.

    - #### test

          public abstract void test()
                             throws Exception

      Deprecated.
      Subclass must override this `abstract` method and provide the test logic.
      Throws:
        `Exception` - if an error occurs during the execution of the aformentioned test logic

    - #### runTest

          public void runTest()

      Deprecated.
      The main template method that drives the running of the `test logic` and the `checking` of the resulting (expected) `Exception`.
      See Also:
        `test()`, `doFail()`, `checkExceptionExpectations(Exception)`

    - #### doFail

          protected void doFail()

      Deprecated.
      Template method called when the test fails; i.e. the expected `Exception` is not thrown.

      The default implementation simply fails the test via a call to `Assert.fail(String)`.

      If you want to customise the failure message, consider overriding `createMessageForNoExceptionThrown()`, and / or supplying an extra, contextual failure message via the appropriate constructor overload.

      See Also:
        `getFailureMessage()`

    - #### createMessageForNoExceptionThrown

          protected String createMessageForNoExceptionThrown()

      Deprecated.
      Creates the failure message used if the test fails (i.e. the expected exception is not thrown in the body of the test).
      Returns:
        the failure message used if the test fails
      See Also:
        `getFailureMessage()`

    - #### checkExceptionExpectations

          protected void checkExceptionExpectations(Exception actualException)

      Deprecated.
      Does the donkey work of checking (verifying) that the `Exception` that was thrown in the body of a test is an instance of the `getExpectedException()` class (or an instance of a subclass).

      If you want to customise the failure message, consider overriding `createMessageForWrongThrownExceptionType(Exception)`.

      Parameters:
        `actualException` - the `Exception` that has been thrown in the body of a test method (will never be `null`)

    - #### createMessageForWrongThrownExceptionType

          protected String createMessageForWrongThrownExceptionType(Exception actualException)

      Deprecated.
      Creates the failure message used if the wrong type of `Exception` is thrown in the body of the test.
      Parameters:
        `actualException` - the actual exception thrown
      Returns:
        the message for the given exception

    - #### getActualException

          public final Exception getActualException()

      Deprecated.
      Expose the actual exception thrown from `test()`, if any.
      Returns:
        the actual exception, or `null` if none