Laravel 8 运行php artisan test无法生成代码覆盖率报告的问题

核心原因 #

• Laravel 8 内置的php artisan test命令未适配覆盖率参数透传，命令后追加的--coverage-html参数会被直接忽略，不会传递给底层调用的PHPUnit进程，命令执行时根本不会触发覆盖率收集逻辑。
• 现有配置采用的是PHPUnit 8及更早版本的语法规范，与Laravel 8自带的PHPUnit 9版本配置规则不兼容，旧版<logging>标签内的coverage配置、<filter><whitelist>结构会被PHPUnit 9直接跳过，配置无法生效。
• 缺少覆盖率收集必需的扩展或组件，会导致即使配置完全正确，也没有有效数据可以生成报告。

分步操作 #

1. 前置依赖校验 #

• 检查PHP环境是否安装覆盖率收集扩展（二选一即可）：
• 推荐选择轻量高速的pcov扩展
• 或选择功能更全的xdebug扩展
  校验命令：

php -m | grep -E 'pcov|xdebug'

命令能输出对应扩展名，才代表扩展安装生效。

• 检查项目是否安装匹配版本的PHPUnit代码覆盖率组件：

composer show phpunit/php-code-coverage

如果提示包不存在，执行composer require --dev phpunit/php-code-coverage安装和当前PHPUnit版本匹配的组件。

2. 修正phpunit.xml配置 #

删除配置中两段旧版无效内容：

• 删掉<logging>标签内的两条coverage相关log配置
• 删掉整个旧版的<filter><whitelist>块
  在配置文件中新增和<testsuites>、<php>平级的<coverage>标签，参考写法：

<coverage processUncoveredFiles="true">
  <include>
    <directory suffix=".php">./app</directory>
    <directory suffix=".php">./packages/okotieno</directory> <!-- 将自定义业务包路径纳入代码统计范围 -->
  </include>
  <report>
    <!-- HTML格式报告输出路径 -->
    <html outputDirectory="reports/coverage" />
    <!-- Clover格式报告输出路径 -->
    <clover outputFile="build/logs/clover.xml" />
  </report>
</coverage>

3. 执行测试生成报告 #

不要在php artisan test命令后追加覆盖率参数，直接调用项目内置的PHPUnit可执行文件运行测试，配置中定义好报告生成规则后，执行命令：

vendor/bin/phpunit

如果需要临时指定HTML报告输出路径，不需要在配置中写死，可直接在命令中追加参数：

vendor/bin/phpunit --coverage-html reports

排查注意点 #

• 不要把报告输出目录设置在tests目录的扫描范围内，比如将报告输出到tests/coverage，会导致PHPUnit把报告文件误识别为测试用例触发报错。
• 确认报告输出目录对当前PHP进程有写权限，避免因权限不足无法生成文件。
• 注意版本差异：Laravel从9版本开始才原生支持php artisan test --coverage参数，Laravel 8不具备这个能力。

内容的提问来源于stack exchange，提问作者Owen Kelvin