Create assertions for Pioneer (#232 / #245)

In 0b79db8 (#6 / #218), we moved all assertion-like methods onto the
`ExecutionResults` class even though that wasn't a good fit. The
intention was to collect all such methods to then more easily replace
them with proper AssertJ-like assertions that we needed to write
ourselves.

This change implements these methods. The API is pretty good already,
but we expect that after using it for a while the experience with it
as well as new use cases may lead to further changes (see #298).

Closes: #232
PR: #245

CONTRIBUTING.md

@@ -116,6 +116,16 @@ All tests shall use [AssertJ](https://joel-costigliola.github.io/assertj/)'s ass
 
 Yes, use it even if Jupiter's assertions are as good or better (c.f. `assertTrue(bool)` vs `assertThat(bool).isTrue()`) - that will spare us the discussion which assertion to use in a specific case.
 
+Pioneer now has its own assertions for asserting not directly executed tests.
+This means asserting `ExecutionResults`.
+We can divide those kinds of assertions into two categories: test case assertions and test suite assertions.
+ - Test case assertions are the ones where you assert a single test, e.g.: it failed with an exception or succeeded.
+ For those, use the assertions that being with `hasSingle...`, e.g.: `hasSingleSucceededTest()`.
+ - Test suite assertions are the ones where you assert multiple tests and their outcomes, e.g.: three tests started, two failed, one succeeded.
+ For those, use the assertions that being with `hasNumberOf...`, e.g.: `hasNumberOfFailedTests(1)`.
+
+Do not mix the two - while technically correct (meaning you _can_ write `hasNumberOfFailedTests(3).hasSingleSucceededTest()`) it is better to handle them separately.
+
 ### Documentation
 
 There are several aspects of this project's documentation.

src/test/java/org/junitpioneer/jupiter/DefaultLocaleTests.java

@@ -13,6 +13,7 @@
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.junitpioneer.testkit.PioneerTestKit.executeTestClass;
 import static org.junitpioneer.testkit.PioneerTestKit.executeTestMethod;
+import static org.junitpioneer.testkit.assertion.PioneerAssert.assertThat;
 
 import java.util.Locale;
 
@@ -98,7 +99,7 @@ void setUp() {
 		void shouldExecuteTestsWithConfiguredLocale() {
 			ExecutionResults results = executeTestClass(ClassLevelTestCase.class);
 
-			assertThat(results.numberOfSucceededTests()).isEqualTo(2);
+			assertThat(results).hasNumberOfSucceededTests(2);
 		}
 
 		@AfterEach
@@ -177,7 +178,9 @@ void shouldFailWhenNothingIsConfigured() {
 				ExecutionResults results = executeTestMethod(MethodLevelInitializationFailureTestCase.class,
 					"shouldFailMissingConfiguration");
 
-				results.assertTestFailedWithThrowable(ExtensionConfigurationException.class);
+				assertThat(results)
+						.hasSingleFailedTest()
+						.withExceptionInstanceOf(ExtensionConfigurationException.class);
 			}
 
 			@Test
@@ -186,7 +189,9 @@ void shouldFailWhenVariantIsSetButCountryIsNot() {
 				ExecutionResults results = executeTestMethod(MethodLevelInitializationFailureTestCase.class,
 					"shouldFailMissingCountry");
 
-				results.assertTestFailedWithExtensionConfigurationException();
+				assertThat(results)
+						.hasSingleFailedTest()
+						.withExceptionInstanceOf(ExtensionConfigurationException.class);
 			}
 
 			@Test
@@ -195,7 +200,9 @@ void shouldFailWhenLanguageTagAndLanguageIsSet() {
 				ExecutionResults results = executeTestMethod(MethodLevelInitializationFailureTestCase.class,
 					"shouldFailLanguageTagAndLanguage");
 
-				results.assertTestFailedWithExtensionConfigurationException();
+				assertThat(results)
+						.hasSingleFailedTest()
+						.withExceptionInstanceOf(ExtensionConfigurationException.class);
 			}
 
 			@Test
@@ -204,7 +211,9 @@ void shouldFailWhenLanguageTagAndCountryIsSet() {
 				ExecutionResults results = executeTestMethod(MethodLevelInitializationFailureTestCase.class,
 					"shouldFailLanguageTagAndCountry");
 
-				results.assertTestFailedWithExtensionConfigurationException();
+				assertThat(results)
+						.hasSingleFailedTest()
+						.withExceptionInstanceOf(ExtensionConfigurationException.class);
 			}
 
 			@Test
@@ -213,7 +222,9 @@ void shouldFailWhenLanguageTagAndVariantIsSet() {
 				ExecutionResults results = executeTestMethod(MethodLevelInitializationFailureTestCase.class,
 					"shouldFailLanguageTagAndVariant");
 
-				results.assertTestFailedWithExtensionConfigurationException();
+				assertThat(results)
+						.hasSingleFailedTest()
+						.withExceptionInstanceOf(ExtensionConfigurationException.class);
 			}
 
 		}
@@ -227,8 +238,9 @@ class ClassLevel {
 			void shouldFailWhenVariantIsSetButCountryIsNot() {
 				ExecutionResults results = executeTestClass(ClassLevelInitializationFailureTestCase.class);
 
-				assertThat(results.numberOfFailedContainers()).isEqualTo(1);
-				assertThat(results.firstFailuresThrowable()).isInstanceOf(ExtensionConfigurationException.class);
+				assertThat(results)
+						.hasSingleFailedContainer()
+						.withExceptionInstanceOf(ExtensionConfigurationException.class);
 			}
 
 		}

src/test/java/org/junitpioneer/jupiter/DefaultTimeZoneTests.java

@@ -14,6 +14,7 @@
 import static org.assertj.core.api.Assertions.fail;
 import static org.junitpioneer.testkit.PioneerTestKit.executeTestClass;
 import static org.junitpioneer.testkit.PioneerTestKit.executeTestMethod;
+import static org.junitpioneer.testkit.assertion.PioneerAssert.assertThat;
 
 import java.util.TimeZone;
 
@@ -68,11 +69,11 @@ void doesNothingWhenAnnotationNotPresent() {
 		void throwsWhenConfigurationIsBad() {
 			ExecutionResults results = executeTestMethod(BadMethodLevelConfigurationTestCase.class, "badConfiguration");
 
-			assertThat(results.numberOfFailedTests()).isEqualTo(1);
-			assertThat(results.firstFailuresThrowable()).isExactlyInstanceOf(ExtensionConfigurationException.class);
-			assertThat(results.firstFailuresThrowableMessage())
-					.doesNotContain("should never execute")
-					.contains("@DefaultTimeZone not configured correctly.");
+			assertThat(results)
+					.hasSingleFailedTest()
+					.withExceptionInstanceOf(ExtensionConfigurationException.class)
+					.hasMessageNotContaining("should never execute")
+					.hasMessageContaining("@DefaultTimeZone not configured correctly.");
 		}
 
 		@DefaultTimeZone("GMT")
@@ -112,25 +113,27 @@ void setUp() {
 		void shouldExecuteTestsWithConfiguredTimeZone() {
 			ExecutionResults results = executeTestClass(ClassLevelTestCase.class);
 
-			assertThat(results.numberOfSucceededTests()).isEqualTo(2);
+			assertThat(results).hasNumberOfSucceededTests(2);
 		}
 
 		@Test
 		@DisplayName("throws when configuration is bad")
 		void shouldThrowWithBadConfiguration() {
 			ExecutionResults results = executeTestClass(BadClassLevelConfigurationTestCase.class);
 
-			assertThat(results.numberOfStartedTests()).isEqualTo(0);
-			assertThat(results.firstFailuresThrowable()).isExactlyInstanceOf(ExtensionConfigurationException.class);
-			assertThat(results.firstFailuresThrowableMessage()).contains("@DefaultTimeZone not configured correctly.");
+			assertThat(results).hasNumberOfStartedTests(0);
+			assertThat(results)
+					.hasSingleFailedContainer()
+					.withExceptionInstanceOf(ExtensionConfigurationException.class)
+					.hasMessageContaining("@DefaultTimeZone not configured correctly.");
 		}
 
 		@Test
 		@DisplayName("does not throw when explicitly set to GMT")
 		void shouldNotThrowForExplicitGmt() {
 			ExecutionResults results = executeTestClass(ExplicitGmtClassLevelTestCase.class);
 
-			assertThat(results.numberOfSucceededTests()).isEqualTo(1);
+			assertThat(results).hasSingleSucceededTest();
 		}
 
 		@AfterEach

src/test/java/org/junitpioneer/jupiter/EnvironmentVariableExtensionTests.java

@@ -15,6 +15,7 @@
 import static org.junitpioneer.jupiter.EnvironmentVariableExtension.WARNING_VALUE;
 import static org.junitpioneer.testkit.PioneerTestKit.executeTestClass;
 import static org.junitpioneer.testkit.PioneerTestKit.executeTestMethod;
+import static org.junitpioneer.testkit.assertion.PioneerAssert.assertThat;
 
 import org.junit.jupiter.api.AfterAll;
 import org.junit.jupiter.api.BeforeAll;
@@ -23,6 +24,7 @@
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtensionConfigurationException;
 import org.junitpioneer.testkit.ExecutionResults;
 
 @DisplayName("EnvironmentVariable extension")
@@ -209,7 +211,7 @@ void shouldFailWhenClearAndSetSameEnvironmentVariable() {
 			ExecutionResults results = executeTestMethod(MethodLevelInitializationFailureTestCase.class,
 				"shouldFailWhenClearAndSetSameEnvironmentVariable");
 
-			results.assertTestFailedWithExtensionConfigurationException();
+			assertThat(results).hasSingleFailedTest().withExceptionInstanceOf(ExtensionConfigurationException.class);
 		}
 
 		@Test
@@ -221,7 +223,7 @@ void shouldFailWhenClearSameEnvironmentVariableTwice() {
 			ExecutionResults results = executeTestMethod(MethodLevelInitializationFailureTestCase.class,
 				"shouldFailWhenClearSameEnvironmentVariableTwice");
 
-			results.assertTestFailedWithExtensionConfigurationException();
+			assertThat(results).hasSingleFailedTest().withExceptionInstanceOf(ExtensionConfigurationException.class);
 		}
 
 		@Test
@@ -230,7 +232,7 @@ void shouldFailWhenSetSameEnvironmentVariableTwice() {
 			ExecutionResults results = executeTestMethod(MethodLevelInitializationFailureTestCase.class,
 				"shouldFailWhenSetSameEnvironmentVariableTwice");
 
-			results.assertTestFailedWithExtensionConfigurationException();
+			assertThat(results).hasSingleFailedTest().withExceptionInstanceOf(ExtensionConfigurationException.class);
 		}
 
 	}
@@ -247,21 +249,21 @@ void resetWarning() {
 		void shouldNotReportWarningIfExtensionNotUsed() {
 			ExecutionResults results = executeTestMethod(ReportWarningTestCases.class, "testWithoutExtension");
 
-			assertThat(results.reportEntries()).hasSize(0);
+			assertThat(results).hasNoReportEntries();
 		}
 
 		@Test
 		void shouldReportWarningIfExtensionUsed() {
 			ExecutionResults results = executeTestMethod(ReportWarningTestCases.class, "testWithExtension");
 
-			assertThat(results.singleReportEntry()).isEqualTo(TestUtils.entryOf(WARNING_KEY, WARNING_VALUE));
+			assertThat(results).hasSingleReportEntry().withKeyAndValue(WARNING_KEY, WARNING_VALUE);
 		}
 
 		@Test
 		void shouldReportWarningExactlyOnce() {
 			ExecutionResults results = executeTestClass(ReportWarningTestCases.class);
 
-			assertThat(results.reportEntries()).hasSize(1);
+			assertThat(results).hasSingleReportEntry();
 		}
 
 	}