Document how to test for failures with the EngineTestKit in User Guide

Issue: #1621

documentation/src/docs/asciidoc/user-guide/testkit.adoc

@@ -88,10 +88,32 @@ include::{testDir}/example/testkit/EngineTestKitSkippedMethodDemo.java[tags=user
 ----
 <1> Select the JUnit Jupiter `TestEngine`.
 <2> Select the `skippedTest()` method in the <<testkit-engine-ExampleTestCase,
-`ExampleTestCase`>> test class.
+    `ExampleTestCase`>> test class.
 <3> Execute the `TestPlan`.
 <4> Filter by _test_ events.
 <5> Save the _test_ `Events` to a local variable.
 <6> Optionally assert the expected statistics.
 <7> Assert that the recorded _test_ events contain exactly one skipped test named
-`skippedTest` with `"for demonstration purposes"` as the _reason_.
+    `skippedTest` with `"for demonstration purposes"` as the _reason_.
+
+If we want to verify the type of exception thrown from the `failingTest()` method in
+<<testkit-engine-ExampleTestCase, `ExampleTestCase`>>, we can do that as follows.
+
+[NOTE]
+====
+For details on what _conditions_ are available for use with AssertJ assertions against
+events and execution results, consult the Javadoc for `{EventConditions}` and
+`{TestExecutionResultConditions}`, respectively.
+====
+
+[source,java,indent=0]
+----
+include::{testDir}/example/testkit/EngineTestKitFailedMethodDemo.java[tags=user_guide]
+----
+<1> Select the JUnit Jupiter `TestEngine`.
+<2> Select the <<testkit-engine-ExampleTestCase, `ExampleTestCase`>> test class.
+<3> Execute the `TestPlan`.
+<4> Filter by _test_ events.
+<5> Assert that the recorded _test_ events contain exactly one failing test named
+    `failingTest` with an exception of type `ArithmeticException` and an error message
+    equal to `"/ by zero"`.

documentation/src/test/java/example/testkit/EngineTestKitFailedMethodDemo.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2015-2018 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v2.0 which
+ * accompanies this distribution and is available at
+ *
+ * http://www.eclipse.org/legal/epl-v20.html
+ */
+
+package example.testkit;
+
+import static org.assertj.core.api.Assertions.allOf;
+import static org.junit.platform.engine.discovery.DiscoverySelectors.selectClass;
+import static org.junit.platform.testkit.engine.EventConditions.event;
+import static org.junit.platform.testkit.engine.EventConditions.finishedWithFailure;
+import static org.junit.platform.testkit.engine.EventConditions.test;
+import static org.junit.platform.testkit.engine.TestExecutionResultConditions.isA;
+import static org.junit.platform.testkit.engine.TestExecutionResultConditions.message;
+
+import example.ExampleTestCase;
+
+import org.junit.jupiter.api.Test;
+import org.junit.platform.testkit.engine.EngineTestKit;
+
+class EngineTestKitFailedMethodDemo {
+
+	@Test
+	void verifyJupiterMethodFailed() {
+		EngineTestKit.engine("junit-jupiter") // <1>
+				.selectors(selectClass(ExampleTestCase.class)) // <2>
+				.execute() // <3>
+				.tests() // <4>
+				.assertThatEvents().haveExactly(1, // <5>
+					event(test("failingTest"),
+						finishedWithFailure(allOf(isA(ArithmeticException.class), message("/ by zero")))));
+	}
+
+}
+// end::user_guide[]
+// @formatter:on