PHPUnit 如何为 preg_match 的失败分支实现 100% 代码覆盖率？

PHPUnit 为 preg_match 包装方法实现完整测试时，需要先覆盖三个严格返回结果：正则匹配返回整数 1、不匹配返回整数 0、正则执行失败返回布尔 false。对失败分支使用一个确定无效的模式，例如只有起始分隔符的字符串，并断言业务异常。题目中的三个用例已经覆盖这三种结果；报告仍显示 Paths 50%、Branches 83.33%、Methods 0%，首先应修正覆盖率运行方式：`xdebug.mode=debug` 只启用单步调试，不启用代码覆盖，命令应使用 `xdebug.mode=coverage`，或设置等效的 `XDEBUG_MODE=coverage`。

还要区分行、分支、路径和方法覆盖。四行可执行代码都运行过，只能证明行覆盖为 100%；方法被判定为完整覆盖，通常要求它的所有可测路径都命中。开启 pathCoverage 后，Xdebug 按 PHP opcode 控制流统计路径，结果可能受 PHP、Xdebug 和 php-code-coverage 版本影响。不要为了追逐一个不稳定的 100% 数字添加没有业务意义的测试；先用 HTML 报告定位缺失分支，再验证三个公开契约和错误诊断是否完整。

preg_match 有三种严格返回值

PHP 官方手册定义 preg_match 的返回类型为 int 或 false。匹配成功返回 1，没有匹配返回 0，执行失败返回 false。

0 和 false 在宽松布尔判断中都为假，但语义完全不同：0 是有效结果，false 表示模式或执行过程出错。

因此包装器必须使用 `false === $result`，不能写 `if (!$result)`，否则合法的不匹配会被误判为异常。

三个最小测试

匹配用例传入能够命中主题字符串的有效模式，使用 assertTrue 验证包装后的布尔结果。

不匹配用例传入有效模式和不含目标的字符串，使用 assertFalse 验证它被正常转换为 false，而不是抛异常。

失败用例传入无法编译的模式，先声明 expectException，再调用方法。这样异常路径也成为可观察契约。

无效模式如何稳定触发失败

使用缺少结束分隔符或括号不配对的模式，可以让 PCRE 编译失败。测试数据应简短且意图清晰。

不要依赖超长输入、回溯限制或 JIT 栈限制制造失败，这些条件受 php.ini、PCRE 版本和机器资源影响。

测试目标只是进入 preg_match 返回 false 的分支，编译期无效模式通常最稳定。

为什么代码使用错误抑制符

无效正则会产生 E_WARNING，同时 preg_match 返回 false。包装器若打算把底层警告转换为领域异常，常会在调用前使用错误抑制符。

测试不应把警告输出污染当成失败分支本身。真正契约是调用者收到指定异常。

但错误抑制会隐藏诊断信息。生产异常可附带 preg_last_error_msg 的安全文本，不能只抛一个无上下文类型。

运行命令中的核心错误

`xdebug.mode=debug` 启用的是 Step Debugging，用于断点与变量检查。它不是 Coverage Analysis。

生成覆盖报告时使用 `php -d xdebug.mode=coverage vendor/bin/phpunit --coverage-text`。环境变量形式也可以在命令前设置覆盖模式。

同时启用 debug 和 coverage 虽可工作，但会增加开销。CI 覆盖任务只启用 coverage 更清晰。

先确认实际生效的 Xdebug 模式

容器、CLI 与 PHP-FPM 可能读取不同 php.ini。网页中看到 Xdebug 已启用，不代表 PHPUnit 的 CLI 进程启用了 coverage。

在同一容器、同一 PHP 二进制中检查 Xdebug 配置，并观察 PHPUnit 启动信息里的覆盖驱动。

若设置 XDEBUG_MODE，注意进程管理器是否允许该环境变量传入。命令行临时 `-d` 更适合最小复现。

行覆盖率说明什么

行覆盖记录可执行源码行是否至少运行一次。异常行、返回行和判断行都命中后，可以得到 100% Lines。

同一行包含多个表达式或分支时，执行该行不代表所有结果都发生过。因此行覆盖无法证明 1、0、false 都测试。

行覆盖适合快速发现完全未运行代码，但不能单独作为复杂条件的充分证据。

分支覆盖率说明什么

分支覆盖关注控制流节点的不同出口。`if (false === $result)` 至少有进入异常和继续执行两个方向。

返回表达式中的类型转换也可能在 opcode 控制流图中产生不同出口，具体呈现由引擎与驱动决定。

Branches 83.33% 表示仍有一个驱动识别的出口未命中，不等于源码中明显少了六分之一的 if。

路径覆盖率说明什么

路径覆盖要求从方法入口到出口的每条可执行控制流组合都运行。多个判断组合后，路径数可能快速增加。

题目报告中的 2/4 路径说明 Xdebug 为该方法识别了四条 opcode 路径，测试只命中两条。

要知道缺哪两条，必须查看 HTML 报告中的分支与路径详情，不能仅凭文本摘要猜测。

方法覆盖为何显示 0%

方法指标通常把方法视为整体：只要该方法还有未覆盖路径，就不计为完整覆盖。

所以一个方法每行都执行过，Methods 仍可能显示 0/1。这不是说方法从未调用。

阅读报告时同时看 Lines、Branches、Paths，避免把汇总百分比当成调用计数。

使用 HTML 报告定位

文本报告适合 CI 摘要，HTML 报告更适合诊断。它能展开文件、方法和控制流信息。

生成报告后打开 StringValidator 页面，查看未命中的 branch 和 path 标识，再关联到源码行。

若报告只显示行颜色，没有分支路径，检查 pathCoverage 配置和当前驱动能力。

PCOV 与 Xdebug 的差别

PHPUnit 官方文档说明，分支和路径覆盖需要 Xdebug；PCOV 只提供行覆盖。

若团队只设置行覆盖门槛，PCOV 通常更轻量。需要诊断复杂控制流时再使用 Xdebug。

不能用 PCOV 生成的 100% 行覆盖与 Xdebug 的路径覆盖直接比较，它们测量的不是同一指标。

pathCoverage 配置的代价

启用路径覆盖会增加分析与执行开销。Xdebug 需要收集 opcode 级分支和入口到出口的路径。

大型套件可把快速行覆盖放在常规 CI，把路径覆盖放在主干或定期质量任务。

不要因为覆盖任务变慢就扩大超时而不测量；应先限制覆盖过滤器只包含业务源码。

覆盖过滤器要准确

include 目录应指向实际源码根目录，exclude 只排除明确不纳入质量门槛的生成代码或边界层。

使用多层通配排除容易遗漏或误排。生成 HTML 报告后确认 StringValidator 文件确实来自预期路径。

过滤器应在代码首次加载前生效，因为 Xdebug 在 PHP 编译文件时决定是否采集。

不要先怀疑 PHPUnit 缓存

结果缓存主要保存测试运行信息，覆盖缓存用于分析性能。反复删除缓存不能修复未启用的 Xdebug coverage 模式。

先检查运行时、驱动、过滤器和报告详情，再用清缓存排除明确的版本或源码漂移。

把删除缓存写成每次 CI 固定步骤会拖慢运行，也掩盖真正配置问题。

严格比较必须保留

包装代码中的 `false === $result` 是正确边界。返回 0 时该条件为假，继续转成布尔 false；返回 false 时进入异常。

若改为 `false == $result`，整数 0 也相等，未匹配测试将错误抛异常。

测试应保留对未匹配的 assertFalse，它能防止未来重构破坏严格比较。

测试返回 1

选择简单确定模式和主题，例如字面量匹配，不要使用依赖区域、Unicode 属性或复杂回溯的表达式。

断言包装方法返回 true，而不是直接比较底层整数 1，因为公开返回类型是 bool。

此用例证明正常命中路径和布尔转换成立。

测试返回 0

模式必须有效，只是主题不匹配。这样才能把“合法否定”与“执行失败”分离。

断言返回 false，并确保没有异常。必要时不设置 expectException，让任何异常自然使测试失败。

这个用例是严格返回值设计中最容易被宽松判断破坏的回归保护。

测试返回 false

传入明确无效模式，声明 InvalidRegexPatternException。若异常含错误码，可同时断言其类型化属性。

不要依赖异常消息的完整 PCRE 文案，底层版本可能改变措辞。业务异常可保留稳定代码。

该用例证明失败不会被伪装成普通不匹配。

preg_last_error_msg 的使用

PHP 8 提供 preg_last_error_msg，可在 preg_match 失败后返回最近一次 PCRE 错误文本。

必须紧接失败调用读取，避免同一进程中后续正则操作覆盖错误状态。

异常可记录错误码与受控消息，但不要记录包含敏感主题文本的完整输入。

错误处理可以封装

直接在业务代码各处使用 `@preg_match` 会重复严格判断和诊断逻辑。集中包装器能建立一致契约。

包装器返回 bool，只在 PCRE 失败时抛领域异常。调用者无需记忆 int 或 false 三态。

测试也聚焦包装边界，不需要在每个消费者重复制造无效模式。

不要 Mock preg_match

preg_match 是 PHP 内置函数，通常应使用真实、确定输入测试。为了覆盖失败而引入命名空间函数替身会增加生产结构复杂度。

只有需要稳定模拟无法轻易触发的资源限制错误时，才考虑注入 RegexEngine 接口。

本题的编译失败可以可靠触发，无需 Mock。

什么时候注入适配器

如果业务必须区分回溯限制、UTF-8 错误、JIT 栈错误等多种失败，可让适配器返回结果对象。

结果对象包含 matched、errorCode 和 errorMessage，领域层再决定重试、拒绝或记录。

适配器测试真实 PCRE 的少量集成场景，领域策略用 Fake 覆盖所有错误分类。

无效 UTF-8 分支

带 u 修饰符的模式遇到无效 UTF-8 主题可能失败，并设置对应 PREG 错误。

这与模式编译失败是不同原因。如果包装器只承诺统一异常，一个无效模式用例已覆盖控制流。

若异常类型或错误码需要区分，则添加字节级输入测试，并注明它依赖 PCRE 与 PHP 行为。

回溯限制分支

灾难性回溯可能触发 PREG_BACKTRACK_LIMIT_ERROR，但构造样本容易受限制值与引擎优化影响。

测试前临时设置明确的 pcre.backtrack_limit，并在 finally 中恢复，避免污染其他测试。

只有产品确实处理该错误时才测试，不应为提高路径百分比制造脆弱样本。

错误抑制符的替代方案

可以安装临时错误处理器，将目标 E_WARNING 转换为 ErrorException，再在 finally 恢复处理器。

这种方式获得警告文本，但必须避免捕获无关错误，并正确处理 PHP 版本差异。

简单包装器使用抑制符后读取 PCRE 错误通常更直接，选择应由诊断需求决定。

覆盖率版本必须成组记录

报告结果由 PHP、Xdebug、PHPUnit 和 php-code-coverage 共同产生。升级任一组件都可能改变 opcode 与路径统计。

CI 保存四者版本和生成命令。不能拿旧环境的 2/4 路径与新环境数字直接判断测试退步。

依赖升级后先审查控制流报告差异，再调整门槛。

PHPUnit 9 与新版本配置差异

题目使用 PHPUnit 9.6，而当前文档示例可能来自更高版本。XML schema、属性和命令选项可能变化。

先使用当前安装版本的 `--version` 和配置校验，不要未经迁移直接复制新版本 XML。

修复 Xdebug 模式属于跨版本稳定原则，但 Covers 属性与严格覆盖元数据需按项目版本处理。

覆盖元数据不是执行覆盖

@covers 或 CoversClass 告诉 PHPUnit 哪些代码由测试负责，避免无意执行被计入覆盖。

它不会让遗漏路径变为已覆盖，也不会启用 Xdebug coverage。

先确保元数据指向完整命名空间类，再诊断运行时控制流。

为何完整行数仍值得保留三个用例

如果只写匹配用例，判断行和返回行都可能变绿，但异常与不匹配语义没有验证。

三个用例表达 API 的三态输入与两态业务输出，比一个汇总百分比更能帮助维护者理解契约。

覆盖率用来发现遗漏，测试名称与断言用来证明行为。

数据提供器是否更合适

匹配和不匹配可以放入数据提供器，输入模式、主题和预期 bool。失败异常通常保留独立测试。

独立用例的结果更容易定位；数据提供器适合增加多组等价边界。不要为减少行数牺牲意图。

无论形式如何，确保失败、0 和 1 都是独立可识别样本。

Mutation Testing 的价值

100% 覆盖只说明执行过代码，不证明断言能发现错误。变异测试可以把严格比较改成宽松比较，观察测试是否失败。

也可删除异常、固定返回 true 或反转结果。若测试仍绿，说明断言不足。

对这种短包装器，变异得分往往比追求 opcode 路径 100% 更有解释力。

合理的 CI 门槛

项目可以对行覆盖设稳定门槛，并对关键解析与校验代码要求明确分支测试。

路径覆盖受工具版本与控制流图影响较大，适合诊断，不一定适合所有文件的硬性 100% 门槛。

门槛失败时报告具体未覆盖文件与分支，不能只输出一个总百分比。

一个可靠的执行顺序

先无覆盖运行三个测试，确认行为正确。再用 Xdebug coverage 模式生成文本摘要和 HTML 报告。

确认运行时显示 Xdebug 驱动，过滤器包含目标源码，HTML 中三条业务路径可见。

若仍缺 opcode 路径，制作最小独立项目，锁定四个组件版本，再判断是代码结构还是工具报告问题。

最小复现要包含什么

只保留 StringValidator、异常类、三个测试、composer 依赖和最小 phpunit.xml。

记录 PHP 与 Xdebug 版本、实际 mode、完整 PHPUnit 命令和覆盖摘要。不要携带大型项目排除规则。

最小复现若达到完整覆盖，说明原项目问题位于配置、过滤器、预加载或版本组合。

常见误区

误区一是把 `debug` 当成覆盖模式；误区二是把 0 和 false 用宽松判断合并；误区三是把 Lines 100% 当作 Paths 100%。

误区四是删除 PHPUnit 缓存代替验证运行配置；误区五是用脆弱资源限制样本追逐统计数字。

误区六是看到 Methods 0% 就认为方法未执行，而忽略其完整路径判定。

测试检查清单

确认有效匹配返回 true，有效不匹配返回 false，无效模式抛业务异常。

确认生产代码使用 `false === $result`，异常诊断在失败调用后立即读取。

确认 CLI 使用 Xdebug coverage 模式，pathCoverage 开启时驱动确实支持分支与路径。

确认过滤器只包含目标源码，HTML 报告用于定位具体 branch 和 path。

确认覆盖工具版本已记录，质量门槛强调业务契约而非孤立百分比。

结论

preg_match 包装器的失败分支可以用确定无效模式覆盖，但本题报告异常的首要原因是 Xdebug 只启用了 debug 而不是 coverage。

修正运行模式后，三个测试分别覆盖 1、0 和 false。严格比较确保不匹配不会被误判为执行错误。

若行覆盖已经 100% 而路径仍不足，应查看 Xdebug 的 opcode 路径详情并核对版本，不要凭摘要盲目添加测试。测试真正要证明的是匹配、不匹配与失败三个公开行为，而不是让每个工具版本都显示同一个漂亮数字。