## org.springframework.test
Class AssertThrows

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

    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();
        }
     }

You might want to compare this class with the `junit.extensions.ExceptionTestCase` class.

Note: This class requires JDK 1.4 or higher.

Since:
  2.0
Author:
  Rick Evans, Juergen Hoeller

Constructor Summary
`AssertThrows(Class expectedException)` Create a new instance of the `AssertThrows` class.
`AssertThrows(Class expectedException, String failureMessage)` Create a new instance of the `AssertThrows` class.

Method Summary
`protected void` `checkExceptionExpectations(Exception actualException)` 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()` Creates the failure message used if the test fails (i.e. the expected exception is not thrown in the body of the test).
`protected String` `createMessageForWrongThrownExceptionType(Exception actualException)` Creates the failure message used if the wrong type of `Exception` is thrown in the body of the test.
`protected void` `doFail()` Template method called when the test fails; i.e. the expected `Exception` is not thrown.
`Exception` `getActualException()` Expose the actual exception thrown from `test()`, if any.
`protected Class` `getExpectedException()` Return the `Exception` expected to be thrown during the execution of the surrounding test.
`protected String` `getFailureMessage()` Return the extra, contextual failure message that will be included in the failure text if the text fails.
`void` `runTest()` The main template method that drives the running of the `test logic` and the `checking` of the resulting (expected) `Exception`.
`void` `setFailureMessage(String failureMessage)` Set the extra, contextual failure message that will be included in the failure text if the text fails.
`abstract void` `test()` 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)

  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)

  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()

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

### setFailureMessage

    public void setFailureMessage(String failureMessage)

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

### getFailureMessage

    protected String getFailureMessage()

  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

  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()

  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()

  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()

  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)

  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)

  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()

  Expose the actual exception thrown from `test()`, if any.

  Returns:
    the actual exception, or `null` if none

Copyright © 2002-2008 The Spring Framework.