PHPUnit 9.5升级时expectException关联Error类的弃用适配方案
PHPUnit 9.5 升级弃用警告适配指南
核心认知澄清
expectException()对所有自定义业务异常(比如案例中提到的InvalidArgumentException)的支持是完全保留的,没有任何废弃计划,也不需要强制替换。- 触发“使用
expectException()匹配PHPUnit\Framework\Error\Error将被移除”警告的场景非常局限:仅当你用expectException()去匹配PHPUnit内置的三个错误桥接类时才会出现。这三个类是PHPUnit为了兼容老版本写法,把PHP原生的非异常类错误(比如E_WARNING、E_NOTICE这类)转成可捕获对象设计的兼容层,从9.5开始,这类原生错误场景有了独立的专用断言方法,不再推荐复用通用的异常断言逻辑。 - 你当前触发警告的根本原因,不是断言
InvalidArgumentException的写法有问题,而是测试流程没有走到业务代码主动抛出自定义异常的分支:代码没有按预期抛出InvalidArgumentException,反而触发了PHP原生错误,被PHPUnit自动包装成内置的Error类,和你写的预期异常不匹配后抛出,最终触发了弃用提示。
分场景落地解决方案
场景1:业务代码确实设计为传空值时主动抛出InvalidArgumentException
这种场景完全不需要修改断言逻辑,先排查测试跑通的前置问题:
- 检查业务代码的参数校验逻辑是否生效,有没有遗漏空值判断、或者判断逻辑被其他try/catch块吞掉了异常
- 检查测试代码里的异常类引入路径是否正确,有没有因为类名拼写错误、命名空间错配导致预期异常匹配失败
- 校验完成后,原有断言写法完全兼容PHPUnit 9.5,不需要改动:
public function testFooErrorsOnBlankBar() { $this->expectException(InvalidArgumentException::class); $this->expectExceptionMessage('expected bar to be set'); My\Class::foo('', '123'); }
场景2:业务代码没有主动抛出自定义异常,仅靠PHP原生逻辑触发错误
如果代码实现是依赖PHP原生参数校验、没有主动抛业务异常,想要同时保留*“错误类型断言”的可读性*,有两种低侵入的实现方式:
自定义错误处理器转成可捕获异常
在测试的生命周期钩子中注册错误拦截器,把匹配规则内的原生错误转成自定义异常抛出,后续就可以完全复用原来的异常断言逻辑:protected function setUp(): void { parent::setUp(); set_error_handler(function (int $errno, string $errstr) { // 匹配需要拦截的错误,转成指定的业务异常抛出 if (str_contains($errstr, 'expected bar to be set')) { throw new InvalidArgumentException($errstr); } }); } protected function tearDown(): void { restore_error_handler(); parent::tearDown(); }这种实现下,依然可以直接写
$this->expectException(InvalidArgumentException::class),完全不需要依赖原生错误的专用断言方法,代码可读性和原有写法保持一致。使用PHPUnit内置的专用错误断言组合
如果不想自定义错误处理器,可以用内置的错误断言方法组合实现和异常断言对等的校验能力,不需要硬编码全量错误文本:public function testFooErrorsOnBlankBar() { // 声明预期触发的错误级别,完成错误类型层面的断言 $this->expectError(E_RECOVERABLE_ERROR); // 用正则匹配核心错误提示,避免硬编码全量文本导致测试脆弱 $this->expectErrorMessageMatches('/expected bar to be set/'); My\Class::foo('', '123'); }
很多开发者会误以为PHPUnit的
expectError()系列方法只能硬匹配错误文本,实际上它和expectException()的能力完全对等:可以同时对错误级别、错误代码、错误消息做多维度组合断言,只是面向的校验对象从“代码主动抛出的异常”换成了“PHP原生触发的错误”而已。
内容的提问来源于stack exchange,提问作者hollabaq
相关产品推荐
相关产品推荐

