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
diff --git a/gerrit-server/src/test/java/com/google/gerrit/testutil/GerritJUnit.java b/gerrit-server/src/test/java/com/google/gerrit/testutil/GerritJUnit.java
new file mode 100644
index 0000000..7437c7e
--- /dev/null
+++ b/gerrit-server/src/test/java/com/google/gerrit/testutil/GerritJUnit.java
@@ -0,0 +1,67 @@
+// Copyright (C) 2019 The Android Open Source Project
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package com.google.gerrit.testutil;
+
+/** Static JUnit utility methods. */
+public class GerritJUnit {
+ /**
+ * Assert that an exception is thrown by a block of code.
+ *
+ * <p>This method is source-compatible with <a
+ * href="https://junit.org/junit4/javadoc/latest/org/junit/Assert.html#assertThrows(java.lang.Class,%20org.junit.function.ThrowingRunnable)">JUnit
+ * 4.13 beta</a>.
+ *
+ * <p>This construction is recommended by the Truth team for use in conjunction with asserting
+ * over a {@code ThrowableSubject} on the return type:
+ *
+ * <pre>
+ * MyException e = assertThrows(MyException.class, () -> doSomething(foo));
+ * assertThat(e).isInstanceOf(MySubException.class);
+ * assertThat(e).hasMessageThat().contains("sub-exception occurred");
+ * </pre>
+ *
+ * @param throwableClass expected exception type.
+ * @param runnable runnable containing arbitrary code.
+ * @return exception that was thrown.
+ */
+ public static <T extends Throwable> T assertThrows(
+ Class<T> throwableClass, ThrowingRunnable runnable) {
+ try {
+ runnable.run();
+ } catch (Throwable t) {
+ if (!throwableClass.isInstance(t)) {
+ throw new AssertionError(
+ "expected "
+ + throwableClass.getName()
+ + " but "
+ + t.getClass().getName()
+ + " was thrown",
+ t);
+ }
+ @SuppressWarnings("unchecked")
+ T toReturn = (T) t;
+ return toReturn;
+ }
+ throw new AssertionError(
+ "expected " + throwableClass.getName() + " but no exception was thrown");
+ }
+
+ @FunctionalInterface
+ public interface ThrowingRunnable {
+ void run() throws Throwable;
+ }
+
+ private GerritJUnit() {}
+}
diff --git a/gerrit-server/src/test/java/com/google/gerrit/testutil/GerritJUnitTest.java b/gerrit-server/src/test/java/com/google/gerrit/testutil/GerritJUnitTest.java
new file mode 100644
index 0000000..e0ead71
--- /dev/null
+++ b/gerrit-server/src/test/java/com/google/gerrit/testutil/GerritJUnitTest.java
@@ -0,0 +1,90 @@
+// Copyright (C) 2019 The Android Open Source Project
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package com.google.gerrit.testutil;
+
+import static com.google.common.truth.Truth.assertThat;
+import static com.google.common.truth.Truth.assert_;
+import static com.google.gerrit.testutil.GerritJUnit.assertThrows;
+
+import org.junit.Test;
+
+public class GerritJUnitTest {
+ private static class MyException extends Exception {
+ private static final long serialVersionUID = 1L;
+
+ MyException(String msg) {
+ super(msg);
+ }
+ }
+
+ private static class MySubException extends MyException {
+ private static final long serialVersionUID = 1L;
+
+ MySubException(String msg) {
+ super(msg);
+ }
+ }
+
+ @Test
+ public void assertThrowsCatchesSpecifiedExceptionType() {
+ MyException e =
+ assertThrows(
+ MyException.class,
+ () -> {
+ throw new MyException("foo");
+ });
+ assertThat(e).hasMessageThat().isEqualTo("foo");
+ }
+
+ @Test
+ public void assertThrowsCatchesSubclassOfSpecifiedExceptionType() {
+ MyException e =
+ assertThrows(
+ MyException.class,
+ () -> {
+ throw new MySubException("foo");
+ });
+ assertThat(e).isInstanceOf(MySubException.class);
+ assertThat(e).hasMessageThat().isEqualTo("foo");
+ }
+
+ @Test
+ public void assertThrowsConvertsUnexpectedExceptionTypeToAssertionError() {
+ try {
+ assertThrows(
+ IllegalStateException.class,
+ () -> {
+ throw new MyException("foo");
+ });
+ assert_().fail("expected AssertionError");
+ } catch (AssertionError e) {
+ assertThat(e).hasMessageThat().contains(IllegalStateException.class.getSimpleName());
+ assertThat(e).hasMessageThat().contains(MyException.class.getSimpleName());
+ assertThat(e).hasCauseThat().isInstanceOf(MyException.class);
+ assertThat(e).hasCauseThat().hasMessageThat().isEqualTo("foo");
+ }
+ }
+
+ @Test
+ public void assertThrowsThrowsAssertionErrorWhenNothingThrown() {
+ try {
+ assertThrows(MyException.class, () -> {});
+ assert_().fail("expected AssertionError");
+ } catch (AssertionError e) {
+ assertThat(e).hasMessageThat().contains(MyException.class.getSimpleName());
+ assertThat(e).hasCauseThat().isNull();
+ }
+ }
+}
