wp-browser 3.x 升级 4.0 完整迁移指南避开所有坑【免费下载链接】wp-browserThe easy and reliable way to test WordPress with Codeception. 10 years of proven success.项目地址: https://gitcode.com/gh_mirrors/wp/wp-browserwp-browser是目前最流行的 Codeception WordPress 测试框架用它给 WordPress 插件、主题和站点写自动化测试已经验证了 10 年。如果你还在用 3.x 老版本升到 4.0 并不复杂但命名空间、测试断言、配置文件都有变化稍不注意就会踩坑。这篇 wp-browser 3.x 升级 4.0 迁移指南带你一步步走完全部流程让你快速无痛完成升级。一、迁移前先搞清楚3.x 与 4.0 有什么本质区别升级 wp-browser 到 4.0最核心的一刀切变化是两个硬性环境要求维度wp-browser 3.xwp-browser 4.0PHP 版本5.68.0必须Codeceptionv4v5必须Composer API1.x 即可2.2必须命名空间tad\WPBrowser、Codeception\Modulelucatume\WPBrowser统一长期维护❌ 已停止演进✅ 后续所有新版本都基于 4.x一句话只要你的项目 PHP 是 8.0 以上就应该直接迁移到 4.0。3.x 已经没有新功能了留在旧版本意味着错过dbUrl一键配置、WPLoader.dump多数据库导入等大量新能力。 官方说明wp-browser 未来的开发都发生在 4.x 上迁移是迟早要做的事不如现在做完。详见 CHANGELOG.md 中 4.0.0 版本的完整变更记录。二、迁移前必做的 3 项准备工作5 分钟1. 确认 PHP 与 Codeception 版本在终端执行以下两条命令确认你的环境达标php -v # 必须是 8.0 或更高 vendor/bin/codecept -v # 需要 5.x如果 Codeception 还是 4.x先单独升级它composer require --dev codeception/codeception:^5.02. 备份数据库转储文件wp-browser 依赖dump.sql或 SQLite 的dump.sqlite作为测试数据快照。迁移过程不会改动它但万一测试失败需要回滚有一份备份让你高枕无忧。3. 通读官方迁移清单升级前 10 分钟读一遍仓库中的 docs/migration.md它就是本文所有坑点的官方出处本文只是把它翻译成了可操作的清单。三、最快配置方法composer 一键升级 wp-browser 4.0第 1 步修改 composer.json 并安装打开项目根目录的composer.json把开发依赖改为{ require-dev: { lucatume/wp-browser: ^4.0 } }然后执行composer require --dev lucatume/wp-browser:^4.0第 2 步可选克隆源码仓库研究细节如果迁移过程中想对照源码排错可以克隆仓库到本地git clone https://gitcode.com/gh_mirrors/wp/wp-browser建议重点看两个文件src/version-4-aliases.php里面列出了全部旧类名到新类名的映射表是你全局搜索替换时的字典docs/migration.md官方迁移步骤原文四、代码改动清单命名空间迁移是最大工作量4.0 把散落在tad\WPBrowser和Codeception两个命名空间的类全部收编到lucatume\WPBrowser。用全局搜索替换处理对照表如下旧写法3.x新写法4.0用途tad\WPBrowser\...lucatume\WPBrowser\...所有工具类、辅助函数Codeception\Module\WPBrowser等lucatume\WPBrowser\Module\WPBrowser等模块类Codeception\Command\GenerateWPUnit等lucatume\WPBrowser\Command\GenerateWPUnit等代码生成命令Codeception\TestCase\WPTestCase等lucatume\WPBrowser\TestCase\WPTestCase等测试用例基类tad\WPBrowser\Extension\Eventslucatume\WPBrowser\Extension\EventDispatcherBridge事件桥接扩展好消息有向后兼容的类别名兜底4.0 内置了一套class_alias兼容层见src/version-4-aliases.php旧类名短期内仍可用。但这只是过渡拐杖建议迁移完就删干净否则后续升级会突然断掉。⚠️ 坑点提醒tad\WPBrowser\pregErrorMessage、Patchwork/PHPUnit 相关的旧函数已被彻底移除没有任何别名兜底用到它们会直接报函数/类不存在。五、测试用例常见坑废弃处理与断言变严格这是 3.x 升级 4.0 后测试莫名失败的重灾区共 3 个坑坑 1runInSeparateProcess注解被移除4.0 不再支持 PHPUnit 的runInSeparateProcess注解。如果你的测试还在用它需要在套件配置文件如tests/functional.suite.yml中启用隔离扩展extensions:yaml extensions: enabled: - lucatume\\WPBrowser\\Extension\\IsolationSupport扩展详情见仓库文档docs/extensions/IsolationSupport.md。坑 2废弃函数/类的预期申报方式变了3.x 时代靠过滤deprecated_function_trigger_error等钩子来忍废弃告警4.0 改用 Core PHPUnit 原生机制。老写法全部失效换成两个方法// 申报我知道这里用了废弃的函数/类/文件/钩子 $this-setExpectedDeprecated( my_deprecated_function ); // 申报我知道这里触发了 doing_it_wrong $this-setExpectedIncorrectUsage( my_doing_it_wrong );同时直接改$this-expected_deprecated[]属性数组的老写法也要一并改掉——属性访问已被移除。坑 3断言类型检查变严格新版 PHPUnit 核心的部分断言如assertEqualFields会检查参数类型。如果你习惯数组对象混着传会突然失败。显式转换类型即可$this-assertEqualFields( (object) [ a 1 ], [ a 1 ] );六、配置文件必改项codeception.yml 命令与模块更新打开项目根目录的codeception.yml注意不是套件配置把extensions.commands里的旧命令全部换成新命名空间并补上新命令extensions: commands: - lucatume\\WPBrowser\\Command\\GenerateWPUnit - lucatume\\WPBrowser\\Command\\GenerateWPRestApi - lucatume\\WPBrowser\\Command\\GenerateWPRestController - lucatume\\WPBrowser\\Command\\GenerateWPRestPostTypeController - lucatume\\WPBrowser\\Command\\GenerateWPAjax - lucatume\\WPBrowser\\Command\\GenerateWPCanonical - lucatume\\WPBrowser\\Command\\GenerateWPXMLRPC # 4.0 新增命令建议一并启用 - lucatume\\WPBrowser\\Command\\RunOriginal - lucatume\\WPBrowser\\Command\\RunAll - lucatume\\WPBrowser\\Command\\DbExport - lucatume\\WPBrowser\\Command\\DbImport命令源码在src/Command/目录下每个文件对应一个命令类想深入了解可逐个查看。WPLoader 模块配置删旧用新检查codeception.yml中WPLoader的配置键4.0 有明确的废弃/新增清单❌删除installationTableHandling、skipPluggables、wpDebug、isolatedInstall4.0 中安装永远隔离此参数无意义⚠️替换activatePlugins→ 改用plugins参数指定即自动激活推荐dbUrl一个 URL 配齐库名/用户/密码/主机如mysql://user:passhost:3306/db、dump安装后、首测前自动导入一个或多个转储文件、template/stylesheet模板与外观分开指定WPLoader模块源码见src/Module/WPLoader.php配置项的默认值都写在里面。七、迁移验证跑通全部测试的完整流程改完配置和代码后按这个顺序验证能最快定位残留问题冒烟测试vendor/bin/codecept run --help确认新命令wp:db:export、wp:db:import出现在命令列表里单元套件vendor/bin/codecept run unit——最快、不碰 WordPress 本体功能套件vendor/bin/codecept run functional——覆盖 WPDb、WPFilesystem 等模块端到端套件vendor/bin/codecept run acceptance如有 WebDriver 测试如果第 2 步就能通过说明命名空间迁移基本干净失败信息里出现 Class not found 或 Function tad\WPBrowser\xxx not found 时回到第四节的对照表逐个替换。八、避坑清单6 个高频问题速查#症状原因与解法1Class Codeception\Module\WPLoader not found模块类命名空间未更新见第四对照表2测试随机互相串味、nonce 冲突新 Core PHPUnit 套件清理全局状态更彻底在测试里显式设置所有依赖的全局变量3runInSeparateProcess无效改用IsolationSupport扩展见第五节坑 14废弃告警导致测试失败用setExpectedDeprecated()/setExpectedIncorrectUsage()申报5assertEqualFields等断言报类型错误显式类型转换后再断言6升级后WPCLI模块命令偶发报错4.0 的 WPCLI 模块改用严格参数解析把字符串命令改为数组格式传参更稳妥九、迁移完成后的收尾检查最后用 3 分钟做一遍收尾把兼容拐杖全部拆除✅ 全局搜索tad\WPBrowser和Codeception\Command\GenerateWP确认命中为 0✅ 全局搜索expected_deprecated、expected_doing_it_wrong确认没有直接改属性的残留✅composer update --lock提交新的锁文件✅ CI 流水线跑一次完整套件确认绿灯到这里你的 wp-browser 就完成从 3.x 到 4.0 的全部迁移了。整个流程核心就是四件事升 Composer 依赖 → 换命名空间 → 改测试用例的废弃申报 → 更新 codeception.yml。照这份清单走基本不会踩到任何隐藏的坑。【免费下载链接】wp-browserThe easy and reliable way to test WordPress with Codeception. 10 years of proven success.项目地址: https://gitcode.com/gh_mirrors/wp/wp-browser创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考