Closes #35: Remove WP Rocket coupling from generic package

README.md

@@ -5,7 +5,6 @@ This reusable package bootstraps our PHPUnit unit and integration tests. It incl
 - bootstrapping for both Unit and Integration tests
 - `phpunit.xml.dist` for each test suite
 - `TestCase` for each test suite
-- Common polyfill functions
 
 This means your repo only needs its tests. w00t!
 

Tests/Fixtures/ApiTrait/getApiCredential.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+return [
+	'environment variable is set'                => [
+		'env_name'             => 'WPMEDIA_PHPUNIT_TEST_CREDENTIAL',
+		'env_value'            => 'from_env',
+		'config_filename'      => null,
+		'config_file_contents' => null,
+		'credential_name'      => 'WPMEDIA_PHPUNIT_TEST_CREDENTIAL',
+		'expected'             => 'from_env',
+	],
+
+	'no config file is set'                      => [
+		'env_name'             => null,
+		'env_value'            => null,
+		'config_filename'      => null,
+		'config_file_contents' => null,
+		'credential_name'      => 'WPMEDIA_PHPUNIT_TEST_UNSET_CONSTANT',
+		'expected'             => '',
+	],
+
+	'config file is not readable'                => [
+		'env_name'             => null,
+		'env_value'            => null,
+		'config_filename'      => 'missing-credentials.php',
+		'config_file_contents' => null,
+		'credential_name'      => 'WPMEDIA_PHPUNIT_TEST_UNSET_CONSTANT',
+		'expected'             => '',
+	],
+
+	'constant is defined in the config file'     => [
+		'env_name'             => null,
+		'env_value'            => null,
+		'config_filename'      => 'credentials.php',
+		'config_file_contents' => "<?php define( 'WPMEDIA_PHPUNIT_TEST_CONSTANT', 'from_constant' );",
+		'credential_name'      => 'WPMEDIA_PHPUNIT_TEST_CONSTANT',
+		'expected'             => 'from_constant',
+	],
+
+	'constant is not defined in the config file' => [
+		'env_name'             => null,
+		'env_value'            => null,
+		'config_filename'      => 'empty-credentials.php',
+		'config_file_contents' => '<?php // No constants defined here.',
+		'credential_name'      => 'WPMEDIA_PHPUNIT_TEST_UNDEFINED_CONSTANT',
+		'expected'             => '',
+	],
+];

Tests/Unit/ApiTrait/ApiTraitTestDouble.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WPMedia\PHPUnit\Tests\Unit\ApiTrait;
+
+use WPMedia\PHPUnit\Integration\ApiTrait;
+
+/**
+ * Exposes the otherwise protected members of ApiTrait for the tests to drive.
+ */
+class ApiTraitTestDouble {
+	use ApiTrait;
+
+	/**
+	 * Name of the API credentials config file, if applicable.
+	 *
+	 * @var string|null
+	 */
+	protected static $api_credentials_config_file;
+
+	/**
+	 * Points the trait at the config file to load for the current scenario.
+	 *
+	 * @param string $path_to_config Path to the directory holding the config file.
+	 * @param string $config_file    Name of the config file.
+	 *
+	 * @return void
+	 */
+	public static function set_config_file( $path_to_config, $config_file ) {
+		self::pathToApiCredentialsConfigFile( $path_to_config );
+
+		static::$api_credentials_config_file = $config_file;
+	}
+
+	/**
+	 * Gets the credential's value for the given name.
+	 *
+	 * @param string $name Name of the environment variable or constant to find.
+	 *
+	 * @return string returns the value if available; else an empty string.
+	 */
+	public static function get_credential( $name ) {
+		return static::getApiCredential( $name );
+	}
+
+	/**
+	 * Resets the trait's static state so each scenario starts from a clean slate.
+	 *
+	 * @return void
+	 */
+	public static function reset() {
+		self::$path_to_config                = null;
+		static::$api_credentials_config_file = null;
+	}
+}

Tests/Unit/ApiTrait/getApiCredential.php

@@ -0,0 +1,93 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WPMedia\PHPUnit\Tests\Unit\ApiTrait;
+
+use WPMedia\PHPUnit\Unit\TestCase;
+
+/**
+ * Tests WPMedia\PHPUnit\Integration\ApiTrait::getApiCredential().
+ *
+ * @covers WPMedia\PHPUnit\Integration\ApiTrait::getApiCredential
+ * @group  ApiTrait
+ */
+class Test_GetApiCredential extends TestCase {
+
+	/**
+	 * Path to the temporary directory used to hold the config file for the scenarios that need one.
+	 *
+	 * @var string
+	 */
+	private $tmp_dir;
+
+	/**
+	 * Resets the test double and prepares a scratch directory before each scenario.
+	 *
+	 * @return void
+	 */
+	protected function set_up() {
+		parent::set_up();
+
+		ApiTraitTestDouble::reset();
+
+		$this->tmp_dir = sys_get_temp_dir() . '/wpmedia-phpunit-apitrait-' . uniqid();
+
+		mkdir( $this->tmp_dir ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_mkdir -- WP_Filesystem is not available in the Unit test suite; this creates a throwaway scratch directory.
+	}
+
+	/**
+	 * Removes the scratch directory after each scenario.
+	 *
+	 * @return void
+	 */
+	protected function tear_down() {
+		array_map( 'unlink', glob( "{$this->tmp_dir}/*.php" ) );
+		rmdir( $this->tmp_dir ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_rmdir -- WP_Filesystem is not available in the Unit test suite; this removes the throwaway scratch directory.
+
+		parent::tear_down();
+	}
+
+	/**
+	 * Asserts that getApiCredential() returns the expected value for each scenario.
+	 *
+	 * @dataProvider getApiCredentialDataProvider
+	 *
+	 * @param string|null $env_name             Name of the environment variable to set before running the scenario, if any.
+	 * @param string|null $env_value            Value to set the environment variable to, if any.
+	 * @param string|null $config_filename      Name of the config file to point the trait at, if any.
+	 * @param string|null $config_file_contents Contents to write to the config file before running the scenario, if any.
+	 * @param string      $credential_name      Name of the environment variable or constant to look up.
+	 * @param string      $expected             Expected return value.
+	 *
+	 * @return void
+	 */
+	public function testShouldReturnTheExpectedCredential( $env_name, $env_value, $config_filename, $config_file_contents, $credential_name, $expected ) {
+		if ( null !== $env_name ) {
+			putenv( "{$env_name}={$env_value}" ); // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.runtime_configuration_putenv -- Test-only: simulates the environment variable that getApiCredential() reads via getenv().
+		}
+
+		if ( null !== $config_filename ) {
+			if ( null !== $config_file_contents ) {
+				file_put_contents( $this->tmp_dir . '/' . $config_filename, $config_file_contents ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_file_put_contents -- WP_Filesystem is not available in the Unit test suite; this writes the throwaway config file fixture.
+			}
+
+			ApiTraitTestDouble::set_config_file( $this->tmp_dir . '/', $config_filename );
+		}
+
+		$this->assertSame( $expected, ApiTraitTestDouble::get_credential( $credential_name ) );
+
+		if ( null !== $env_name ) {
+			putenv( $env_name ); // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.runtime_configuration_putenv -- Test-only: unsets the environment variable set above.
+		}
+	}
+
+	/**
+	 * Provides the scenarios from the Fixtures directory.
+	 *
+	 * @return array test data.
+	 */
+	public function getApiCredentialDataProvider() {
+		return $this->getTestData( __DIR__, 'getApiCredential' );
+	}
+}

phpcs.xml.dist

@@ -11,11 +11,17 @@
 	opportunistically, and widen this to the full source tree (src/ plus Tests/) once the
 	codebase is fully compliant.
 	-->
+	<file>src/Integration/ApiTrait.php</file>
 	<file>src/Integration/HttpRequestTrait.php</file>
+	<file>src/TestCaseTrait.php</file>
+	<file>src/Unit/TestCase.php</file>
 	<file>src/VirtualFilesystemTestTrait.php</file>
+	<file>Tests/Fixtures/ApiTrait/getApiCredential.php</file>
+	<file>Tests/Fixtures/VirtualFilesystemTestTrait/getDefaultVfs.php</file>
+	<file>Tests/Unit/ApiTrait/ApiTraitTestDouble.php</file>
+	<file>Tests/Unit/ApiTrait/getApiCredential.php</file>
 	<file>Tests/Unit/VirtualFilesystemDirect/TestCase.php</file>
 	<file>Tests/Unit/VirtualFilesystemTestTrait/getDefaultVfs.php</file>
-	<file>Tests/Fixtures/VirtualFilesystemTestTrait/getDefaultVfs.php</file>
 	<exclude-pattern>vendor/*</exclude-pattern>
 	<arg value="sp"/>
 	<arg name="colors"/>

phpstan-baseline.neon

@@ -54,12 +54,6 @@ parameters:
 			count: 1
 			path: src/Integration/AdminTestCase.php
 
-		-
-			rawMessage: 'Method WPMedia\PHPUnit\Integration\AjaxTestCase::getApiCredential() should return string but returns bool.'
-			identifier: return.type
-			count: 1
-			path: src/Integration/AjaxTestCase.php
-
 		-
 			rawMessage: 'Class WP_REST_Request referenced with incorrect case: WP_Rest_Request.'
 			identifier: class.nameCase
@@ -84,12 +78,6 @@ parameters:
 			count: 1
 			path: src/Integration/RESTfulTestCase.php
 
-		-
-			rawMessage: 'Method WPMedia\PHPUnit\Integration\RESTfulTestCase::getApiCredential() should return string but returns bool.'
-			identifier: return.type
-			count: 1
-			path: src/Integration/RESTfulTestCase.php
-
 		-
 			rawMessage: Variable $wp_rest_server in PHPDoc tag @var does not exist.
 			identifier: varTag.variableNotFound

phpstan.neon.dist

@@ -13,7 +13,6 @@ parameters:
         - src/bootstrap-functions.php
         - src/Integration/
         - src/Unit/
-        - src/Fixtures/
         - Tests/
     scanFiles:
         - vendor/php-stubs/wordpress-stubs/wordpress-stubs.php

src/Integration/ApiTrait.php

@@ -1,11 +1,26 @@
 <?php
 
+declare(strict_types=1);
+
 namespace WPMedia\PHPUnit\Integration;
 
 trait ApiTrait {
+
+	/**
+	 * Path to the directory holding the local API credentials config file.
+	 *
+	 * @var string|null
+	 */
 	protected static $path_to_config;
 
-	protected static function pathToApiCredentialsConfigFile( $path ) {
+	/**
+	 * Sets the path to the directory holding the local API credentials config file.
+	 *
+	 * @param string $path Path to the directory holding the config file.
+	 *
+	 * @return void
+	 */
+	protected static function pathToApiCredentialsConfigFile( $path ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid -- Public API method; renaming would be a breaking change for consumers.
 		self::$path_to_config = $path;
 	}
 
@@ -16,7 +31,7 @@ protected static function pathToApiCredentialsConfigFile( $path ) {
 	 *
 	 * @return string returns the value if available; else an empty string.
 	 */
-	protected static function getApiCredential( $name ) {
+	protected static function getApiCredential( $name ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid -- Public API method; renaming would be a breaking change for consumers.
 		$var = getenv( $name );
 		if ( ! empty( $var ) ) {
 			return $var;
@@ -34,6 +49,10 @@ protected static function getApiCredential( $name ) {
 		// This file is local to the developer's machine and not stored in the repo.
 		require_once $config_file;
 
-		return rocket_get_constant( $name, '' );
+		if ( ! defined( $name ) ) {
+			return '';
+		}
+
+		return constant( $name );
 	}
 }