Improving incorrect usage/deprecated calls early on (#845)

* WIP

* Contd

* Contd

* Wrapping up for today

* WIP

* Adding before/after to collection

* Adding lazy collection

* Wrapping up

* Wrapping up

* Drop lazy

* Lint fixes

* Wrapping up

* Testing CI

* Lint fix

* Testing CI

* Lint fix

* Wrapping up early

* Wrapping up incorrect usage changes

* Remove comment

* Improvements to attributes

* Remove trace method

* Remove testing

* Remove old

* Linting fixes

* Adding early deprecation support

Author: srtfisher

CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+### Added
+
+- Added better messaging for early `_doing_it_wrong()` calls during testing
+  bootstrap.
+
+### Changed
+
+- Tests that call `$this->ignoreIncorrectUsage()` or use
+  `Ignore_Incorrect_Usage` will no longer make any assertions. Only using the
+  `$this->setExpectedIncorrectUsage()` method or the `Expected_Incorrect_Usage`
+  attribute will make assertions and pass the test.
+
 ## v1.14.1
 
 ### Added

composer.json

@@ -20,6 +20,7 @@
         "doctrine/inflector": "^2.0.8",
         "dragonmantank/cron-expression": "^3.3.3",
         "fakerphp/faker": "^1.24",
+        "filp/whoops": "^2.18.1",
         "laravel/serializable-closure": "^1.3.1 || ^2.0",
         "league/commonmark": "^2.7.0",
         "league/flysystem": "^3.29",

phpcs.xml

@@ -32,6 +32,8 @@
 		<exclude name="WordPress.PHP.YodaConditions.NotYoda" />
 		<exclude name="WordPress.Files.FileName.NotHyphenatedLowercase" />
 		<exclude name="WordPress.Files.FileName.InvalidClassFileName" />
+		<exclude name="WordPressVIPMinimum.Functions.StripTags.StripTagsOneParameter" />
+		<exclude name="WordPressVIPMinimum.Performance.FetchingRemoteData" />
 	</rule>
 
 	<rule ref="Generic.Arrays.DisallowLongArraySyntax" />
@@ -75,4 +77,9 @@
 	<rule ref="Generic.CodeAnalysis.UselessOverridingMethod.Found">
 		<exclude-pattern>src/mantle/framework/resources/</exclude-pattern>
 	</rule>
+
+	<!-- Ignore all WordPres naming conventions for PSR-4 code. -->
+	<rule ref="WordPress.NamingConventions">
+		<exclude-pattern>src/mantle/testing/*</exclude-pattern>
+	</rule>
 </ruleset>

src/mantle/console/concerns/trait-interacts-with-io.php

@@ -393,7 +393,7 @@ public function success( string $string, $verbosity = null ): void {
 	 * @param  int|string|null $verbosity
 	 */
 	public function alert( string $string, $verbosity = null ): void {
-		$length = Str::length( strip_tags( $string ) ) + 12; // phpcs:ignore WordPressVIPMinimum.Functions.StripTags.StripTagsOneParameter
+		$length = Str::length( strip_tags( $string ) ) + 12;
 
 		$this->comment( str_repeat( '*', $length ), $verbosity );
 		$this->comment( '*     ' . $string . '     *', $verbosity );

src/mantle/testing/EarlyDeprecationsHandler.php

@@ -0,0 +1,136 @@
+<?php
+/**
+ * EarlyDeprecationsHandler class file
+ *
+ * @package Mantle
+ */
+
+declare(strict_types=1);
+
+namespace Mantle\Testing;
+
+use Closure;
+use Spatie\Backtrace\Backtrace;
+use Spatie\Backtrace\Frame;
+
+use function Mantle\Support\Helpers\collect;
+
+/**
+ * Handler for early deprecation calls early in the testing lifecycle
+ *
+ * @see \Mantle\Testing\Concerns\Deprecations
+ *
+ * @internal
+ */
+final class EarlyDeprecationsHandler {
+	/**
+	 * Hook priority for deprecation handlers.
+	 *
+	 * This priority is cleared fully when unregistering the hooks. The priority
+	 * is assumed to not be commonly used by other handlers.
+	 *
+	 * @var int
+	 */
+	public const HOOK_PRIORITY = 57;
+
+	/**
+	 * Register the hooks for the class.
+	 */
+	public static function register(): void {
+		foreach ( TestCase::DEPRECATION_TYPES as $type ) {
+			tests_add_filter(
+				"deprecated_{$type}_run",
+				self::create_deprecated_run_callback( $type, self::deprecated_run( ... ) ),
+				self::HOOK_PRIORITY,
+				99,
+			);
+
+			tests_add_filter(
+				"deprecated_{$type}_trigger_error",
+				'__return_false',
+				self::HOOK_PRIORITY,
+			);
+		}
+
+		// Filter for _deprecated_file() which doesn't follow the same pattern.
+		tests_add_filter(
+			'deprecated_file_included',
+			self::create_deprecated_run_callback( 'file', self::deprecated_run( ... ) ),
+			self::HOOK_PRIORITY,
+			199,
+		);
+	}
+
+	/**
+	 * Deregister the hooks for the class.
+	 */
+	public static function unregister(): void {
+		foreach ( TestCase::DEPRECATION_TYPES as $type ) {
+			remove_all_actions( "deprecated_{$type}_run", self::HOOK_PRIORITY );
+			remove_filter( "deprecated_{$type}_trigger_error", '__return_false', self::HOOK_PRIORITY );
+		}
+
+		// Filters for _deprecated_file() which doesn't follow the same pattern.
+		remove_all_actions( 'deprecated_file_included', self::HOOK_PRIORITY );
+	}
+
+	/**
+	 * Handle a deprecated call.
+	 *
+	 * @param string      $type    The type of deprecation (function, argument, hook, etc).
+	 * @param string      $name    The name of the deprecated argument/function/hook/etc.
+	 * @param string|null $message An optional message.
+	 */
+	public static function deprecated_run( string $type, string $name, ?string $message = null ): void {
+		if ( empty( $message ) ) {
+			$message = "Deprecation notice for {$type} '{$name}'.";
+		}
+
+		$writer = new TraceWriter(
+			title: "Unexpected {$type} deprecation notice in test bootstrap",
+			description: $message,
+			frames: collect( Backtrace::create()->frames() )
+				->skip_until( fn ( Frame $frame ) => in_array( $frame->method, TestCase::get_deprecation_methods(), true ) )
+				->slice( 1 )
+				->values()
+				->all(),
+			prefix: 'Early Deprecation',
+		);
+
+		$writer->write();
+	}
+
+	/**
+	 * Create a callback for deprecated method calls.
+	 *
+	 * This method will resolve the varying argument structures of the different
+	 * deprecation types in WordPress and call the provided callback with a
+	 * consistent set of parameters.
+	 *
+	 * @param string  $type The type of deprecation (function, argument, hook, etc).
+	 * @param Closure $callback The callback to run on deprecation.
+	 *
+	 * @phpstan-param Closure(string $type, string $name, ?string $message): void $callback
+	 */
+	public static function create_deprecated_run_callback( string $type, Closure $callback ): callable {
+		return function ( ...$args ) use ( $type, $callback ): void {
+			// Because WordPress is WordPress, the position of the message parameter
+			// varies based on the type of deprecation.
+			$message = match ( $type ) {
+				'function'    => $args[3] ?? null,
+				'constructor' => $args[2] ?? null,
+				'class'       => $args[2] ?? null,
+				'file'        => $args[3] ?? null,
+				'argument'    => $args[2] ?? null,
+				'hook'        => $args[3] ?? null,
+				default       => end( $args ) ?: null, // Fallback to the last argument.
+			};
+
+			$callback(
+				type: $type,
+				name: $args[0],
+				message: $message,
+			);
+		};
+	}
+}

src/mantle/testing/EarlyIncorrectUsageHandler.php

@@ -0,0 +1,67 @@
+<?php
+/**
+ * EarlyIncorrectUsageHandler class file
+ *
+ * @package Mantle
+ */
+
+declare(strict_types=1);
+
+namespace Mantle\Testing;
+
+use Spatie\Backtrace\Backtrace;
+use Spatie\Backtrace\Frame;
+
+use function Mantle\Support\Helpers\collect;
+
+/**
+ * Handler for early _doing_it_wrong() calls early in the testing lifecycle
+ * (during the bootstrap process).
+ *
+ * Within the context of a test, the \Mantle\Testing\Concerns\Incorrect_Usage
+ * trait handles _doing_it_wrong() calls appropriately. However, if
+ * _doing_it_wrong() is called before the test begins (for example, during the
+ * bootstrap process), those calls are routed to this handler instead.
+ *
+ * @see \Mantle\Testing\Concerns\Incorrect_Usage
+ *
+ * @internal
+ */
+final class EarlyIncorrectUsageHandler {
+	/**
+	 * Register the hooks for the class.
+	 */
+	public static function register(): void {
+		tests_add_filter( 'doing_it_wrong_run', [ self::class, 'handle_doing_it_wrong_run' ], 10, 2 );
+		tests_add_filter( 'doing_it_wrong_trigger_error', '__return_false', 9 );
+	}
+
+	/**
+	 * Deregister the hooks for the class.
+	 */
+	public static function unregister(): void {
+		remove_action( 'doing_it_wrong_run', [ self::class, 'handle_doing_it_wrong_run' ] );
+		remove_filter( 'doing_it_wrong_trigger_error', '__return_false', 9 );
+	}
+
+	/**
+	 * Handle a _doing_it_wrong() call.
+	 *
+	 * @param string $function The function called incorrectly.
+	 * @param string $message  The message for the incorrect usage.
+	 */
+	public static function handle_doing_it_wrong_run( string $function, string $message ): void {
+		$writer = new TraceWriter(
+			title: 'Unexpected incorrect usage call in test bootstrap',
+			description: $message,
+			frames: collect( Backtrace::create()->frames() )
+				->skip_until( fn ( Frame $frame ) => $frame->method === '_doing_it_wrong' )
+				->slice( 1 )
+				->values()
+				->all(),
+			prefix: 'Early Incorrect Usage',
+		);
+
+		$writer->write();
+	}
+}