Build/Test Tools: Add tests for the PHPStan extensions

.github/workflows/phpstan-static-analysis.yml

@@ -19,6 +19,9 @@ on:
       - 'phpstan.neon.dist'
       - 'tests/phpstan/base.neon'
       - 'tests/phpstan/baselines/**'
+      # These files configure the tests of the PHPStan extensions.
+      - 'tests/phpstan/phpunit.xml.dist'
+      - 'tests/phpstan/Tests/tests.neon'
       # Confirm any changes to relevant workflow files.
       - '.github/workflows/phpstan-static-analysis.yml'
       - '.github/workflows/reusable-phpstan-static-analysis-v1.yml'

.github/workflows/reusable-phpstan-static-analysis-v1.yml

@@ -30,6 +30,7 @@ jobs:
   # - Logs debug information.
   # - Installs Composer dependencies.
   # - Make Composer packages available globally.
+  # - Runs the tests of the WordPress-specific PHPStan extensions.
   # - Builds WordPress.
   # - Configures caching for PHPStan static analysis scans.
   # - Runs PHPStan static analysis.
@@ -75,6 +76,13 @@ jobs:
       - name: Make Composer packages available globally
         run: echo "${PWD}/vendor/bin" >> "$GITHUB_PATH"
 
+      # The extensions in `tests/phpstan` are tested against fixtures rather than against
+      # core, so a defect in one is reported here as a failing test rather than as a
+      # change in what the analysis below reports.
+      - name: Run the tests of the PHPStan extensions
+        if: ${{ hashFiles('tests/phpstan/phpunit.xml.dist') != '' }}
+        run: composer run phpstan:test
+
       # The directory holds more than the analysis results. PHPStan also stores what it read out of
       # each source file there, the docblocks and signatures it found, keyed by that file's contents
       # and nothing else. The extensions in `tests/phpstan` change what reading a file yields without

composer.json

@@ -77,6 +77,7 @@
 	"scripts": {
 		"phpstan": "@php ./vendor/bin/phpstan analyse --memory-limit=2G",
 		"phpstan:baselines": [ "Composer\\Config::disableProcessTimeout", "@php ./tests/phpstan/generate-baselines.php" ],
+		"phpstan:test": "@php ./vendor/phpunit/phpunit/phpunit -c tests/phpstan/phpunit.xml.dist",
 		"compat": "@php ./vendor/squizlabs/php_codesniffer/bin/phpcs --standard=phpcompat.xml.dist --report=summary,source",
 		"format": "@php ./vendor/squizlabs/php_codesniffer/bin/phpcbf --report=summary,source",
 		"lint": "@php ./vendor/squizlabs/php_codesniffer/bin/phpcs --report=summary,source",

package.json

@@ -154,6 +154,7 @@
 		"test:visual": "wp-scripts test-playwright --config tests/visual-regression/playwright.config.js",
 		"typecheck:php": "node ./tools/local-env/scripts/docker.js run --rm php composer phpstan --",
 		"typecheck:php:baselines": "node ./tools/local-env/scripts/docker.js run --rm php composer phpstan:baselines --",
+		"typecheck:php:test": "node ./tools/local-env/scripts/docker.js run --rm php composer phpstan:test --",
 		"gutenberg:copy": "node tools/gutenberg/copy.js",
 		"gutenberg:verify": "node tools/gutenberg/utils.js",
 		"gutenberg:download": "node tools/gutenberg/download.js && npm run build:gutenberg"

tests/phpstan/README.md

@@ -186,6 +186,24 @@ These identifiers are specific to WordPress, and can be ignored or baselined lik
 | `wordpress.hookDocReferenceHookMissing` | The referenced file exists, but documents no hook of that name. Either the reference is stale, or the canonical docblock has moved. |
 | `wordpress.hookParamCountMismatch` | The call passes a different number of arguments than the docblock documents `@param` tags for. Passing fewer risks an `ArgumentCountError` in a callback registered for the documented count; passing more silently drops the extra argument and leaves the documentation misleading. |
 
+### Testing the extensions
+
+The extensions have tests of their own under [`Tests/`](Tests), built on PHPStan's test harness. The two rules are run over fixture files and the errors they report are compared with the ones expected. The visitors and the return type extension are checked through the types PHPStan infers for the `assertType()` calls in their fixtures. Reference comments resolve against a small WordPress tree of fixtures in [`Tests/data/wordpress`](Tests/data/wordpress) rather than against `src`, so a broken reference can be tested without one existing in core.
+
+Run them with:
+
+```bash
+npm run typecheck:php:test
+```
+
+or, outside the Docker environment:
+
+```bash
+composer phpstan:test
+```
+
+They also run in CI, ahead of the analysis itself.
+
 ## Ignoring and baselining errors
 
 As we adopt PHPStan iteratively, you may be faced with false positives due to legacy code, or code that is not worth changing at this time.

tests/phpstan/Tests/ApplyFiltersDynamicFunctionReturnTypeExtensionTest.php

@@ -0,0 +1,49 @@
+<?php
+/**
+ * Tests for ApplyFiltersDynamicFunctionReturnTypeExtension.
+ *
+ * @package WordPress
+ */
+
+declare(strict_types=1);
+
+namespace WordPress\PHPStan\Tests;
+
+use PHPStan\Testing\TypeInferenceTestCase;
+
+/**
+ * Checks the type PHPStan infers for a filtered value against the `assertType()`
+ * calls in the fixtures.
+ */
+final class ApplyFiltersDynamicFunctionReturnTypeExtensionTest extends TypeInferenceTestCase {
+
+	/**
+	 * Gathers the assertions from the fixtures.
+	 *
+	 * @return iterable<string, mixed[]>
+	 */
+	public function data_file_asserts(): iterable {
+		yield from self::gatherAssertTypes( __DIR__ . '/data/apply-filters.php' );
+		yield from self::gatherAssertTypes( __DIR__ . '/data/ApplyFiltersTestClass.php' );
+	}
+
+	/**
+	 * @dataProvider data_file_asserts
+	 *
+	 * @param string $assert_type Kind of assertion.
+	 * @param string $file        Fixture file.
+	 * @param mixed  ...$args     Assertion arguments.
+	 */
+	public function test_file_asserts( string $assert_type, string $file, ...$args ): void {
+		$this->assertFileAsserts( $assert_type, $file, ...$args );
+	}
+
+	/**
+	 * Returns the configuration registering the extension and the visitors it relies on.
+	 *
+	 * @return list<string>
+	 */
+	public static function getAdditionalConfigFiles(): array {
+		return array( __DIR__ . '/tests.neon' );
+	}
+}

tests/phpstan/Tests/GlobalDocBlockVisitorTest.php

@@ -0,0 +1,49 @@
+<?php
+/**
+ * Tests for GlobalDocBlockVisitor.
+ *
+ * @package WordPress
+ */
+
+declare(strict_types=1);
+
+namespace WordPress\PHPStan\Tests;
+
+use PHPStan\Testing\TypeInferenceTestCase;
+
+/**
+ * Checks the type PHPStan infers for an imported global against the `assertType()`
+ * calls in the fixtures.
+ */
+final class GlobalDocBlockVisitorTest extends TypeInferenceTestCase {
+
+	/**
+	 * Gathers the assertions from the fixtures.
+	 *
+	 * @return iterable<string, mixed[]>
+	 */
+	public function data_file_asserts(): iterable {
+		yield from self::gatherAssertTypes( __DIR__ . '/data/global-docblock.php' );
+		yield from self::gatherAssertTypes( __DIR__ . '/data/GlobalDocBlockTestClass.php' );
+	}
+
+	/**
+	 * @dataProvider data_file_asserts
+	 *
+	 * @param string $assert_type Kind of assertion.
+	 * @param string $file        Fixture file.
+	 * @param mixed  ...$args     Assertion arguments.
+	 */
+	public function test_file_asserts( string $assert_type, string $file, ...$args ): void {
+		$this->assertFileAsserts( $assert_type, $file, ...$args );
+	}
+
+	/**
+	 * Returns the configuration registering the visitor.
+	 *
+	 * @return list<string>
+	 */
+	public static function getAdditionalConfigFiles(): array {
+		return array( __DIR__ . '/tests.neon' );
+	}
+}

tests/phpstan/Tests/HashNotationTypeTest.php

@@ -0,0 +1,47 @@
+<?php
+/**
+ * Tests the types PHPStan infers once HashNotationVisitor has translated a hash.
+ *
+ * @package WordPress
+ */
+
+declare(strict_types=1);
+
+namespace WordPress\PHPStan\Tests;
+
+use PHPStan\Testing\TypeInferenceTestCase;
+
+/**
+ * Checks the `assertType()` calls in the hash notation fixture.
+ */
+final class HashNotationTypeTest extends TypeInferenceTestCase {
+
+	/**
+	 * Gathers the assertions from the fixture.
+	 *
+	 * @return iterable<string, mixed[]>
+	 */
+	public function data_file_asserts(): iterable {
+		yield from self::gatherAssertTypes( __DIR__ . '/data/hash-notation.php' );
+	}
+
+	/**
+	 * @dataProvider data_file_asserts
+	 *
+	 * @param string $assert_type Kind of assertion.
+	 * @param string $file        Fixture file.
+	 * @param mixed  ...$args     Assertion arguments.
+	 */
+	public function test_file_asserts( string $assert_type, string $file, ...$args ): void {
+		$this->assertFileAsserts( $assert_type, $file, ...$args );
+	}
+
+	/**
+	 * Returns the configuration registering the visitor.
+	 *
+	 * @return list<string>
+	 */
+	public static function getAdditionalConfigFiles(): array {
+		return array( __DIR__ . '/tests.neon' );
+	}
+}