Laravel中自定义模块PHPUnit代码覆盖率统计失败的原因及解决

问题背景 #

非Laravel项目的正常配置 #

我在普通PHP项目中配置了双命名空间的PHPUnit测试，运行完全正常，具体配置如下：

文件夹结构：

├── docker-compose.yml
├── Dockerfile
├── composer.json
├── phpunit.xml
├── app/
│   └── Example.php
├── modules/
│   └── Example.php
└── tests/
    ├── AppTest.php
    └── ModulesTest.php

phpunit.xml核心配置：

<testsuites>
    <testsuite name="Tests">
        <directory>tests</directory>
    </testsuite>
</testsuites>
<source>
    <include>
        <directory>app</directory>
        <directory>modules</directory>
    </include>
</source>

composer.json自动加载配置：

"autoload": {
    "psr-4": {
        "App\\": "app/",
        "Modules\\": "modules/"
    }
}

执行覆盖率生成命令：

docker compose exec php ./vendor/bin/phpunit --coverage-html coverage-report

该项目的覆盖率报告可正常统计app和modules两个命名空间的代码覆盖情况。

Laravel项目的异常情况 #

将相同结构和配置复制到全新Laravel 10.48.24项目中后，出现以下问题：

• 项目环境：Laravel 10.48.24、PHP 8.2.26、PHPUnit 10.x（与非Laravel项目版本一致）
• Modules目录的测试可正常运行，但覆盖率报告仅包含app命名空间，完全忽略modules目录

已尝试的操作：

• 确认composer.json命名空间配置正确，执行过composer dump-autoload
• 保持两个项目的phpunit.xml结构一致
• 验证Modules目录的测试用例可成功执行

关键发现：

• Laravel项目仅比非Laravel项目多了框架自带的文件和依赖
• 但覆盖率报告始终无法统计Modules命名空间的代码

问题 #

为什么Laravel中PHPUnit代码覆盖率报告无法包含Modules命名空间？是否与Laravel的PHPUnit集成或自动加载配置有关？如何解决此问题，确保两个命名空间的覆盖率都能被统计？

原因分析及解决方案 #

核心原因 #

Laravel默认的PHPUnit集成存在隐性的代码过滤规则：框架预设的phpunit.xml配置可能仅将app目录纳入覆盖率统计范围，自定义的<source>配置可能被默认规则覆盖；同时，Laravel的自动加载优先级机制可能导致PHPUnit无法正确识别modules目录的代码文件。

解决方案 #

1. 完整覆盖phpunit.xml的source配置

修改Laravel项目的phpunit.xml，确保<source>部分明确包含modules目录，且配置完整无冲突：

<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="./vendor/phpunit/phpunit/phpunit.xsd"
         bootstrap="vendor/autoload.php"
         colors="true">
    <testsuites>
        <testsuite name="Tests">
            <directory>tests</directory>
        </testsuite>
    </testsuites>
    <source>
        <include>
            <directory suffix=".php">app</directory>
            <directory suffix=".php">modules</directory>
        </include>
    </source>
    <!-- 保留Laravel默认的PHP环境配置 -->
    <php>
        <env name="APP_ENV" value="testing"/>
        <env name="BCRYPT_ROUNDS" value="4"/>
        <env name="CACHE_DRIVER" value="array"/>
        <env name="DB_CONNECTION" value="sqlite"/>
        <env name="DB_DATABASE" value=":memory:"/>
        <env name="MAIL_MAILER" value="array"/>
        <env name="QUEUE_CONNECTION" value="sync"/>
        <env name="SESSION_DRIVER" value="array"/>
        <env name="SESSION_LIFETIME" value="120"/>
    </php>
</phpunit>

2. 优化Composer自动加载

执行带优化参数的自动加载生成命令，确保Modules命名空间的映射完全生效：

composer dump-autoload -o

3. 命令行强制指定覆盖目录

如果xml配置仍不生效，可通过PHPUnit命令行参数直接指定需要统计的目录：

docker compose exec php ./vendor/bin/phpunit --coverage-html coverage-report --coverage-filter app/ --coverage-filter modules/

4. 确认测试类基类

确保Modules目录的测试类继承纯PHPUnit的TestCase，而非Laravel框架的测试基类：

use PHPUnit\Framework\TestCase;

class ModulesTest extends TestCase
{
    // 测试逻辑
}

验证 #

重新执行覆盖率生成命令后，查看coverage-report/index.html，确认Modules命名空间的代码已被纳入统计范围。

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