tree cb3dfdff46e4b448eb15787996e35849cf73f38e
parent 413eb071d60aa672dbd358211d642635dc725fab
author Dave Borowitz <dborowitz@google.com> 1556811867 -0700
committer David Pursehouse <dpursehouse@collab.net> 1563943454 +0900

Add assertThrows method compatible with future JUnit 4.13

The testing guidelines at Google have the following to say about testing
for exceptions:

"The strongly preferred solution is to use Assert.assertThrows().
...
In some situations you will decide it is important to check additional
details about the thrown exception. You might care about its message, or
the attributes of its chained exception, for example.

It is easy to check these details, as assertThrows returns the thrown
exception to you, and you can pass it to Truth.
...
There are two cases where you can't use assertThrows:
 * In open-sourced code, until JUnit 4.13 is released.
 * When you aren't able to use Java 8 constructs like lambda expressions.
   (You can still use assertThrows, but you may find it bulky enough to
   outweigh its advantages.)

However, use caution when doing so
...
Don't use ExpectedException, @Test(expected =), or
ExceptionExpectations. You can find a lengthy explanation of the
pitfalls of these approaches in this page's history."

I've mentioned these pitfalls in code reviews before, based on this
advice. Paraphrasing the page history referenced above:

 * The main downside of manual try-fail is it's easy to forget the
   fail call; we've been bitten by this in Gerrit several times.
 * ExpectedException is dangerous because any statements after the
   throwing call will never be executed, even though the author of those
   statements probably did not intend this.
 * @Test(expected) passes if *any* statement in the test body throws,
   regardless of which statement the author had in mind. Later
   statements may not execute at all.

Unfortunately, JUnit 4.13 is taking much longer to release than
anticipated. I asked the Truth team approximately one year ago whether
it would make sense to add assertThrows to Truth itself; their answer
was that they didn't think it was worth it, given that it would
eventually be replaced by JUnit 4.13. They told me that if we want to
use it sooner, we should roll our own, so here we are.

I wrote this method to be source-compatible with the method in JUnit
4.13 based upon reading the method signature and Javadoc of JUnit.
However, I wrote the implementation from scratch without referencing the
JUnit implementation.

Change-Id: I4a774846ad6245f418c50be02dc469698b6e4def