Merge pull request #44 from Yoast/develop

Release version 1.1.0

Author: jrfnl

.github/dependabot.yml

@@ -0,0 +1,29 @@
+# Dependabot configuration.
+#
+# Please see the documentation for all configuration options:
+# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  # Maintain dependencies for GitHub Actions.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "GH Actions:"
+    labels:
+      - "yoastcs/qa"
+
+  # Maintain dependencies for Composer.
+  - package-ecosystem: "composer"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5 # Set to 0 to (temporarily) disable.
+    versioning-strategy: "increase-if-necessary"
+    commit-message:
+      prefix: "Composer:"
+    labels:
+      - "yoastcs/qa"

.github/workflows/cs.yml

@@ -14,7 +14,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
 
       - name: Install PHP
         uses: shivammathur/setup-php@v2
@@ -26,7 +26,10 @@ jobs:
       # Install dependencies and handle caching in one go.
       # @link https://github.com/marketplace/actions/install-composer-dependencies
       - name: Install Composer dependencies
-        uses: "ramsey/composer-install@v1"
+        uses: "ramsey/composer-install@v2"
+        with:
+          # Bust the cache at least once a month - output format: YYYY-MM-DD.
+          custom-cache-suffix: $(date -u -d "-0 month -$(($(date +%d)-1)) days" "+%F")
 
       # Validate the composer.json file.
       # @link https://getcomposer.org/doc/03-cli.md#validate
@@ -35,8 +38,9 @@ jobs:
 
       # Check the code-style consistency of the PHP files.
       - name: Check PHP code style
-        continue-on-error: true
+        id: phpcs
         run: composer check-cs -- --report-full --report-checkstyle=./phpcs-report.xml
 
       - name: Show PHPCS results in PR
+        if: ${{ always() && steps.phpcs.outcome == 'failure' }}
         run: cs2pr ./phpcs-report.xml

.github/workflows/test.yml

@@ -14,20 +14,13 @@ jobs:
 
     strategy:
       matrix:
-        php: ['5.6', '7.0', '7.1', '7.2', '7.3', '7.4', '8.0']
-        experimental: [false]
-
-        include:
-          - php: '8.1'
-            experimental: true
+        php: ['5.6', '7.0', '7.1', '7.2', '7.3', '7.4', '8.0', '8.1', '8.2']
 
     name: "Tests: PHP ${{ matrix.php }}"
 
-    continue-on-error: ${{ matrix.experimental }}
-
     steps:
       - name: Checkout code
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
 
       - name: Install PHP
         uses: shivammathur/setup-php@v2
@@ -38,16 +31,11 @@ jobs:
 
       # Install dependencies and handle caching in one go.
       # @link https://github.com/marketplace/actions/install-composer-dependencies
-      - name: Install Composer dependencies for PHP < 8.1
-        if: ${{ matrix.php < 8.1 }}
-        uses: "ramsey/composer-install@v1"
-
-      # For PHP 8.1 and above, we need to install with ignore platform reqs as not all dependencies allow it yet.
-      - name: Install Composer dependencies for PHP >= 8.1
-        if: ${{ matrix.php >= 8.1 }}
-        uses: "ramsey/composer-install@v1"
+      - name: Install Composer dependencies
+        uses: "ramsey/composer-install@v2"
         with:
-          composer-options: --ignore-platform-reqs
+          # Bust the cache at least once a month - output format: YYYY-MM-DD.
+          custom-cache-suffix: $(date -u -d "-0 month -$(($(date +%d)-1)) days" "+%F")
 
       - name: Lint PHP files against parse errors
         run: composer lint

.phpcs.xml.dist

@@ -109,12 +109,18 @@
 
 	<!-- Allow for camelCase method and variable names to be more in line with PHPUnit and BrainMonkey. -->
 	<rule ref="WordPress.NamingConventions.ValidFunctionName">
+		<exclude-pattern>/src/BrainMonkey/bootstrap\.php$</exclude-pattern>
 		<exclude-pattern>/src/Helpers/*\.php$</exclude-pattern>
 	</rule>
 	<rule ref="WordPress.NamingConventions.ValidVariableName">
 		<exclude-pattern>/src/Helpers/*\.php$</exclude-pattern>
 	</rule>
 
+	<!-- This class is not a test double for the tests, but a _feature_ of this package. -->
+	<rule ref="Yoast.Files.TestDoubles">
+		<exclude-pattern>/src/BrainMonkey/Doubles/DummyTestDouble\.php$</exclude-pattern>
+	</rule>
+
 	<!-- Ignore word count for object names in tests. -->
 	<rule ref="Yoast.NamingConventions.ObjectNameDepth.MaxExceeded">
 		<exclude-pattern>/tests/*\.php$</exclude-pattern>
@@ -125,16 +131,4 @@
 		<exclude-pattern>/tests/*/Fixtures/*\.php$</exclude-pattern>
 	</rule>
 
-	<!--
-	#############################################################################
-	TEMPORARY ADJUSTMENTS
-	Adjustments which should be removed once the associated issue has been resolved.
-	#############################################################################
-	-->
-
-	<!-- PHPCS Bug: https://github.com/squizlabs/PHP_CodeSniffer/pull/3184 -->
-	<rule ref="PSR2.Namespaces.NamespaceDeclaration">
-		<exclude-pattern>/src/WPIntegration/(bootstrap-functions|Autoload)\.php$</exclude-pattern>
-	</rule>
-
 </ruleset>

CHANGELOG.md

@@ -9,6 +9,28 @@ This projects adheres to [Keep a CHANGELOG](http://keepachangelog.com/) and uses
 
 _Nothing yet._
 
+## [1.1.0] - 2022-11-17
+
+### Added
+* Helper functions for on-the-fly creation of opaque test doubles for unavailable classes for use with Mockery. PR [#40]
+    The default Mockery mocks for unavailable classes do not allow for the dynamic property deprecation in PHP 8.2, which can cause tests to error out.
+    These helper functions can be used to create test doubles which do allow for setting properties.
+    The helper functions can be called from within a test bootstrap or from within a test class.
+    For full details about these new functions, why they exist and how to use them, please see [the documentation in the README](https://github.com/Yoast/wp-test-utils#helpers-to-create-test-doubles-for-unavailable-classes).
+
+### Changed
+* The [BrainMonkey] dependency has been updated to require [version `^2.6.1`](https://github.com/Brain-WP/BrainMonkey/releases/tag/2.6.1) (was `^2.6.0`). PR  [#28]
+* The [PHPUnit Polyfills] dependency has been updated to require [version `^1.0.4`](https://github.com/Yoast/PHPUnit-Polyfills/releases/tag/1.0.4) (was `^1.0.1`). PRs [#28], [#41]
+* Composer: The package will now identify itself as a testing tool. PR [#36]
+* Verified PHP 8.2 compatibility.
+* General housekeeping.
+
+[#28]: https://github.com/Yoast/wp-test-utils/pull/28
+[#36]: https://github.com/Yoast/wp-test-utils/pull/36
+[#40]: https://github.com/Yoast/wp-test-utils/pull/40
+[#41]: https://github.com/Yoast/wp-test-utils/pull/41
+
+
 ## [1.0.0] - 2021-09-27
 
 WordPress 5.9 contains significant changes to the WordPress native test suite, which impacts **integration tests**.<br/>
@@ -86,6 +108,7 @@ Initial release.
 
 
 [Unreleased]: https://github.com/Yoast/wp-test-utils/compare/main...HEAD
+[1.1.0]: https://github.com/Yoast/wp-test-utils/compare/1.0.0...1.1.0
 [1.0.0]: https://github.com/Yoast/wp-test-utils/compare/0.2.2...1.0.0
 [0.2.2]: https://github.com/Yoast/wp-test-utils/compare/0.2.1...0.2.2
 [0.2.1]: https://github.com/Yoast/wp-test-utils/compare/0.2.0...0.2.1

README.md

@@ -5,7 +5,7 @@ WP Test Utils
 [![CS Build Status](https://github.com/Yoast/wp-test-utils/actions/workflows/cs.yml/badge.svg)](https://github.com/Yoast/wp-test-utils/actions/workflows/cs.yml)
 [![Test Build Status](https://github.com/Yoast/wp-test-utils/actions/workflows/test.yml/badge.svg)](https://github.com/Yoast/wp-test-utils/actions/workflows/test.yml)
 [![Minimum PHP Version](https://img.shields.io/packagist/php-v/yoast/wp-test-utils.svg?maxAge=3600)](https://packagist.org/packages/yoast/wp-test-utils)
-[![License: BSD3](https://poser.pugx.org/yoast/wp-test-utils/license)](https://github.com/Yoast/wp-test-utils/blob/master/LICENSE)
+[![License: BSD3](https://poser.pugx.org/yoast/wp-test-utils/license)](https://github.com/Yoast/wp-test-utils/blob/main/LICENSE)
 
 This library contains a set of utilities for running automated tests for WordPress plugins and themes.
 
@@ -16,6 +16,7 @@ This library contains a set of utilities for running automated tests for WordPre
         - [Basic `TestCase` for use with BrainMonkey](#basic-testcase-for-use-with-brainmonkey)
         - [Yoast TestCase for use with BrainMonkey](#yoast-testcase-for-use-with-brainmonkey)
         - [Bootstrap file for use with BrainMonkey](#bootstrap-file-for-use-with-brainmonkey)
+        - [Helpers to create test doubles for unavailable classes](#helpers-to-create-test-doubles-for-unavailable-classes)
     - [Utilities for running integration tests with WordPress](#utilities-for-running-integration-tests-with-wordpress)
         - [What these utilities solve](#what-these-utilities-solve)
         - [Basic `TestCase` for WordPress integration tests](#basic-testcase-for-wordpress-integration-tests)
@@ -32,9 +33,9 @@ Requirements
 * PHP 5.6 or higher.
 
 The following packages will be automatically required via Composer:
-* [PHPUnit Polyfills] 1.0.1 or higher.
+* [PHPUnit Polyfills] 1.0.4 or higher.
 * [PHPUnit] 5.7 - 9.x.
-* [BrainMonkey] 2.6.0 or higher.
+* [BrainMonkey] 2.6.1 or higher.
 
 
 Installation
@@ -67,7 +68,8 @@ Features of this `TestCase`:
     The BrainMonkey native functions create stubs which will apply basic HTML escaping if the stubbed function is an escaping function, like `esc_html__()`.<br/>
     The alternative implementations of these functions will create stubs which will return the original value without change. This makes creating tests easier as the `$expected` value does not need to account for the HTML escaping.<br/>
     _Note: the alternative implementation should be used selectively._
-5. Helper functions for setting expectations for generated output.
+5. Helper functions for [setting expectations for generated output](#yoastwptestutilshelpersescapeoutputhelper-trait).
+6. Helper functions for [creating "dummy" test doubles for unavailable classes](#helpers-to-create-test-doubles-for-unavailable-classes).
 
 **_Implementation example:_**
 ```php
@@ -168,6 +170,76 @@ require_once dirname( __DIR__ ) . '/vendor/autoload.php';
 To tell PHPUnit to use this bootstrap file, use `--bootstrap tests/bootstrap.php` on the command-line or add the `bootstrap="tests/bootstrap.php"` attribute to your `phpunit.xml.dist` file.
 
 
+#### Helpers to create test doubles for unavailable classes
+
+##### Why you may need to create test doubles for unavailable classes
+
+Typically a mock for an unavailable class is created using `Mockery::mock()` or `Mockery::mock( 'Unavailable' )`.
+
+When either the test or the code under test sets a property on such a mock, this will lead to a ["Creation of dynamic properties is deprecated" notice](https://wiki.php.net/rfc/deprecate_dynamic_properties) on PHP >= 8.2, which can cause tests to error out.
+
+If you know for sure the property being set on the mock is a declared property or a property supported via [magic methods](https://www.php.net/oop5.overloading#language.oop5.overloading.members) on the class which is being mocked, the _code under test_ will under normal circumstances never lead to this deprecation notice, but your tests now do.
+
+Primarly this is an issue with Mockery. A [question on how to handle this/to add support for this in Mockery itself](https://github.com/mockery/mockery/issues/1197) is open, but in the mean time a work-around is needed (if you're interested, have a read through the Mockery issue for details about alternative solutions and why those don't work as intended).
+
+##### How to use the functionality
+
+WP Test Utils offers three new utilities to solve this (as of version 1.1.0).
+* `Yoast\WPTestUtils\BrainMonkey\makeDoublesForUnavailableClasses( array $class_names )` for use from within a test bootstrap file.
+* `Yoast\WPTestUtils\BrainMonkey\TestCase::makeDoublesForUnavailableClasses( array $class_names )` and `Yoast\WPTestUtils\BrainMonkey\TestCase::makeDoubleForUnavailableClass( string $class_name )` for use from within a test class.
+
+These methods can be used to create one or more "fake" test double classes on the fly, which allow for setting (dynamic) properties.
+These "fake" test double classes are effectively aliases for `stdClass`.
+
+These methods are solely intended for classes which are unavailable during the test run and have no effect (at all!) on classes which _are_ available during the test run.
+
+For setting expectations on the "fake" test double, use `Mockery::mock( 'FakedClass' )`.
+
+**_Implementation example using the bootstrap function:_**
+
+You can create the "fake" test doubles for a complete test suite in one go in your test bootstrap file like so:
+
+```php
+<?php
+// File: tests/bootstrap.php
+require_once dirname( __DIR__ ) . '/vendor/yoast/wp-test-utils/src/BrainMonkey/bootstrap.php';
+require_once dirname( __DIR__ ) . '/vendor/autoload.php';
+
+Yoast\WPTestUtils\BrainMonkey\makeDoublesForUnavailableClasses( [ 'WP_Post', 'wpdb' ] );
+```
+
+**_Implementation example using these functions from within a test class:_**
+
+Alternatively, you can create the "fake" test double(s) last minute in each test class which needs them.
+
+```php
+<?php
+namespace PackageName\Tests;
+
+use Mockery;
+use WP_Post;
+use wpdb;
+use Yoast\WPTestUtils\BrainMonkey\TestCase;
+
+class FooTest extends TestCase {
+    protected function set_up_before_class() {
+        parent::set_up_before_class();
+        self::makeDoublesForUnavailableClasses( [ WP_Post::class, wpdb::class ] );
+        // or if only one class is needed:
+        self::makeDoubleForUnavailableClass( WP_Post::class );
+    }
+
+    public function testSomethingWhichUsesWpPost() {
+        $wp_post = Mockery::mock( WP_Post::class );
+        $wp_post->post_title = 'my test title';
+        $wp_post->post_type  = 'my_custom_type';
+
+        $this->assertSame( 'expected', \function_under_test( $wp_post ) );
+    }
+}
+```
+
+
 ### Utilities for running integration tests with WordPress
 
 #### What these utilities solve

composer.json

@@ -1,7 +1,7 @@
 {
     "name" : "yoast/wp-test-utils",
     "description" : "PHPUnit cross-version compatibility layer for testing plugins and themes build for WordPress",
-    "keywords" : [ "wordpress", "unit-testing", "integration-testing", "brainmonkey", "phpunit" ],
+    "keywords" : [ "wordpress", "unit-testing", "integration-testing", "brainmonkey", "phpunit", "testing" ],
     "license" : "BSD-3-Clause",
     "homepage": "https://github.com/Yoast/wp-test-utils/",
     "authors": [
@@ -21,11 +21,16 @@
     },
     "require" : {
         "php" : ">=5.6",
-        "yoast/phpunit-polyfills": "^1.0.1",
-        "brain/monkey": "^2.6.0"
+        "yoast/phpunit-polyfills": "^1.0.4",
+        "brain/monkey": "^2.6.1"
     },
     "require-dev" : {
-        "yoast/yoastcs": "^2.2.0"
+        "yoast/yoastcs": "^2.2.1"
+    },
+    "config": {
+        "allow-plugins": {
+            "dealerdirect/phpcodesniffer-composer-installer": true
+        }
     },
     "minimum-stability": "dev",
     "prefer-stable": true,
@@ -51,7 +56,7 @@
     },
     "scripts" : {
         "lint": [
-            "@php ./vendor/php-parallel-lint/php-parallel-lint/parallel-lint . -e php --exclude vendor --exclude .git"
+            "@php ./vendor/php-parallel-lint/php-parallel-lint/parallel-lint . -e php --show-deprecated --exclude vendor --exclude .git"
         ],
         "check-cs": [
             "@php ./vendor/squizlabs/php_codesniffer/bin/phpcs"

src/BrainMonkey/Doubles/DummyTestDouble.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace Yoast\WPTestUtils\BrainMonkey\Doubles;
+
+use stdClass;
+
+/**
+ * This is a "dummy" test double class for use with Mockery.
+ *
+ * This class allows to mock classes which are unavailable during the test run
+ * and on which properties need to be set, either from within the test or
+ * from within the code under test, by aliasing this class ahead of creating the mock.
+ *
+ * Mocking unavailable classes using an anonymous mock - `Mockery::mock()` or
+ * a mock for a specific named, but unavailable class - `Mockery::mock( 'Unavailable' )` -
+ * worked fine prior to PHP 8.2.
+ * However, PHP 8.2 deprecates the use of dynamic properties, which means that if
+ * either of the above code patterns is used and either the test or the code under
+ * test sets properties on the Mock, tests will throw deprecation notices and,
+ * depending on the value for the PHPUnit `convertDeprecationsToExceptions` configuration
+ * option, tests may show as errored.
+ *
+ * The "go to" pattern to solve this is to let the mock extend `stdClass`, but
+ * as `stdClass` always exists, the class will then identify as an instance of `stdClass`
+ * and no longer as an instance of the "Unavailable" class, which causes problems
+ * with code using type declarations of calls to `instanceof`.
+ *
+ * The other alternative would be to used `Mockery::namedMock()` or an alias mock, but
+ * both of these require each test using these to run in a separate process, which
+ * makes debugging of failing tests more complicated as well as making the test suite
+ * slower.
+ *
+ * Note: aliasing `stdClass` directly is not allowed in PHP, which is why this
+ * dummy test double class is put in place.
+ *
+ * @link https://github.com/mockery/mockery/issues/1197
+ */
+class DummyTestDouble extends stdClass {}

src/BrainMonkey/TestCase.php

@@ -6,6 +6,7 @@
 use Brain\Monkey\Functions;
 use Mockery\Adapter\Phpunit\MockeryPHPUnitIntegration;
 use Yoast\PHPUnitPolyfills\TestCases\TestCase as Polyfill_TestCase;
+use Yoast\WPTestUtils\BrainMonkey\Doubles\DummyTestDouble;
 use Yoast\WPTestUtils\Helpers\ExpectOutputHelper;
 
 /**
@@ -97,4 +98,54 @@ public function stubEscapeFunctions() {
 			]
 		);
 	}
+
+	/**
+	 * On the fly create a "fake" test double class, which allows for setting
+	 * (dynamic) properties on it.
+	 *
+	 * This method is solely intended for classes which are unavailable during
+	 * the test run.
+	 *
+	 * Typically a mock for an unavailable class is created using `Mockery::mock()`
+	 * or `Mockery::mock( 'Unavailable' )`.
+	 * When either the test or the code under test sets a property on such a mock,
+	 * this will lead to a "Creation of dynamic properties is deprecated"
+	 * notice on PHP >= 8.2, which can cause tests to error out.
+	 *
+	 * This method provides a work-around for this by on the fly creating a test double
+	 * for the unavailable class which allows for setting dynamic properties.
+	 *
+	 * This method can be called during the test bootstrapping, in test `set_up()`
+	 * methods or in the test itself (also see the linked helper functions).
+	 *
+	 * For setting expectations on the "fake" test double, use `Mockery::mock( 'FakedClass' )`.
+	 *
+	 * @see Yoast\WPTestUtils\BrainMonkey\makeDoublesForUnavailableClasses() Create one or more fake doubles during the test bootstrapping.
+	 * @see Yoast\WPTestUtils\BrainMonkey\TestCase::makeDoublesForUnavailableClasses() Create one or more fake doubles in one go.
+	 *
+	 * @param string $class_name Name of the class to be "faked".
+	 *
+	 * @return void
+	 */
+	public static function makeDoubleForUnavailableClass( $class_name ) {
+		if ( \class_exists( $class_name ) === false ) {
+			\class_alias( DummyTestDouble::class, $class_name );
+		}
+	}
+
+	/**
+	 * On the fly create multiple "fake" test double classes which allow for setting
+	 * (dynamic) properties on them.
+	 *
+	 * @see TestCase::makeDoubleForUnavailableClass()
+	 *
+	 * @param string[] $class_names List of class names to be "faked".
+	 *
+	 * @return void
+	 */
+	public static function makeDoublesForUnavailableClasses( array $class_names ) {
+		foreach ( $class_names as $class_name ) {
+			self::makeDoubleForUnavailableClass( $class_name );
+		}
+	}
 }

src/BrainMonkey/bootstrap.php

@@ -32,3 +32,17 @@
 if ( \function_exists( 'opcache_reset' ) ) {
 	\opcache_reset();
 }
+
+/**
+ * On the fly create multiple "fake" test double classes which allow for setting
+ * (dynamic) properties on them.
+ *
+ * @see TestCase::makeDoubleForUnavailableClass()
+ *
+ * @param string[] $class_names List of class names to be "faked".
+ *
+ * @return void
+ */
+function makeDoublesForUnavailableClasses( array $class_names ) {
+	TestCase::makeDoublesForUnavailableClasses( $class_names );
+}

tests/BrainMonkey/Fixtures/AnotherAvailableClass.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Yoast\WPTestUtils\Tests\BrainMonkey\Fixtures;
+
+/**
+ * Fixture to test the TestCase::makeDoubleForUnavailableClass() method.
+ */
+class AnotherAvailableClass {}

tests/BrainMonkey/Fixtures/AvailableClass.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Yoast\WPTestUtils\Tests\BrainMonkey\Fixtures;
+
+/**
+ * Fixture to test the TestCase::makeDoubleForUnavailableClass() method.
+ */
+class AvailableClass {}

tests/BrainMonkey/TestCaseTest.php

@@ -3,7 +3,13 @@
 namespace Yoast\WPTestUtils\Tests\BrainMonkey;
 
 use Brain\Monkey\Functions;
+use Mockery;
+use ReflectionClass;
+use UnavailableClassB;
+use Yoast\WPTestUtils\BrainMonkey\Doubles\DummyTestDouble;
 use Yoast\WPTestUtils\BrainMonkey\TestCase;
+use Yoast\WPTestUtils\Tests\BrainMonkey\Fixtures\AnotherAvailableClass;
+use Yoast\WPTestUtils\Tests\BrainMonkey\Fixtures\AvailableClass;
 
 /**
  * Basic test for the BrainMonkey TestCase setup.
@@ -54,6 +60,46 @@ public function testStubTranslationFunctions() {
 		);
 	}
 
+	/**
+	 * Verify the input dependent behaviour of the stub for the `_n()` function.
+	 *
+	 * @return void
+	 */
+	public function testStubTranslationFunctionsN() {
+		$this->stubTranslationFunctions();
+
+		$this->assertSame(
+			'chair',
+			\_n( 'chair', 'chairs', 1 ),
+			'Function stub for _n() does not return singular when number is 1'
+		);
+		$this->assertSame(
+			'chairs',
+			\_n( 'chair', 'chairs', 10 ),
+			'Function stub for _n() does not return plural when number is not 1'
+		);
+	}
+
+	/**
+	 * Verify the input dependent behaviour of the stub for the `_nx()` function.
+	 *
+	 * @return void
+	 */
+	public function testStubTranslationFunctionsNx() {
+		$this->stubTranslationFunctions();
+
+		$this->assertSame(
+			'table',
+			\_nx( 'table', 'tables', 1, 'test' ),
+			'Function stub for _nx() does not return singular when number is 1'
+		);
+		$this->assertSame(
+			'tables',
+			\_nx( 'table', 'tables', 10, 'test' ),
+			'Function stub for _nx() does not return plural when number is not 1'
+		);
+	}
+
 	/**
 	 * Verify the alternative translations function stubbing for functions echo-ing output is available
 	 * and that the functions echo out the input unchanged.
@@ -97,4 +143,170 @@ public function testStubEscapeFunctions() {
 			\esc_html( 'some <div>test</div>' )
 		);
 	}
+
+	/**
+	 * Verify that creating a test double aliases for an unavailable class works as expected.
+	 *
+	 * @return void
+	 */
+	public function testMakeDoubleForUnavailableClass() {
+		$this->assertFalse(
+			\class_exists( 'UnavailableClassA' ),
+			'Class UnavailableClassA appears to already exist'
+		);
+
+		$this->makeDoubleForUnavailableClass( 'UnavailableClassA' );
+
+		$this->assertTrue(
+			\class_exists( 'UnavailableClassA' ),
+			'Class UnavailableClassA still doesn\'t appear to exist'
+		);
+
+		$reflection_class = new ReflectionClass( 'UnavailableClassA' );
+		$this->assertSame(
+			DummyTestDouble::class,
+			$reflection_class->getName(),
+			'Class UnavailableClassA is not an alias for the DummyTestDouble class'
+		);
+	}
+
+	/**
+	 * Verify that properties can be set on a test double created using the `makeDoubleForUnavailableClass()` method.
+	 *
+	 * @return void
+	 */
+	public function testDoubleForUnavailableClassAllowsSettingProperties() {
+		$this->assertFalse(
+			\class_exists( UnavailableClassB::class ),
+			'Class UnavailableClassB appears to already exist'
+		);
+
+		static::makeDoubleForUnavailableClass( UnavailableClassB::class );
+
+		$unavailable_class           = new UnavailableClassB();
+		$unavailable_class->property = 10;
+
+		$this->assertTrue(
+			\property_exists( $unavailable_class, 'property' ),
+			'Property does not exist on test double'
+		);
+		$this->assertSame(
+			10,
+			$unavailable_class->property,
+			'Property value on test double does not match expected value'
+		);
+	}
+
+	/**
+	 * Verify that properties can be set on a mock of a test double, which was created
+	 * using the `makeDoubleForUnavailableClass()` method.
+	 *
+	 * @return void
+	 */
+	public function testDoubleForUnavailableClassAllowsSettingPropertiesWhenMocked() {
+		$this->assertFalse(
+			\class_exists( 'UnavailableClassC' ),
+			'Class UnavailableClassC appears to already exist'
+		);
+
+		self::makeDoubleForUnavailableClass( 'UnavailableClassC' );
+
+		$mock_of_unavailable_class           = Mockery::mock( 'UnavailableClassC' );
+		$mock_of_unavailable_class->property = 'test';
+
+		$this->assertTrue(
+			\property_exists( $mock_of_unavailable_class, 'property' ),
+			'Property does not exist on mocked test double'
+		);
+		$this->assertSame(
+			'test',
+			$mock_of_unavailable_class->property,
+			'Property value on mocked test double does not match expected value'
+		);
+	}
+
+	/**
+	 * Verify that no errors or warnings are thrown when a test double is requested for a class
+	 * which already exists, but wasn't loaded prior to the `makeDoubleForUnavailableClass()` function being called.
+	 *
+	 * @return void
+	 */
+	public function testMakeDoubleForAvailableClassNotYetInMemoryDoesNotCreateDouble() {
+		$this->assertFalse(
+			\class_exists( AvailableClass::class, false ), // Don't autoload this class!
+			'Class Yoast\WPTestUtils\Tests\BrainMonkey\Fixtures\AvailableClass already loaded, test is invalid'
+		);
+
+		$this->makeDoubleForUnavailableClass( AvailableClass::class );
+
+		$reflection_class = new ReflectionClass( AvailableClass::class );
+		$this->assertSame(
+			AvailableClass::class,
+			$reflection_class->getName(),
+			'The class does not point to the original, available class'
+		);
+	}
+
+	/**
+	 * Verify that no errors or warnings are thrown when a test double is requested for a class
+	 * which already exists and was already loaded prior to the `makeDoubleForUnavailableClass()` function being called.
+	 *
+	 * @return void
+	 */
+	public function testMakeDoubleForAvailableClassAlreadyInMemoryDoesNotCreateDouble() {
+		// Don't load via autoloader.
+		require_once __DIR__ . '/Fixtures/AnotherAvailableClass.php';
+
+		$this->assertTrue(
+			\class_exists( AnotherAvailableClass::class ),
+			'Class Yoast\WPTestUtils\Tests\BrainMonkey\Fixtures\AnotherAvailableClass doesn\'t exist prior to this test'
+		);
+
+		$this->makeDoubleForUnavailableClass( AnotherAvailableClass::class );
+
+		$reflection_class = new ReflectionClass( AnotherAvailableClass::class );
+		$this->assertSame(
+			AnotherAvailableClass::class,
+			$reflection_class->getName(),
+			'The class does not point to the original, available class'
+		);
+	}
+
+	/**
+	 * Verify that creating multiple test double aliases in one go works as expected.
+	 *
+	 * This test also safeguards that the functionality also works with namespaced class names.
+	 *
+	 * @return void
+	 */
+	public function testMakeDoublesForUnavailableClasses() {
+		$classes = [
+			'UnavailableClassX',
+			'My\\Namespace\\UnavailableClassY',
+			'Other\\UnavailableClassZ',
+		];
+
+		foreach ( $classes as $class_name ) {
+			$this->assertFalse(
+				\class_exists( $class_name ),
+				"Class $class_name appears to already exist"
+			);
+		}
+
+		self::makeDoublesForUnavailableClasses( $classes );
+
+		foreach ( $classes as $class_name ) {
+			$this->assertTrue(
+				\class_exists( $class_name ),
+				"Class $class_name still doesn't appear to exist"
+			);
+
+			$reflection_class = new ReflectionClass( $class_name );
+			$this->assertSame(
+				DummyTestDouble::class,
+				$reflection_class->getName(),
+				"Class $class_name is not an alias for the DummyTestDouble class"
+			);
+		}
+	}
 }

tests/BrainMonkey/YoastTestCaseTest.php

@@ -12,12 +12,336 @@
 class YoastTestCaseTest extends YoastTestCase {
 
 	/**
-	 * Verify that the additional stubs added in the setUp() are available.
+	 * Verify the behaviour of the `get_bloginfo()` stub.
+	 *
+	 * @dataProvider dataStubGetBlogInfo
+	 *
+	 * @param string $show     Value to pass to the function.
+	 * @param string $expected Expected return value.
+	 *
+	 * @return void
+	 */
+	public function testStubGetBlogInfo( $show, $expected ) {
+		$this->assertSame( $expected, \get_bloginfo( $show ) );
+	}
+
+	/**
+	 * Data provider.
+	 *
+	 * @return array
+	 */
+	public function dataStubGetBlogInfo() {
+		return [
+			// Explicit cases.
+			'charset' => [
+				'show'     => 'charset',
+				'expected' => 'UTF-8',
+			],
+			'language' => [
+				'show'     => 'language',
+				'expected' => 'English',
+			],
+			// Default behaviour, return input unchanged.
+			'name' => [
+				'show'     => 'name',
+				'expected' => 'name',
+			],
+			'pingback_url' => [
+				'show'     => 'pingback_url',
+				'expected' => 'pingback_url',
+			],
+		];
+	}
+
+	/**
+	 * Verify the behaviour of the `is_multisite()` stub, which should always return
+	 * false, except when the `WP_TESTS_MULTISITE` constant has been defined (which we're not testing).
 	 *
 	 * @return void
 	 */
-	public function testSetUp() {
-		$this->assertSame( 'https://www.example.org', \site_url() );
+	public function testStubIsMultisite() {
 		$this->assertFalse( \is_multisite() );
 	}
+
+	/**
+	 * Verify the behaviour of the `mysql2date()` stub, which should ignore the $format parameter completely.
+	 *
+	 * @return void
+	 */
+	public function testStubMysql2Date() {
+		$date = '2022-11-16 00:25:41';
+		$this->assertSame( $date, \mysql2date( 'U', $date ) );
+	}
+
+	/**
+	 * Verify the behaviour of the `number_format_i18n()` stub, which should return
+	 * the first parameter passed unchanged.
+	 *
+	 * @return void
+	 */
+	public function testStubNumberFormatI18n() {
+		$number = 123e7;
+		$this->assertSame( $number, \number_format_i18n( $number, 5 ) );
+	}
+
+	/**
+	 * Verify the behaviour of the `sanitize_text_field()` stub, which should return
+	 * the first parameter passed unchanged.
+	 *
+	 * @return void
+	 */
+	public function testStubSanitizeTextField() {
+		$text = 'some text < which <span> needs 	 sanitization    ';
+		$this->assertSame( $text, \sanitize_text_field( $text ) );
+	}
+
+	/**
+	 * Verify the behaviour of the `site_url()` stub, which should always return
+	 * the same value regardless of the passed parameters.
+	 *
+	 * @return void
+	 */
+	public function testStubSiteUrl() {
+		$this->assertSame( 'https://www.example.org', \site_url( 'some/path', 'rest' ) );
+	}
+
+	/**
+	 * Verify the behaviour of the `wp_kses_post()` stub, which should return
+	 * the first parameter passed unchanged.
+	 *
+	 * @return void
+	 */
+	public function testStubWpKsesPost() {
+		$text = 'some text < which <span> needs 	 sanitization    ';
+		$this->assertSame( $text, \wp_kses_post( $text ) );
+	}
+
+	/**
+	 * Verify the behaviour of the `wp_parse_args()` stub, which should return
+	 * a merged array.
+	 *
+	 * Note: not testing invalid input handling as these are function stubs to be used in tests,
+	 * so invalid input throwing errors is exactly the right behaviour.
+	 *
+	 * @dataProvider dataStubWpParseArgs
+	 *
+	 * @param array $settings Value for settings to pass to the function.
+	 * @param array $defaults Value for defaults to pass to the function.
+	 * @param array $expected Expected return value.
+	 *
+	 * @return void
+	 */
+	public function testStubWpParseArgs( $settings, $defaults, $expected ) {
+		$this->assertSame( $expected, \wp_parse_args( $settings, $defaults ) );
+	}
+
+	/**
+	 * Data provider.
+	 *
+	 * @return array
+	 */
+	public function dataStubWpParseArgs() {
+		return [
+			'two empty arrays' => [
+				'settings' => [],
+				'defaults' => [],
+				'expected' => [],
+			],
+			'settings array empty, defaults array has values' => [
+				'settings' => [
+					'setting A' => true,
+					'setting B' => 'string',
+					'setting C' => 10,
+				],
+				'defaults' => [],
+				'expected' => [
+					'setting A' => true,
+					'setting B' => 'string',
+					'setting C' => 10,
+				],
+			],
+			'settings array has values, defaults array empty' => [
+				'settings' => [],
+				'defaults' => [
+					'setting A' => true,
+					'setting B' => 'string',
+					'setting C' => 10,
+				],
+				'expected' => [
+					'setting A' => true,
+					'setting B' => 'string',
+					'setting C' => 10,
+				],
+			],
+			'both arrays have values' => [
+				'settings' => [
+					'setting A' => true,
+					'setting B' => 'string',
+					'setting C' => 10,
+					'setting E' => 'world!',
+				],
+				'defaults' => [
+					'setting A' => false,
+					'setting B' => 'default',
+					'setting C' => 0,
+					'setting D' => 'hello!',
+				],
+				'expected' => [
+					'setting A' => true,
+					'setting B' => 'string',
+					'setting C' => 10,
+					'setting D' => 'hello!',
+					'setting E' => 'world!',
+				],
+			],
+		];
+	}
+
+	/**
+	 * Verify the behaviour of the `wp_strip_all_tags()` stub, which should return
+	 * a merged array.
+	 *
+	 * Note: not testing invalid input handling as these are function stubs to be used in tests,
+	 * so invalid input throwing errors is exactly the right behaviour.
+	 *
+	 * @dataProvider dataStubWpStripAllTags
+	 *
+	 * @param string $text          Text to strip tags from.
+	 * @param bool   $remove_breaks Whether or not to strip line breaks and tabs.
+	 * @param string $expected      Expected return value.
+	 *
+	 * @return void
+	 */
+	public function testStubWpStripAllTags( $text, $remove_breaks, $expected ) {
+		$this->assertSame( $expected, \wp_strip_all_tags( $text, $remove_breaks ) );
+	}
+
+	/**
+	 * Data provider.
+	 *
+	 * @return array
+	 */
+	public function dataStubWpStripAllTags() {
+		return [
+			'Empty string' => [
+				'text'          => '',
+				'remove_breaks' => true,
+				'expected'      => '',
+			],
+			'Text containing script tag; no remove breaks' => [
+				// phpcs:ignore WordPress.WP.EnqueuedResources.NonEnqueuedScript -- Not relevant.
+				'text'          => '<script src="https://maliciousurl.com/">Click me
+									</script>',
+				'remove_breaks' => false,
+				'expected'      => '',
+			],
+			'Text containing other HTML tags; no remove breaks' => [
+				'text'          => '<span class="foo">my text</span>',
+				'remove_breaks' => false,
+				'expected'      => 'my text',
+			],
+			'Text surrounded by whitespace; no remove breaks' => [
+				'text'          => '  	  my text
+				',
+				'remove_breaks' => false,
+				'expected'      => 'my text',
+			],
+			'Text containing line breaks and tabs; no remove breaks' => [
+				'text'          => 'my
+					text
+					and more',
+				'remove_breaks' => false,
+				'expected'      => 'my
+					text
+					and more',
+			],
+			'Text containing line breaks and tabs; with remove breaks' => [
+				'text'          => 'my
+					text
+					and more',
+				'remove_breaks' => true,
+				'expected'      => 'my text and more',
+			],
+		];
+	}
+
+	/**
+	 * Verify the behaviour of the `wp_slash()` stub, which should return
+	 * the first parameter passed unchanged.
+	 *
+	 * @dataProvider dataStubWpSlash
+	 *
+	 * @param string $input Value to pass to the function.
+	 *
+	 * @return void
+	 */
+	public function testStubWpSlash( $input ) {
+		$this->assertSame( $input, \wp_slash( $input ) );
+	}
+
+	/**
+	 * Data provider.
+	 *
+	 * @return array
+	 */
+	public function dataStubWpSlash() {
+		return [
+			'string' => [
+				'input' => "O'Reilly?",
+			],
+			'array' => [
+				'input' => [
+					"O'Reilly?",
+					"aa\'bb",
+				],
+			],
+			'invalid input: null' => [
+				'input' => null,
+			],
+		];
+	}
+
+	/**
+	 * Verify the behaviour of the `wp_unslash()` stub, which should return
+	 * the first parameter without slashes if a string or the first parameter
+	 * unchanged if a non-string input was received.
+	 *
+	 * @dataProvider dataStubWpUnslash
+	 *
+	 * @param string $input    Value to pass to the function.
+	 * @param string $expected Expected return value.
+	 *
+	 * @return void
+	 */
+	public function testStubWpUnslash( $input, $expected ) {
+		$this->assertSame( $expected, \wp_unslash( $input ) );
+	}
+
+	/**
+	 * Data provider.
+	 *
+	 * @return array
+	 */
+	public function dataStubWpUnslash() {
+		return [
+			'string' => [
+				'input'    => "O\'Reilly\?",
+				'expected' => "O'Reilly?",
+			],
+			'array' => [
+				'input'    => [
+					"O\'Reilly?",
+					"aa\'bb",
+				],
+				'expected' => [
+					"O\'Reilly?",
+					"aa\'bb",
+				],
+			],
+			'invalid input: null' => [
+				'input'    => null,
+				'expected' => null,
+			],
+		];
+	}
 }