Changeset 62379 for branches/7.0/tests/phpunit/tests/dependencies/scripts.php

Timestamp:

05/19/2026 12:23:04 PM (4 months ago)

Author:

ellatrix

Message:

Script Loader: Warn when classic scripts with module dependencies lack footer/defer.

A classic script with module_dependencies may be evaluated before the script modules import map is printed if it loads blocking in the document head, causing a "Failed to resolve module specifier" error on dynamic imports.

• Trigger _doing_it_wrong() from _wp_scripts_add_args_data() when a classic script provides module_dependencies without setting in_footer to true or using a defer loading strategy, and document this requirement in the wp_register_script() and wp_enqueue_script() docblocks.
• Remove the module_dependencies arg from the wp-codemirror script registration in favor of passing the espree module URL directly through wp_get_code_editor_settings(). This avoids registering espree as a publicly-available script module when it is only ever used internally as a private implementation detail of the code editor.
• Add a console.warn() in wp.codeEditor.initialize() when invoked before DOMContentLoaded, so developers are alerted if the function is called too early for the import map to have been parsed.
• Add PHPStan types which were missing when module_dependencies were initially introduced.
• Harden WP_Scripts::add_data() against non-string strategy values being passed to sprintf().

Developed in ​https://github.com/WordPress/wordpress-develop/pull/11788

Follow-up to r61587.

Reviewed by jonsurrell.
Merges [62368] to the 7.0 branch.
Props khokansardar, westonruter, jonsurrell, jorbin.
See #61500, #64238.
Fixes #65165.

Location:

branches/7.0

Files:

• . (modified) (1 prop)
• tests/phpunit/tests/dependencies/scripts.php (modified) (6 diffs)

branches/7.0/tests/phpunit/tests/dependencies/scripts.php

@@ -9 +9 @@
  * @covers ::wp_add_inline_script
  * @covers ::wp_set_script_translations
+ *
+ * @phpstan-type ScriptArgs array{
+ *     in_footer?: bool,
+ *     strategy?: 'async'|'defer',
+ *     fetchpriority?: 'low'|'auto'|'high',
+ *     module_dependencies?: array<non-empty-string|array{ id: non-empty-string, ... }>,
+ * }
+ * @phpstan-type WpEnqueueScriptArgs array{
+ *     0: non-empty-string, // $handle
+ *     1?: non-empty-string, // $src
+ *     2?: non-empty-string[], // $deps
+ *     3?: null|bool|string, // $version
+ *     4?: ScriptArgs,
+ * }
  */
 class Tests_Dependencies_Scripts extends WP_UnitTestCase {
@@ -1393 +1407 @@
                                 'expected' => true,
                                 'stored'   => array( 'valid', array( 'id' => 'valid2' ) ),
+                        ),
+                );
+        }
+
+        /**
+         * Tests that registering a script with `module_dependencies` triggers `_doing_it_wrong`
+         * when the script is not printed in the footer and does not use the `defer` strategy.
+         *
+         * @ticket 65165
+         *
+         * @covers ::wp_register_script
+         * @covers ::wp_enqueue_script
+         * @covers ::_wp_scripts_add_args_data
+         *
+         * @dataProvider data_module_dependencies_require_footer_or_defer
+         *
+         * @param callable-string $function_name Function name to call.
+         * @param array           $args          Arguments to pass to the function.
+         * @param bool            $should_warn   Whether the call is expected to trigger a `_doing_it_wrong` warning.
+         *
+         * @phpstan-param WpEnqueueScriptArgs $args
+         */
+        public function test_module_dependencies_require_footer_or_defer( string $function_name, array $args, bool $should_warn ): void {
+                if ( $should_warn ) {
+                        $this->setExpectedIncorrectUsage( $function_name );
+                }
+
+                call_user_func_array( $function_name, $args );
+
+                if ( $should_warn ) {
+                        $this->assertStringContainsString(
+                                'module_dependencies',
+                                $this->caught_doing_it_wrong[ $function_name ],
+                                'The _doing_it_wrong message should reference module_dependencies.'
+                        );
+                        $this->assertStringContainsString(
+                                'in_footer',
+                                $this->caught_doing_it_wrong[ $function_name ],
+                                'The _doing_it_wrong message should reference the in_footer requirement.'
+                        );
+                        $this->assertStringContainsString(
+                                'defer',
+                                $this->caught_doing_it_wrong[ $function_name ],
+                                'The _doing_it_wrong message should reference the defer strategy.'
+                        );
+                } else {
+                        $this->assertArrayNotHasKey(
+                                $function_name,
+                                $this->caught_doing_it_wrong,
+                                'No _doing_it_wrong warning should be triggered when in_footer is true or strategy is defer.'
+                        );
+                }
+        }
+
+        /**
+         * Data provider for {@see self::test_module_dependencies_require_footer_or_defer()}.
+         *
+         * @phpstan-return array<string, array{
+         *     function_name: callable-string,
+         *     args: WpEnqueueScriptArgs,
+         *     should_warn: bool,
+         * }>
+         */
+        public function data_module_dependencies_require_footer_or_defer(): array {
+                $base_args = array(
+                        '/script.js',
+                        array(),
+                        null,
+                );
+
+                return array(
+                        'register_blocking_warns'            => array(
+                                'function_name' => 'wp_register_script',
+                                'args'          => array_merge(
+                                        array( 'module-deps-blocking-register' ),
+                                        $base_args,
+                                        array(
+                                                array(
+                                                        'module_dependencies' => array( 'foo' ),
+                                                ),
+                                        )
+                                ),
+                                'should_warn'   => true,
+                        ),
+                        'enqueue_blocking_warns'             => array(
+                                'function_name' => 'wp_enqueue_script',
+                                'args'          => array_merge(
+                                        array( 'module-deps-blocking-enqueue' ),
+                                        $base_args,
+                                        array(
+                                                array(
+                                                        'module_dependencies' => array( 'foo' ),
+                                                ),
+                                        )
+                                ),
+                                'should_warn'   => true,
+                        ),
+                        'register_async_warns'               => array(
+                                'function_name' => 'wp_register_script',
+                                'args'          => array_merge(
+                                        array( 'module-deps-async-register' ),
+                                        $base_args,
+                                        array(
+                                                array(
+                                                        'module_dependencies' => array( 'foo' ),
+                                                        'strategy'            => 'async',
+                                                ),
+                                        )
+                                ),
+                                'should_warn'   => true,
+                        ),
+                        'enqueue_async_warns'                => array(
+                                'function_name' => 'wp_enqueue_script',
+                                'args'          => array_merge(
+                                        array( 'module-deps-async-enqueue' ),
+                                        $base_args,
+                                        array(
+                                                array(
+                                                        'module_dependencies' => array( 'foo' ),
+                                                        'strategy'            => 'async',
+                                                ),
+                                        )
+                                ),
+                                'should_warn'   => true,
+                        ),
+                        'register_in_footer_does_not_warn'   => array(
+                                'function_name' => 'wp_register_script',
+                                'args'          => array_merge(
+                                        array( 'module-deps-footer-register' ),
+                                        $base_args,
+                                        array(
+                                                array(
+                                                        'module_dependencies' => array( 'foo' ),
+                                                        'in_footer'           => true,
+                                                ),
+                                        )
+                                ),
+                                'should_warn'   => false,
+                        ),
+                        'enqueue_in_footer_does_not_warn'    => array(
+                                'function_name' => 'wp_enqueue_script',
+                                'args'          => array_merge(
+                                        array( 'module-deps-footer-enqueue' ),
+                                        $base_args,
+                                        array(
+                                                array(
+                                                        'module_dependencies' => array( 'foo' ),
+                                                        'in_footer'           => true,
+                                                ),
+                                        )
+                                ),
+                                'should_warn'   => false,
+                        ),
+                        'register_defer_does_not_warn'       => array(
+                                'function_name' => 'wp_register_script',
+                                'args'          => array_merge(
+                                        array( 'module-deps-defer-register' ),
+                                        $base_args,
+                                        array(
+                                                array(
+                                                        'module_dependencies' => array( 'foo' ),
+                                                        'strategy'            => 'defer',
+                                                ),
+                                        )
+                                ),
+                                'should_warn'   => false,
+                        ),
+                        'enqueue_defer_does_not_warn'        => array(
+                                'function_name' => 'wp_enqueue_script',
+                                'args'          => array_merge(
+                                        array( 'module-deps-defer-enqueue' ),
+                                        $base_args,
+                                        array(
+                                                array(
+                                                        'module_dependencies' => array( 'foo' ),
+                                                        'strategy'            => 'defer',
+                                                ),
+                                        )
+                                ),
+                                'should_warn'   => false,
+                        ),
+                        'register_footer_and_defer_no_warn'  => array(
+                                'function_name' => 'wp_register_script',
+                                'args'          => array_merge(
+                                        array( 'module-deps-footer-defer-register' ),
+                                        $base_args,
+                                        array(
+                                                array(
+                                                        'module_dependencies' => array( 'foo' ),
+                                                        'in_footer'           => true,
+                                                        'strategy'            => 'defer',
+                                                ),
+                                        )
+                                ),
+                                'should_warn'   => false,
+                        ),
+                        'register_no_module_deps_no_warn'    => array(
+                                'function_name' => 'wp_register_script',
+                                'args'          => array_merge(
+                                        array( 'no-module-deps-register' ),
+                                        $base_args,
+                                        array( array() )
+                                ),
+                                'should_warn'   => false,
+                        ),
+                        'register_empty_module_deps_no_warn' => array(
+                                'function_name' => 'wp_register_script',
+                                'args'          => array_merge(
+                                        array( 'empty-module-deps-register' ),
+                                        $base_args,
+                                        array(
+                                                array(
+                                                        'module_dependencies' => array(),
+                                                ),
+                                        )
+                                ),
+                                'should_warn'   => false,
                         ),
                 );
@@ -3170 +3401 @@
                                 'browser',
                                 'globals',
+                                'espreeModuleUrl',
                         ),
                         array_keys( $wp_enqueue_code_editor['jshint'] )
@@ -3253 +3485 @@
                                 'browser',
                                 'globals',
+                                'espreeModuleUrl',
                         ),
                         array_keys( $wp_enqueue_code_editor['jshint'] )
@@ -3350 +3583 @@
                                 'browser',
                                 'globals',
+                                'espreeModuleUrl',
                         ),
                         array_keys( $wp_enqueue_code_editor['jshint'] )
@@ -3444 +3678 @@
                                 'browser',
                                 'globals',
+                                'espreeModuleUrl',
                         ),
                         array_keys( $wp_enqueue_code_editor['jshint'] )