Gutenberg E2E 测试插件与 MU-Plugins 包深度解析wordpress/e2e-tests的架构、职责与运行机制【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg本文聚焦 WordPress Gutenberg 项目 monorepo 中packages/e2e-tests这一专用包系统讲解它为端到端E2E测试环境提供的测试插件test plugins与必须使用插件mu-plugins的组织方式、加载机制与典型实现。读完本文你将掌握该包三大目录plugins/、mu-plugins/、assets/中每个文件的真实用途理解其如何通过wp-env自动注入测试环境以及 E2E 测试脚本如何通过requestUtils.activatePlugin()动态启用这些测试夹具并能够据此为自己的测试场景编写同类插件。包的定位E2E 测试的“夹具仓库”在 Gutenberg monorepo 中packages/e2e-tests是一个不产出运行时功能、只服务测试的特殊包。它不向生产环境贡献任何代码而是为 WordPress 的 E2E 测试提供所需的测试插件test plugins与必须使用插件mu-plugins。从 package.json 可以看到其描述为Test plugins and mu-plugins for E2E tests in WordPress.包名为wordpress/e2e-tests。值得注意的是这个包本身不包含测试用例。README 明确提示E2E 测试用例已迁移至 Playwright位于仓库的/test/e2e/目录对应测试包wordpress/e2e-tests-playwright见 test/e2e/package.json。因此该包的全部职责可以概括为一句话为运行在/test/e2e/下的 Playwright 用例提供可复用的测试环境夹具fixtures。从依赖关系看该包依赖wordpress/interactivity与wordpress/interactivity-router用于构建交互式区块测试插件并将y-websocket作为开发依赖服务于实时协作相关的测试见 package.json。目录结构与三大组成README 给出了包的三大内容分区结合仓库实际文件可以更完整地呈现目录职责数量按仓库实际plugins/供 E2E 测试按需激活/停用的测试插件每个插件由*.php入口与对应的*.js/*.json资源组成100 个 PHP 插件入口mu-plugins/必须使用插件测试环境启动即自动加载用于统一环境配置7 个assets/测试素材图片等供用例上传、处理2 个测试图片必须使用插件mu-plugins与普通测试插件的核心区别在于加载时机mu-plugins 在 WordPress 启动阶段即被自动加载无需手动激活而普通测试插件默认不激活由测试用例通过 REST API 按需启用。这一设计让“全局环境约束”与“场景化测试夹具”解耦是理解整个测试体系的关键。mu-plugins测试环境的“全局环境约束”mu-plugins/下的 7 个文件共同承担起让测试环境稳定、可复现的使命。它们分别在 WordPress 的不同生命周期钩子上工作1. 禁用登录自动聚焦disable-login-autofocus.php文件极简仅注册一个过滤器add_filter( enable_login_autofocus, __return_false );它通过enable_login_autofocus过滤器关闭 WordPress 登录页对用户名字段的自动聚焦autofocus。在自动化测试中自动聚焦可能导致页面滚动位置或焦点状态不可控从而引发断言不稳定因此被显式关闭。2. 禁用远程模式disable-remote-patterns.phpadd_filter( should_load_remote_block_patterns, __return_false );通过should_load_remote_block_patterns过滤器禁止加载远程块模式remote block patterns。E2E 测试必须保证离线、确定性不能依赖从 wordpress.org 拉取远程资源否则网络波动会直接导致测试失败。3. 规范化主题normalize-theme.php该 mu-plugin 的目标是消除不同测试主题之间的差异保证测试断言与具体主题无关function normalize_theme_init() { remove_theme_support( editor-color-palette ); remove_theme_support( editor-font-sizes ); } add_action( init, normalize_theme_init );它在init钩子上移除主题声明的调色板editor-color-palette与字号editor-font-sizes支持从而让所有测试主题在编辑器中呈现一致的颜色与字体选项。这与全局设置脚本中强制激活twentytwentyone主题的策略见 global-setup.ts形成互补主题可以轮换但编辑器外观保持统一。4. 移除no-store缓存头nocache-headers.php这是针对测试稳定性的一个经典“workaround”。WordPress 在后台页面的Cache-Control头中会设置no-store而 Playwright 等待networkidle事件时会因该指令超时。此 mu-plugin 将no-store从Cache-Control中剔除add_filter( nocache_headers, static function ( $headers ) { $cache_control_parts explode( , , $headers[Cache-Control] ); $cache_control_parts array_diff( $cache_control_parts, array( no-store ) ); $headers[Cache-Control] implode( , , $cache_control_parts ); return $headers; } );这段代码展示了测试基础设施开发中常见的“问题驱动修补”模式注释中明确记录了为规避networkidle超时问题而引入该补丁。5. 加速协作同步轮询e2e-fast-sync-polling.php该 mu-plugin 服务于 Gutenberg 的实时协作collaboration功能测试通过过滤器将同步轮询间隔从默认值缩短从而加速测试add_action( enqueue_block_editor_assets, function () { wp_add_inline_script( wp-sync, JS wp.hooks.addFilter( sync.pollingManager.pollingInterval, e2e-tests, () 500 ); wp.hooks.addFilter( sync.pollingManager.pollingIntervalWithCollaborators, e2e-tests, () 100 ); JS, before ); } );这里有一个值得注意的实现细节由于sync模块在加载时通过applyFilters读取轮询间隔过滤器必须在wp-sync脚本执行之前注册因此它钩住enqueue_block_editor_assets并通过wp_add_inline_script( ..., before )将内联脚本注入在wp-sync句柄之前。6. 启用模板 UIenable-templates-ui.php默认情况下wp_template与wp_template_part两个文章类型不显示 UI。此 mu-plugin 在块主题block theme下为它们启用show_uiadd_filter( register_post_type_args, static function ( $args, $name ) { if ( in_array( $name, array( wp_template, wp_template_part ), true ) ) { $args[show_ui] wp_is_block_theme(); } return $args; }, 20, 2 ); add_action( setup_theme, gutenberg_enable_templates_ui );注意它钩住的是setup_theme早于init且仅在wp_is_block_theme()为真时启用确保测试界面与主题类型匹配。7. 注入 Server-Timing 指标server-timing.php这是最复杂的一个 mu-plugin其核心价值在于让测试尤其是性能测试能在前端直接读取后端性能数据。它通过Server-TimingHTTP 响应头暴露三类指标wpBeforeTemplate从请求开始到模板加载前的耗时wpTemplate模板渲染耗时wpTotal总耗时wpMemoryUsage内存使用量memory_get_usage()wpDbQueries数据库查询次数$wpdb-num_queries。实现上前台通过template_include过滤器优先级PHP_INT_MAX开启输出缓冲后台通过admin_init开启另一个缓冲在缓冲关闭回调中组装Server-Timing头$header_values[] sprintf( %1$s;dur%2$s, $slug, $value ); header( Server-Timing: . implode( , , $header_values ) );文件头部注释还提到自 WordPress 6.9 起经典主题默认启用了模板增强输出缓冲可通过wp_should_output_buffer_template_for_enhancement过滤器为块主题也启用该机制或改用wp_before_include_template动作来替代这里的template_include方案——这是跟随核心演进留下的技术备注。plugins按需激活的场景化测试夹具plugins/目录拥有上百个测试插件每个插件都是一个完整的 WordPress 插件含 PHP 入口 前端/编辑器资源供不同测试场景按需激活。按功能可归纳为以下几大类区块 API 与区块行为类这类插件用于测试 Gutenberg 区块注册、变化、图标、上下文、分组、模板等核心 API 的行为。典型代表align-hook.php注册gutenberg-test-align-hook脚本演示Align Hook如何为区块添加对齐控制依赖wp-blocks、wp-block-editor等句柄。block-api.php、block-variations.php、block-icons.php、block-context.php、child-blocks.php、inner-blocks-*.php含inner-blocks-allowed-blocks、inner-blocks-templates、inner-blocks-locking-all-embed等分别覆盖区块变化注册、图标渲染、上下文传递、嵌套区块约束等场景。register-block-type-hooks.php、allowed-blocks.php、allowed-patterns.php、block-hooks.php、block-template-registration.php测试区块钩子与模板注册机制。编辑器扩展点与 API 类这类插件通过真实的扩展点代码验证编辑器对外暴露 API 的可用性format-api.php在enqueue_block_editor_assets时加载format-api/index.js依赖wp-rich-text等测试 RichText 格式FormatAPI 的注册与使用。hooks-api.php测试wordpress/hooks过滤器与动作系统。plugins-api.php测试插件面板Plugin Sidebar / Publish Panel扩展点。test-autocompleter.php、table-of-contents-heading-source.php分别测试自动补全器与目录标题源的自定义。view-config-extensibility.php、block-bindings.php测试 View 配置与区块绑定 API 的扩展能力。iframed 区块系列iframed-*系列共 6 个专门用于测试在 iframe 中渲染的区块及其样式、脚本隔离行为。以 iframed-block.php 为例add_action( setup_theme, static function () { add_theme_support( block-templates ); } ); add_action( init, static function () { wp_register_script( iframed-block-jquery-test, ... ); wp_register_script( iframed-block-editor, ... ); wp_register_script( iframed-block-script, ... ); register_block_type_from_metadata( __DIR__ . /iframed-block ); } );它通过register_block_type_from_metadata从 block.json 注册区块并注册了 jQuery 依赖脚本用于验证 iframe 内第三方库的加载。同系列还包括iframed-inline-styles内联样式、iframed-multiple-stylesheets多样式表、iframed-masonry-blockMasonry 布局、iframed-enqueue-block-assets前端资源入队。Interactivity API 与交互式区块类interactive-blocks/子目录包含数十个针对Interactivity API指令directive的测试插件覆盖data-wp-bind、data-wp-class、data-wp-context、data-wp-each、data-wp-init、data-wp-key、data-wp-on、data-wp-on-document、data-wp-on-window、data-wp-style、data-wp-text、data-wp-watch等全部指令以及router-navigate、router-regions等路由场景和 hydration 时序场景hydration-timing、hydration-timing-async、hydration-timing-slow。这些插件是验证 Interactivity API 行为的核心测试夹具每个都由 PHP 入口 block.json JS 组成。媒体与图片处理类image-size.php、image-size-duplicates.php测试图片尺寸注册与重复尺寸处理。image-format-conversion-jpeg-to-webp.php、image-format-conversion-png-to-jpeg.php测试客户端媒体处理中的格式转换管线。lightbox-allow-editing-false-enabled-false.php测试 Lightbox 相关设置组合。协作与实时同步类rtc-websocket-provider.php与rtc-websocket-provider/子目录为实时协作测试提供 WebSocket 服务端。在 test/e2e/config/rtc-websocket-setup.ts 中全局设置会调用requestUtils.activatePlugin( PROVIDER_PLUGIN )激活它test/e2e/bin/rtc-dev.mjs 也直接以packages/e2e-tests/plugins/rtc-websocket-provider作为挂载源启动开发环境。sync-connection-error-filter.php、meta-box-rtc-compatible.php测试同步连接错误过滤与 Meta Box 兼容性。disable-client-side-media-processing.php、disable-cross-origin-isolation.php关闭客户端媒体处理与跨域隔离构造特定测试条件。自定义文章类型类custom-post-types.php 一次性注册了多组具有不同可见性组合的自定义文章类型用于系统化测试public与publicly_queryable两个标志的四象限组合not_publicpublicfalse且不可查询public_q_not_publicpublicfalse但publicly_queryabletruenot_public_q_publicpublictrue但publicly_queryablefalsepublic_q_publicpublictrue且publicly_queryabletrue。此外还包括关闭实时协作的rtc_disabled类型通过wp_is_post_type_collaboration_disabled过滤器实现、层级结构但无标题的hierar-no-title、以及模板内嵌遗留区块的leg_block_in_tpl。这类插件的价值在于测试用例可以在不同 CPT 配置下验证编辑器的差异行为。测试素材assets 目录assets/目录存放两个测试图片1024x768_e2e_test_image_size.jpg标准 1024x768 尺寸图片10x10_e2e_test_image_z9T8jK.png10x10 像素的小尺寸 PNG。小尺寸图片在媒体类测试中尤其重要——上传速度快、生成的缩略图尺寸组合少便于断言。在 test/e2e/specs/editor/blocks/image.spec.js 等用例中即可看到this.TEST_IMAGE_FILE_PATH ./assets/10x10_e2e_test_image_z9T8jK.png的引用方式。加载机制wp-env 如何注入这些夹具README 指出“这些插件与 mu-plugins 通过wp-env自动加载到测试环境中”。仓库根目录的 .wp-env.json 揭示了具体机制{ $schema: ./schemas/json/wp-env.json, testsEnvironment: false, core: WordPress/WordPress, plugins: [ . ], themes: [ ./test/emptytheme ], phpmyadminPort: 9000 }plugins: [ . ]将整个仓库根目录作为插件挂载而 Gutenberg 插件入口 gutenberg.php 在加载时会自动将packages/e2e-tests/mu-plugins下的文件作为必须使用插件拷贝/注册到测试环境的mu-plugins目录将packages/e2e-tests/plugins下的插件作为可激活插件暴露给 REST API。同时themes: [ ./test/emptytheme ]挂载了空主题作为测试主题之一。测试用例如何与夹具交互Playwright 用例通过RequestUtils来自wordpress/e2e-test-utils-playwright包以 REST API 的方式激活/停用测试插件。典型调用链如 test/e2e/specs/admin/font-library.spec.js 中的requestUtils.activatePlugin( ... )/requestUtils.deactivatePlugin( ... )。而 test/e2e/config/global-setup.ts 则展示了全局设置阶段的环境复位策略激活twentytwentyone主题、停用gutenberg-test-plugin-disables-the-css-animations插件注释说明该插件与部分用例冲突且 Playwright 本身已启用 reduced motion 并会等待动画、删除全部文章/页面/区块、重置用户偏好并初始化 RTC WebSocket Provider。值得注意的是gutenberg-test-plugin-disables-the-css-animations对应的正是disable-animations.php通过wp_add_inline_style( wp-components, ... )注入animation-duration: 0ms !important等样式可见测试插件同样会被全局设置显式地启用或停用以维持不同用例之间的隔离。从 Jest 迁移到 Playwright历史与现状README 中关于“测试已迁移到 Playwright”的说明反映了一个重要的工程演进历史形态E2E 测试曾基于 Jest Puppeteer测试辅助代码存放于本包测试用例与夹具同处一包当前形态测试用例全部迁至 test/e2e/ 目录441 个文件含specs/用例目录、config/配置目录基于 Playwright 运行测试包更名为wordpress/e2e-tests-playwright本包现在的角色仅保留测试夹具插件、mu-plugins、素材继续通过wp-env注入测试环境。如何扩展本包为你的测试场景新增夹具基于上述架构新增一个测试插件的标准流程为在 packages/e2e-tests/plugins/ 下创建my-scenario.php作为插件入口填写标准的插件头注释Plugin Name等并在合适的钩子init、enqueue_block_editor_assets等中注册脚本/样式/区块元数据如需前端 JS创建同名子目录my-scenario/index.js通过plugins_url()引用并使用filemtime()作为版本参数这一模式在align-hook.php、format-api.php、iframed-block.php中反复出现便于开发时绕过缓存如需全局环境约束而非按需激活将文件放入mu-plugins/目录它会在环境启动时自动加载在用例中通过requestUtils.activatePlugin( gutenberg-test-my-scenario )激活测试结束后通过deactivatePlugin清理。其中插件 slug 由插件头注释中的Plugin Name推导而来命名遵循gutenberg-test-*前缀约定这也是 global-setup.ts 能够以gutenberg-test-plugin-disables-the-css-animations精确停用对应插件的原因。总结wordpress/e2e-tests是 Gutenberg 测试体系中被低估却至关重要的基础设施包。它以“夹具仓库”的定位通过mu-plugins/实现全局环境约束禁用远程资源、禁用动画依赖、规范化主题、移除缓存干扰、加速协作轮询、注入性能指标通过plugins/提供上百个可按需激活的场景化插件覆盖区块 API、编辑器扩展点、iframed 渲染、Interactivity API、媒体处理、实时协作、CPT 变体等并通过wp-env与 Playwright 的RequestUtils实现自动加载与动态启停。理解这套机制无论对阅读 Gutenberg 源码、编写 WordPress 插件测试还是构建自己的 WordPress E2E 测试环境都具有直接的借鉴价值。该包相关的测试运行代码、配置与用例可分别在 test/e2e/、.wp-env.json 与 packages/e2e-tests/ 中继续深入探索。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
