Closes #36: Consolidate divergent getDefaultVfs() definitions

Tests/Fixtures/VirtualFilesystemTestTrait/getDefaultVfs.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+return [
+	'wp-like default structure' => [
+		[
+			'wp-admin'      => [],
+			'wp-content'    => [
+				'mu-plugins' => [],
+				'plugins'    => [
+					'wp-rocket' => [],
+				],
+				'themes'     => [
+					'twentytwenty' => [],
+				],
+				'uploads'    => [],
+			],
+			'wp-includes'   => [],
+			'wp-config.php' => '',
+		],
+	],
+];

Tests/Unit/VirtualFilesystemDirect/TestCase.php

@@ -1,23 +1,65 @@
 <?php
 
+declare(strict_types=1);
+
 namespace WPMedia\PHPUnit\Tests\Unit\VirtualFilesystemDirect;
 
 use WPMedia\PHPUnit\Unit\VirtualFilesystemTestCase;
 
 abstract class TestCase extends VirtualFilesystemTestCase {
+
+	/**
+	 * Path to the config and test data in the Fixtures directory.
+	 *
+	 * @var string
+	 */
 	protected $path_to_test_data = 'structure.php';
 
+	/**
+	 * Initializes the virtual filesystem before each test.
+	 *
+	 * @return void
+	 */
 	protected function setUp(): void {
 		parent::setUp();
 
 		$this->init();
 	}
 
+	/**
+	 * Gets the path to the Fixtures directory.
+	 *
+	 * @return string
+	 */
 	public function getPathToFixturesDir() {
 		return WPMEDIA_PHPUNIT_ROOT_DIR . '/Tests/Fixtures/';
 	}
 
+	/**
+	 * Loads the test data matching the given file from the Fixtures directory.
+	 *
+	 * @param string $file Path or filename of the test class requesting the data.
+	 *
+	 * @return array test data.
+	 */
 	protected function loadTestData( $file ) {
 		return $this->getTestData( WPMEDIA_PHPUNIT_ROOT_DIR . '/Tests/Fixtures/', basename( $file, '.php' ) );
 	}
+
+	/**
+	 * Overrides the package's WP-like default with the `Tests/{Integration,Unit}` structure
+	 * that the fixtures in this suite (see {@see Test_GetListing}, {@see Test_GetDirsListing},
+	 * {@see Test_GetFilesListing}) assert against as the full, exact listing of the virtual
+	 * filesystem root.
+	 *
+	 * @return array default structure.
+	 */
+	public function getDefaultVfs() {
+		return [
+			'Tests' => [
+				'Integration' => [],
+				'Unit'        => [],
+			],
+		];
+	}
 }

Tests/Unit/VirtualFilesystemTestTrait/TestCase.php

@@ -34,18 +34,4 @@ abstract class TestCase extends BaseTestCase {
 	public function getPathToFixturesDir() {
 		return WPMEDIA_PHPUNIT_ROOT_DIR . '/Tests/Fixtures/';
 	}
-
-	/**
-	 * Gets the default virtual directory filesystem structure.
-	 *
-	 * @return array default structure.
-	 */
-	public function getDefaultVfs() {
-		return [
-			'Tests' => [
-				'Integration' => [],
-				'Unit'        => [],
-			],
-		];
-	}
 }

Tests/Unit/VirtualFilesystemTestTrait/getDefaultVfs.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WPMedia\PHPUnit\Tests\Unit\VirtualFilesystemTestTrait;
+
+/**
+ * Tests the default virtual filesystem structure.
+ *
+ * @covers \WPMedia\PHPUnit\VirtualFilesystemTestTrait::getDefaultVfs
+ * @group  VfsTrait
+ */
+class Test_GetDefaultVfs extends TestCase {
+
+	/**
+	 * Asserts that getDefaultVfs() returns the expected default structure.
+	 *
+	 * @dataProvider getDefaultVfsDataProvider
+	 *
+	 * @param array $expected Expected default structure.
+	 *
+	 * @return void
+	 */
+	public function testShouldReturnTheDefaultStructure( $expected ) {
+		$this->assertSame( $expected, $this->getDefaultVfs() );
+	}
+
+	/**
+	 * Provides the expected default structure from the Fixtures directory.
+	 *
+	 * @return array test data.
+	 */
+	public function getDefaultVfsDataProvider() {
+		return $this->getTestData( __DIR__, 'getDefaultVfs' );
+	}
+}

phpcs.xml.dist

@@ -12,6 +12,10 @@
 	codebase is fully compliant.
 	-->
 	<file>src/Integration/HttpRequestTrait.php</file>
+	<file>src/VirtualFilesystemTestTrait.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

@@ -178,13 +178,13 @@ parameters:
 			rawMessage: 'Call to function is_array() with array will always evaluate to true.'
 			identifier: function.alreadyNarrowedType
 			count: 1
-			path: src/Unit/VirtualFilesystemTestCase.php
+			path: src/ArrayTrait.php
 
 		-
 			rawMessage: 'Call to function is_null() with string will always evaluate to false.'
 			identifier: function.impossibleType
 			count: 2
-			path: src/Unit/VirtualFilesystemTestCase.php
+			path: src/ArrayTrait.php
 
 		-
 			rawMessage: Constant WPMEDIA_PHPUNIT_ROOT_DIR not found.

src/Integration/VirtualFilesystemTestCase.php

@@ -36,18 +36,4 @@ abstract class VirtualFilesystemTestCase extends TestCase {
 	 * @var int
 	 */
 	protected $permissions = 0777;
-
-	/**
-	 * Gets the default virtual directory filesystem structure.
-	 *
-	 * @return array default structure.
-	 */
-	public function getDefaultVfs() {
-		return [
-			'Tests' => [
-				'Integration' => [],
-				'Unit'        => [],
-			],
-		];
-	}
 }

src/Unit/VirtualFilesystemTestCase.php

@@ -28,18 +28,4 @@ abstract class VirtualFilesystemTestCase extends TestCase {
 	 * @var int
 	 */
 	protected $permissions = 0777;
-
-	/**
-	 * Gets the default virtual directory filesystem structure.
-	 *
-	 * @return array default structure.
-	 */
-	public function getDefaultVfs() {
-		return [
-			'Tests' => [
-				'Integration' => [],
-				'Unit'        => [],
-			],
-		];
-	}
 }

src/VirtualFilesystemTestTrait.php

@@ -1,5 +1,7 @@
 <?php
 
+declare(strict_types=1);
+
 namespace WPMedia\PHPUnit;
 
 trait VirtualFilesystemTestTrait {
@@ -25,7 +27,7 @@ trait VirtualFilesystemTestTrait {
 	 *
 	 * @var string
 	 */
-	protected $rootVirtualUrl;
+	protected $rootVirtualUrl; // phpcs:ignore WordPress.NamingConventions.ValidVariableName.PropertyNotSnakeCase -- Public API property; renaming would be a breaking change for consumers.
 
 	/**
 	 * Structure + test data configuration.
@@ -46,7 +48,7 @@ trait VirtualFilesystemTestTrait {
 	 *
 	 * @var bool
 	 */
-	protected $skip_initOriginals = false;
+	protected $skip_initOriginals = false; // phpcs:ignore WordPress.NamingConventions.ValidVariableName.PropertyNotSnakeCase -- Public API property; renaming would be a breaking change for consumers.
 
 	/**
 	 * Original virtual files with flattened full paths.
@@ -71,16 +73,17 @@ public function init() {
 		}
 		$this->initOriginals();
 
+		// phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase -- Public API property; renaming would be a breaking change for consumers.
 		$this->filesystem     = new VirtualFilesystemDirect( $this->rootVirtualDir, $this->mergeStructure(), $this->permissions );
-		$this->rootVirtualUrl = $this->filesystem->getUrl( '/' );
+		$this->rootVirtualUrl = $this->filesystem->getUrl( '/' ); // phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase -- Public API property; renaming would be a breaking change for consumers.
 	}
 
 	/**
 	 * Test Data Provider that uses the `'test_data'` in the config file.
 	 *
 	 * @return mixed
 	 */
-	public function providerTestData() {
+	public function providerTestData() { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid -- Public API method; renaming would be a breaking change for consumers.
 		$this->loadConfig();
 
 		return $this->config['test_data'];
@@ -89,7 +92,7 @@ public function providerTestData() {
 	/**
 	 * Loads the configuration for the vfs structure and test data.
 	 */
-	protected function loadConfig() {
+	protected function loadConfig() { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid -- Public API method; renaming would be a breaking change for consumers.
 		$this->config = array_merge(
 			[
 				'vfs_dir'   => '',
@@ -105,7 +108,7 @@ protected function loadConfig() {
 	 *
 	 * @return string
 	 */
-	public function getPathToFixturesDir() {
+	public function getPathToFixturesDir() { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid -- Public API method; renaming would be a breaking change for consumers.
 		return '';
 	}
 
@@ -114,7 +117,7 @@ public function getPathToFixturesDir() {
 	 *
 	 * @return array merged structure
 	 */
-	protected function mergeStructure() {
+	protected function mergeStructure() { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid -- Public API method; renaming would be a breaking change for consumers.
 		// If already merged, return it.
 		if ( ! empty( $this->merged_structure ) ) {
 			return $this->merged_structure;
@@ -129,9 +132,14 @@ protected function mergeStructure() {
 	/**
 	 * Gets the default virtual directory filesystem structure.
 	 *
+	 * This is the single source of truth for the default structure used by
+	 * {@see mergeStructure()}. Consumers that need a different default structure
+	 * should override this method rather than defining a competing default
+	 * elsewhere in the class hierarchy.
+	 *
 	 * @return array default structure.
 	 */
-	public function getDefaultVfs() {
+	public function getDefaultVfs() { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid -- Public API method and the package's documented single override point (issue #36); renaming would be a breaking change for consumers.
 		return [
 			'wp-admin'      => [],
 			'wp-content'    => [
@@ -152,16 +160,16 @@ public function getDefaultVfs() {
 	/**
 	 * Initializes the original files and directories properties for use in the tests.
 	 */
-	protected function initOriginals() {
+	protected function initOriginals() { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid -- Public API method; renaming would be a breaking change for consumers.
 		// Bail out when "skip_initOriginals" is set to true.
-		if ( $this->skip_initOriginals ) {
+		if ( $this->skip_initOriginals ) { // phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase -- Public API property; renaming would be a breaking change for consumers.
 			return;
 		}
 
 		if ( ! empty( $this->config['vfs_dir'] ) && '/' !== $this->config['vfs_dir'] ) {
-			$vfs_dir    = rtrim( $this->config['vfs_dir'], '/\\' ); // Remove trailing slash for the get.
-			$structure  = $this->get( $this->config['structure'], $vfs_dir, [], '/' );
-			$vfs_dir   .= '/'; // Add the trailing slash for the flattening.
+			$vfs_dir   = rtrim( $this->config['vfs_dir'], '/\\' ); // Remove trailing slash for the get.
+			$structure = $this->get( $this->config['structure'], $vfs_dir, [], '/' );
+			$vfs_dir  .= '/'; // Add the trailing slash for the flattening.
 		} else {
 			$vfs_dir   = '';
 			$structure = $this->config['structure'];