io.github.glytching.junit.extension.exception

Class ExpectedExceptionExtension

java.lang.Object

io.github.glytching.junit.extension.exception.ExpectedExceptionExtension

All Implemented Interfaces:

org.junit.jupiter.api.extension.AfterTestExecutionCallback, org.junit.jupiter.api.extension.Extension, org.junit.jupiter.api.extension.TestExecutionExceptionHandler

public class ExpectedExceptionExtension
extends Object
implements org.junit.jupiter.api.extension.TestExecutionExceptionHandler, org.junit.jupiter.api.extension.AfterTestExecutionCallback

The expected exception extension allows the developer to express the expectations of an exception to be thrown by the code-under-test. This extension is engaged by adding the ExpectedException annotation to a test method.

Usage example:

 public class MyTest {

     @Test
     @ExpectedException(type = Exception.class, messageIs = "Boom!")
     public void canHandleAnException() throws Exception {
         // ...
         throw new Exception("Boom!");
     }


     @Test
     @ExpectedException(type = RuntimeException.class, messageStartsWith = "Bye")
     public void canHandleAnExceptionWithAMessageWhichStartsWith() {
         // ...
         throw new RuntimeException("Bye bye");
     }
 }
 

Notes:

• Since usage of this extension implies that the developer expects an exception to be thrown the following test case will fail since it throws no exception:

     @Test
     @ExpectedException(type = Throwable.class)
     public void failsTestForMissingException() {}
   

  This is to avoid a false positive where a test is declared to expect an exception and passes even if no exception is thrown.
• The expected exception type will match on the given type and any subclasses of that type. In other words, the following test will pass:

            @Test
            @ExpectedException(type = Throwable.class, messageIs = "Boom!")
            public void canHandleAThrowable() throws Throwable {
                throw new Exception("Boom!");
            }
         

  This is for consistency with JUnit Jupiter, in which AssertThrows matches an exception type or any subclass of that exception type.

Since:

1.0.0

See Also:

JUnit 4 ExpectedException Rule

Constructor Summary

Constructors

Constructor and Description
ExpectedExceptionExtension()

Method Summary

Modifier and Type	Method and Description
void	afterTestExecution(org.junit.jupiter.api.extension.ExtensionContext extensionContext) The presence of ExpectedException on a test is a clear statement by the developer that some exception must be thrown by that test.
void	handleTestExecutionException(org.junit.jupiter.api.extension.ExtensionContext extensionContext, Throwable throwable) Handle the supplied Throwable throwable.

Methods inherited from class java.lang.Object

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

Constructor Detail

ExpectedExceptionExtension

public ExpectedExceptionExtension()

Method Detail

handleTestExecutionException

public void handleTestExecutionException(org.junit.jupiter.api.extension.ExtensionContext extensionContext,
                                         Throwable throwable)
                                  throws Throwable

Handle the supplied Throwable throwable. If the extensionContext is annotated with ExpectedException and if the throwable matches the expectations expressed in the ExpectedException annotation then the supplied throwable is swallowed otherwise the supplied throwable is rethrown.

Specified by:

handleTestExecutionException in interface org.junit.jupiter.api.extension.TestExecutionExceptionHandler

Parameters:

extensionContext - the current extension context

throwable - the Throwable to handle

Throws:

Throwable

afterTestExecution

public void afterTestExecution(org.junit.jupiter.api.extension.ExtensionContext extensionContext)
                        throws Exception

The presence of ExpectedException on a test is a clear statement by the developer that some exception must be thrown by that test. Therefore, if the invocation arrives here without having been evaluated by handleTestExecutionException(ExtensionContext, Throwable) and with no exception in the context then this expectation has not been met and rather than failing silently (and giving a false positive) the library will explicitly fail on this condition.

Specified by:

afterTestExecution in interface org.junit.jupiter.api.extension.AfterTestExecutionCallback

Parameters:

extensionContext -

Throws:

Exception