TestCase: add support for assert(Pre|Post)Conditions() fixture methods

Add cross-version handling of the `assertPreConditions()` and `assertPostConditions()` methods via snake_case methods to the `Yoast\PHPUnitPolyfills\TestCases\TestCase`.

Includes unit tests.

Includes improving the documentation within the class.

Note: these methods are not included in the `XTestCase` as there are no annotations available to handle these methods.

README.md

@@ -176,7 +176,7 @@ This library contains two basic `TestCase` options to overcome this issue.
 
 This `TestCase` overcomes the signature mismatch by having two versions. The correct one will be loaded depending on the PHPUnit version being used.
 
-When using this `TestCase`, if an individual test, or another `TestCase` which extends this `TestCase`, needs to overload any of the "fixture" methods, it should do so by using a snake_case variant of the original fixture method name, i.e. `set_up_before_class()`, `set_up()`, `tear_down()` and `tear_down_after_class()`.
+When using this `TestCase`, if an individual test, or another `TestCase` which extends this `TestCase`, needs to overload any of the "fixture" methods, it should do so by using a snake_case variant of the original fixture method name, i.e. `set_up_before_class()`, `set_up()`, `assert_pre_conditions()`, `assert_post_conditions()`, `tear_down()` and `tear_down_after_class()`.
 
 The snake_case methods will automatically be called by PHPUnit.
 
@@ -199,6 +199,18 @@ class MyTest extends TestCase {
         // Set up function mocks which need to be available for all tests in this class.
     }
 
+    protected function assert_pre_conditions() {
+        parent::assert_pre_conditions();
+
+        // Perform assertions shared by all tests of a test case (before the test).
+    }
+
+    protected function assert_post_conditions() {
+        // Performs assertions shared by all tests of a test case (after the test).
+
+        parent::assert_post_conditions();
+    }
+
     protected function tear_down() {
         // Any clean up needed related to `set_up()`.
 

src/TestCases/TestCasePHPUnitGte8.php

@@ -12,7 +12,8 @@
  * Basic test case for use with PHPUnit >= 8.
  *
  * This test case uses renamed (snakecase) methods for the `setUpBeforeClass()`, `setUp()`,
- * `tearDown()` and `tearDownAfterClass()` methods to get round the signature change in PHPUnit 8.
+ * `assertPreConditions()`, `assertPostConditions()`, `tearDown()` and `tearDownAfterClass()`
+ * methods to get round the signature change in PHPUnit 8.
  *
  * When using this TestCase, the snakecase method names need to be used to overload a fixture method.
  */
@@ -36,6 +37,8 @@ public static function setUpBeforeClass(): void {
 	}
 
 	/**
+	 * Sets up the fixture, for example, open a network connection.
+	 *
 	 * This method is called before each test.
 	 *
 	 * @return void
@@ -46,6 +49,32 @@ protected function setUp(): void {
 	}
 
 	/**
+	 * Performs assertions shared by all tests of a test case.
+	 *
+	 * This method is called before the execution of a test starts and after setUp() is called.
+	 *
+	 * @return void
+	 */
+	protected function assertPreConditions(): void {
+		parent::assertPreConditions();
+		$this->assert_pre_conditions();
+	}
+
+	/**
+	 * Performs assertions shared by all tests of a test case.
+	 *
+	 * This method is called before the execution of a test ends and before tearDown() is called.
+	 *
+	 * @return void
+	 */
+	protected function assertPostConditions(): void {
+		parent::assertPostConditions();
+		$this->assert_post_conditions();
+	}
+
+	/**
+	 * Tears down the fixture, for example, close a network connection.
+	 *
 	 * This method is called after each test.
 	 *
 	 * @return void
@@ -75,13 +104,35 @@ public static function tearDownAfterClass(): void {
 	public static function set_up_before_class() {}
 
 	/**
+	 * Sets up the fixture, for example, open a network connection.
+	 *
 	 * This method is called before each test.
 	 *
 	 * @return void
 	 */
 	protected function set_up() {}
 
 	/**
+	 * Performs assertions shared by all tests of a test case.
+	 *
+	 * This method is called before the execution of a test starts and after set_up() is called.
+	 *
+	 * @return void
+	 */
+	protected function assert_pre_conditions() {}
+
+	/**
+	 * Performs assertions shared by all tests of a test case.
+	 *
+	 * This method is called before the execution of a test ends and before tear_down() is called.
+	 *
+	 * @return void
+	 */
+	protected function assert_post_conditions() {}
+
+	/**
+	 * Tears down the fixture, for example, close a network connection.
+	 *
 	 * This method is called after each test.
 	 *
 	 * @return void

src/TestCases/TestCasePHPUnitLte7.php

@@ -16,7 +16,8 @@
  * Basic test case for use with PHPUnit <= 7.
  *
  * This test case uses renamed (snakecase) methods for the `setUpBeforeClass()`, `setUp()`,
- * `tearDown()` and `tearDownAfterClass()` methods to get round the signature change in PHPUnit 8.
+ * `assertPreConditions()`, `assertPostConditions()`, `tearDown()` and `tearDownAfterClass()`
+ * methods to get round the signature change in PHPUnit 8.
  *
  * When using this TestCase, the snakecase method names need to be used to overload a fixture method.
  */
@@ -44,6 +45,8 @@ public static function setUpBeforeClass() {
 	}
 
 	/**
+	 * Sets up the fixture, for example, open a network connection.
+	 *
 	 * This method is called before each test.
 	 *
 	 * @return void
@@ -54,6 +57,32 @@ protected function setUp() {
 	}
 
 	/**
+	 * Performs assertions shared by all tests of a test case.
+	 *
+	 * This method is called before the execution of a test starts and after setUp() is called.
+	 *
+	 * @return void
+	 */
+	protected function assertPreConditions() {
+		parent::assertPreConditions();
+		$this->assert_pre_conditions();
+	}
+
+	/**
+	 * Performs assertions shared by all tests of a test case.
+	 *
+	 * This method is called before the execution of a test ends and before tearDown() is called.
+	 *
+	 * @return void
+	 */
+	protected function assertPostConditions() {
+		parent::assertPostConditions();
+		$this->assert_post_conditions();
+	}
+
+	/**
+	 * Tears down the fixture, for example, close a network connection.
+	 *
 	 * This method is called after each test.
 	 *
 	 * @return void
@@ -83,13 +112,35 @@ public static function tearDownAfterClass() {
 	public static function set_up_before_class() {}
 
 	/**
+	 * Sets up the fixture, for example, open a network connection.
+	 *
 	 * This method is called before each test.
 	 *
 	 * @return void
 	 */
 	protected function set_up() {}
 
 	/**
+	 * Performs assertions shared by all tests of a test case.
+	 *
+	 * This method is called before the execution of a test starts and after set_up() is called.
+	 *
+	 * @return void
+	 */
+	protected function assert_pre_conditions() {}
+
+	/**
+	 * Performs assertions shared by all tests of a test case.
+	 *
+	 * This method is called before the execution of a test ends and before tear_down() is called.
+	 *
+	 * @return void
+	 */
+	protected function assert_post_conditions() {}
+
+	/**
+	 * Tears down the fixture, for example, close a network connection.
+	 *
 	 * This method is called after each test.
 	 *
 	 * @return void

src/TestCases/XTestCase.php

@@ -48,6 +48,8 @@ public static function setUpFixturesBeforeClass() {
 	}
 
 	/**
+	 * Sets up the fixture, for example, open a network connection.
+	 *
 	 * This method is called before each test.
 	 *
 	 * @before
@@ -59,6 +61,8 @@ public function setUpFixtures() {
 	}
 
 	/**
+	 * Tears down the fixture, for example, close a network connection.
+	 *
 	 * This method is called after each test.
 	 *
 	 * @after

tests/TestCases/TestCaseTest.php

@@ -29,6 +29,22 @@ class TestCaseTest extends TestCase {
 	 */
 	public static $before = 0;
 
+	/**
+	 * Keep track of how often the PHPUnit native `assertPreConditions()` method was called/
+	 * called the `assert_pre_conditions()` method.
+	 *
+	 * @var int
+	 */
+	public static $preConditions = 0;
+
+	/**
+	 * Keep track of how often the PHPUnit native `assertPostConditions()` method was called/
+	 * called the `assert_post_conditions()` method.
+	 *
+	 * @var int
+	 */
+	public static $postConditions = 0;
+
 	/**
 	 * Keep track of how often the PHPUnit native `tearDown()` method was called/
 	 * called the `tear_down()` method.
@@ -55,6 +71,24 @@ protected function set_up() {
 		++self::$before;
 	}
 
+	/**
+	 * This method is called before the execution of a test starts and after set_up() is called.
+	 *
+	 * @return void
+	 */
+	protected function assert_pre_conditions() {
+		++self::$preConditions;
+	}
+
+	/**
+	 * This method is called before the execution of a test ends and before tear_down() is called.
+	 *
+	 * @return void
+	 */
+	protected function assert_post_conditions() {
+		++self::$postConditions;
+	}
+
 	/**
 	 * This method is called after each test.
 	 *
@@ -71,9 +105,11 @@ protected function tear_down() {
 	 */
 	public static function tear_down_after_class() {
 		// Reset.
-		self::$beforeClass = 0;
-		self::$before      = 0;
-		self::$after       = 0;
+		self::$beforeClass    = 0;
+		self::$before         = 0;
+		self::$preConditions  = 0;
+		self::$postConditions = 0;
+		self::$after          = 0;
 	}
 
 	/**
@@ -83,13 +119,21 @@ public static function tear_down_after_class() {
 	 *
 	 * @dataProvider dataHaveFixtureMethodsBeenTriggered
 	 *
-	 * @param int $expectedBeforeClass Value expected for the $beforeClass property.
-	 * @param int $expectedBefore      Value expected for the $before property.
-	 * @param int $expectedAfter       Value expected for the $after property.
+	 * @param int $expectedBeforeClass    Value expected for the $beforeClass property.
+	 * @param int $expectedBefore         Value expected for the $before property.
+	 * @param int $expectedAfter          Value expected for the $after property.
+	 * @param int $expectedPreConditions  Value expected for the $preConditions property.
+	 * @param int $expectedPostConditions Value expected for the $postConditions property.
 	 *
 	 * @return void
 	 */
-	public function testHaveFixtureMethodsBeenTriggered( $expectedBeforeClass, $expectedBefore, $expectedAfter ) {
+	public function testHaveFixtureMethodsBeenTriggered(
+		$expectedBeforeClass,
+		$expectedBefore,
+		$expectedAfter,
+		$expectedPreConditions,
+		$expectedPostConditions
+	) {
 		$this->assertSame(
 			$expectedBeforeClass,
 			self::$beforeClass,
@@ -108,5 +152,18 @@ public function testHaveFixtureMethodsBeenTriggered( $expectedBeforeClass, $expe
 			"Failed to verify that tear_down() was triggered $expectedAfter time(s). Actual: "
 				. self::$after
 		);
+
+		$this->assertSame(
+			$expectedPreConditions,
+			self::$preConditions,
+			"Failed to verify that assert_pre_conditions() was triggered $expectedPreConditions time(s). Actual: "
+				. self::$preConditions
+		);
+		$this->assertSame(
+			$expectedPostConditions,
+			self::$postConditions,
+			"Failed to verify that assert_post_conditions() was triggered $expectedPostConditions time(s). Actual: "
+				. self::$postConditions
+		);
 	}
 }

tests/TestCases/TestCaseTestTrait.php

@@ -17,9 +17,9 @@ trait TestCaseTestTrait {
 	 */
 	public function dataHaveFixtureMethodsBeenTriggered() {
 		return [
-			[ 1, 1, 0 ],
-			[ 1, 2, 1 ],
-			[ 1, 3, 2 ],
+			[ 1, 1, 0, 1, 0 ],
+			[ 1, 2, 1, 2, 1 ],
+			[ 1, 3, 2, 3, 2 ],
 		];
 	}