Gutenberg 仓库 PHP 测试PHPUnit实战指南Agent 规则、环境路由与函数前缀测试【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg本篇技术指南聚焦 WordPress 块编辑器项目 Gutenberg 仓库中的PHP 测试PHPUnit体系从 AI Agent 运行 PHP 测试时的规则约定、wp-env 测试环境的启动与状态检查到composer test/vendor/bin/phpunit的具体执行方式再到测试内置带前缀PHP 函数这一仓库特有的关键约束。读完本文你将掌握在 Gutenberg 仓库中正确启动、路由、编写与运行 PHPUnit 测试的完整流程并能依据源码与配置逐层理解其底层原理。关联文档与适用范围本指南的主体依据是仓库中的 .agents/skills/testing/references/php.md它是.agents/skills/testing技能SKILL.md针对PHP 测试PHPUnit的场景化路由文件。该技能整体覆盖三类测试JavaScript 单元/集成测试Jest见 references/jest.md、PHP 测试PHPUnit即本文主题、端到端测试Playwright见 references/e2e.md。php.md 明确声明其适用对象是AgentAI 编码代理因此内容强调规则rules与路由routing什么时候能跑、跑什么命令、测试哪些符号、遵守哪些红线。这些约定同样适用于任何在本地复现 PHP 测试流程的开发者。运行 PHP 测试的前提wp-env 测试环境php.md 开门见山给出最重要的一条 Agent 规则PHPUnit 测试依赖 wp-env 测试环境。流程必须是# 1. 先检查环境是否已在运行 npm run wp-env-test status # 2. 仅当环境未运行时才启动 npm run wp-env-test start这条规则在仓库根目录的 AGENTS.md 中被完整复述Always check status first. Only start if not already running.先检查状态仅在未运行时启动。对于 Agent 会话而言反复start会浪费大量时间并可能触发端口冲突因此先 status 再 start是硬性约定。从 package.json 可以看到wp-env-test脚本的实际定义wp-env-test: wp-env --config .wp-env.test.json即所有 wp-env 相关操作都使用独立的测试环境配置 .wp-env.test.json其关键配置包括port: 8889测试环境专用端口与开发环境默认 8888隔离core: WordPress/WordPress拉取 WordPress 核心用于测试plugins: [.]将当前 Gutenberg 仓库作为插件挂载themes与mappings挂载测试主题./test/emptytheme、gutenberg-test-themes等和测试用 mu-plugins、测试插件确保测试运行在接近真实站点的环境中。为什么 PHP 测试必须依赖 wp-envGutenberg 的 PHP 测试继承自 WordPress Core 的 PHPUnit 测试体系需要一个完整的 WordPress 环境数据库、核心函数、主题/插件加载机制才能真正执行。这一点可以从测试引导文件 phpunit/bootstrap.php 得到印证定义WP_DEBUG、LOCAL_WP_DEBUG_LOG等调试常量第 9-23 行与 WordPress Core 的 PHPUnit 测试保持一致性通过WP_TESTS_DIR环境变量或回退路径定位 WP 测试库第 36-49 行通过_manually_load_plugin()手动加载被测插件lib/load.php第 61-64 行注册fail_if_died处理wp_die避免 WordPress 在测试启动阶段静默死亡导致假通过第 78-85 行通过$GLOBALS[wp_tests_options]预启用一批实验特性gutenberg-full-site-editing、gutenberg-dashboard-widgets、gutenberg-real-time-collaboration等第 87-97 行使测试能覆盖实验性代码路径。执行 PHP 测试的两条命令php.md 给出的运行方式有两条# 方式一运行全部 PHP 测试含 lint composer test # 方式二运行指定测试文件或目录 vendor/bin/phpunit path_to_test_file.phpcomposer test 到底做了什么composer.json 的 scripts 定义如下scripts: { format: phpcbf --standardphpcs.xml.dist --report-summary --report-source, lint: phpcs --standardphpcs.xml.dist, test: phpunit, test:watch: phpunit-watcher watch /dev/tty }也就是说composer test直接调用phpunit使用根目录 phpunit.xml.dist 配置而composer run test:watch则使用sirbrillig/phpunit-watchercomposer.json 的 require-dev 中包含spatie/phpunit-watcher实现文件变更自动重跑。值得注意的是composer test只跑 PHPUnit不包含代码风格检查。composer.json 中的lint脚本phpcs --standardphpcs.xml.dist才是 PHP_CodeSniffer 的 PHP 代码规范检查format脚本phpcbf用于自动修复。这与PHP 测试 lint一体化的 npm 命令见下文有区别。vendor/bin/phpunit 直接调用第二种方式是直接调用 Composer 安装的 PHPUnit 二进制path_to_test_file.php可以是单个测试文件也可以是目录。例如vendor/bin/phpunit phpunit/block-supports/anchor-test.php vendor/bin/phpunit phpunit/block-supports/通过 npm scripts 运行仓库的完整链路虽然 php.md 只给了 composer 两条命令但仓库在 package.json 中封装了更完整的 npm 链路理解它有助于把握composer test之外的全貌test:php: npm run lint:php npm run test:unit:php, test:unit:php:setup: wp-env --config .wp-env.test.json start, test:unit:php:base: wp-env --config .wp-env.test.json run --env-cwdwp-content/plugins/gutenberg wordpress vendor/bin/phpunit -c phpunit.xml.dist --verbose, test:unit:php: npm run test:unit:php:setup npm run test:unit:php:base, test:php:watch: wp-env --config .wp-env.test.json run --env-cwdwp-content/plugins/gutenberg cli composer run-script test:watch对照 docs/contributors/code/testing-overview.md 的 PHP testing 一节可以看到官方文档的表述npm run test:php同时执行 PHP lintPHP_CodeSniffer与 PHPUnit 单测npm run test:unit:php只跑单测、跳过 linternpm run test:php:watch文件变更自动重跑类似 Jest watchnpm run lint:php独立做 PHP 代码规范检查。官方文档同时提示这些 phpunit 命令要求 wp-env 正在运行且 composer 依赖已安装npm 脚本会自动为你启动 wp-env对应test:unit:php:setup而 php.md 之所以要求先手动status/start是为了让 Agent 对环境的生命周期有显式控制、避免反复启停。从 wp-env 视角理解 PHPUnit 的执行位置一个值得注意的实现细节test:unit:php:base使用wp-env ... run --env-cwdwp-content/plugins/gutenberg wordpress vendor/bin/phpunit这意味着 PHPUnit 是在wp-env 容器内部的 WordPress 环境中执行的工作目录是插件挂载点wp-content/plugins/gutenberg。这正好呼应了 bootstrap.php 中如果运行在 WP 的 build 目录中则声明WP_RUN_CORE_TESTS第 31-33 行的逻辑也解释了为什么vendor/bin/phpunit必须在容器内可访问——Composer 依赖安装于插件根目录。在 CI 侧.github/workflows/unit-test.yml 展示了同样的模式先运行npm run wp-env-test -- run wordpress ... vendor/bin/phpunit -- --version校验 PHPUnit 可用再分别执行npm run test:unit:php单站点与npm run test:unit:php:multisite多站点最后通过解析输出中的OK (N tests或Tests: N, Assertions:来判定通过与否。测试目录结构与命名约定Gutenberg 的 PHP 测试集中在 phpunit/ 目录其组织与 phpunit.xml.dist 的 testsuite 声明一一对应testsuites testsuite namedefault directory suffix-test.php./phpunit//directory directory suffix.php./phpunit/tests//directory directory suffix.php./phpunit/blocks//directory /testsuite /testsuites关键约定根级测试文件如phpunit/class-wp-theme-json-test.php、phpunit/class-wp-duotone-test.php以-test.php结尾子目录测试phpunit/tests/、phpunit/blocks/以.php结尾即被收集组排除ms-required仅多站点可运行与fontsapi字体 API 实验特性两个组在单站点运行时被排除避免环境不匹配导致误报。相应地phpunit/multisite.xml 是面向 WordPress 多站点Multisite的独立配置它通过env nameWP_MULTISITE value1 /开启多站点模式排除ms-excluded与fontsapi组。npm 侧对应的命令是npm run test:unit:php:multisite见 package.json。单站点与多站点是两套独立运行通道改动涉及多站点行为如is_multisite()分支、grant_super_admin等时必须同时跑两套。一个真实的测试文件解剖以 phpunit/block-supports/anchor-test.php 为例可以看到仓库 PHP 测试的典型写法/** * covers ::gutenberg_register_anchor_support * dataProvider data_gutenberg_register_anchor_support */ public function test_gutenberg_register_anchor_support( bool $support, ?array $value, array $expected ) { // ... gutenberg_register_anchor_support( $block_type ); } public function data_gutenberg_register_anchor_support(): array { // 返回多组 (support 配置, 属性值, 期望输出) 组合 }要点测试类继承WP_UnitTestCase如 phpunit/class-wp-theme-json-test.php获得 WordPress 测试工厂self::factory()-user-create()等与完整事务回滚大量使用dataProvider做参数化测试覆盖边界值与多分支使用covers注解标明被测函数/类便于生成覆盖率报告。核心约束测试内置带前缀函数而非源码函数php.md 将 Testing prefixed functions 列为重点深读内容并提示前缀规则本身的完整描述位于根目录 AGENTS.md 的 pitfalls 中。这是 Gutenberg PHP 测试最容易踩坑、也最具仓库特色的规则。前缀机制的原理Gutenberg 插件的 PHP 代码在构建时会被自动改名以避免与 WordPress Core 的函数/类重名冲突。相关机制详见 docs/contributors/code/build-system-function-prefixing.md符号类型源码写法开发时构建后运行时实际存在函数名block_core_navigation_link_build_css_colors()gutenberg_block_core_navigation_link_build_css_colors()函数调用wp_get_typography_font_size_value()gutenberg_get_typography_font_size_value()类名WP_Style_EngineWP_Style_Engine_Gutenberg构建产物输出到build/目录lib/blocks.php按优先级加载这些内置文件。因此运行时真正被调用的是带前缀的名字测试也就必须调用这些带前缀的名字否则会触发函数不存在错误或测试到错误的代码版本。测试必须调用内置名称Testing Prefixed Functions 给出了明确示例测试文件位于phpunit/blocks/class My_Block_Test extends WP_UnitTestCase { public function test_my_function() { // 测试内置函数带 gutenberg_ 前缀 $result gutenberg_block_core_my_block_render_function( $args ); $this-assertEquals( $expected, $result ); } public function test_my_class() { // 测试内置类带 _Gutenberg 后缀 $handler new WP_Example_Block_Handler_Gutenberg(); $result $handler-process( $input ); $this-assertEquals( $expected, $result ); } }仓库中这样的例子俯拾皆是。例如 phpunit/block-supports/anchor-test.php 直接调用gutenberg_register_anchor_support()与gutenberg_apply_anchor_support()phpunit/block-supports/block-style-variations-test.php 则实例化WP_Theme_JSON_Resolver_Gutenberg、WP_Theme_JSON_Gutenberg等_Gutenberg后缀类phpunit/class-wp-theme-json-test.php 在类注释中直接以covers WP_Theme_JSON_Gutenberg声明被测类。反向场景回迁到 WordPress Core 时文档同时给出了一条重要例外如果测试被回迁backport到 WordPress Core则必须改回测试无前缀版本block_core_my_block_render_function、WP_Example_Block_Handler。这正是前缀机制设计目标之一——Gutenberg 可以独立于 Core 发布周期演进而代码回迁后只需去掉前缀即可复用。Agent 测试写作规范通用红线虽然 php.md 本身很短但它隶属于.agents/skills/testing/SKILL.md技能体系其中的通用规则对 PHP 测试同样适用且与 PHP 代码评审phpcs直接相关先与作者确认测试清单动笔前先拟出测试用例名从用户视角描述行为一条用例对应一个行为与作者确认后再写测试体无人值守时把清单写进总结供评审。对应文档规范见 Testing Overview 的 Describing tests。禁止通过削弱测试来让失败变绿不放松断言、不无端增加等待/超时、不静默跳过用例。要么诊断根因要么如实报告失败。禁止为了修测试而改生产代码除非生产代码本身就是 Bug 源测试通过不是任务完成的最终标准验证生产代码按预期工作才是核心目标。代码规范同样适用Gutenberg 的 PHP 测试代码与生产代码同等对待testing-overview.md 明确Tests are also part of our code base。仓库提供了专用的编码标准包 test/php/gutenberg-coding-standards作为 path 仓库被 composer.json 引用为gutenberg/gutenberg-coding-standards配合wp-coding-standards/wpcs、phpcompatibility/phpcompatibility-wp等依赖通过vendor/bin/phpcs/vendor/bin/phpcbf强制执行。快速上手清单Agent 与开发者通用综合 php.md 与仓库配置一次规范的 PHP 测试会话可以归纳为以下步骤准备依赖npm install composer install安装 Node 与 PHP 依赖含 PHPUnit、PHP_CodeSniffer、编码标准包。检查环境npm run wp-env-test status若未运行则npm run wp-env-test start。运行测试全部 PHP 测试仅 PHPUnitcomposer test指定文件/目录vendor/bin/phpunit phpunit/block-supports/全链路lint 单测npm run test:php仅单测npm run test:unit:php多站点npm run test:unit:php:multisite监听模式npm run test:php:watch。遵守符号约定测试中一律调用构建后的gutenberg_*函数与*_Gutenberg类若面向 Core 回迁则使用无前缀版本。风格检查composer run lint检查与composer run format自动修复或直接vendor/bin/phpcs/vendor/bin/phpcbf。CI 对齐本地应同时通过单站点与多站点两套 PHPUnit对应 .github/workflows/unit-test.yml 的 CI 流水线并保持 PHP 代码符合 WordPress Coding Standards。总结.agents/skills/testing/references/php.md用极简篇幅划定了 Gutenberg 仓库 PHP 测试的关键路径wp-env 测试环境先行、composer test/vendor/bin/phpunit执行、前缀函数测试约定、以及指向 Testing Overview 的深度文档路由。其背后是仓库完整的工程化支撑——phpunit.xml.dist的测试套件编排、bootstrap.php的 WordPress 测试环境引导、composer/npm 双通道命令封装、以及构建期函数前缀机制。对 Agent 而言这些约定确保了测试行为的确定性不反复启停环境、不改弱断言、不误改生产代码对开发者而言它们就是一份可直接落地的 PHPUnit 实战手册。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考