如何让PHPUnit检测curl请求对应的服务端Xdebug代码覆盖率？

核心问题是：PHPUnit的覆盖率会话运行在测试进程，而curl触发的API请求是服务端独立进程（比如PHP-FPM），两者的覆盖率数据默认不互通。要实现合并，得让服务端进程把覆盖率数据持久化，再让PHPUnit进程读取合并。

步骤1：修改curl请求，传递测试会话标识 #

在你的curl请求里添加自定义Cookie，标记这是测试请求，同时传递唯一会话ID，方便后续区分覆盖率文件：

// 生成唯一会话ID，也可以用当前测试方法名保证唯一性
$sessionId = uniqid('coverage_');
// 添加Cookie告诉服务端要收集覆盖率
curl_setopt($ch, CURLOPT_COOKIE, "XDEBUG_COVERAGE_SESSION={$sessionId}");

步骤2：服务端调整覆盖率收集逻辑 #

修改服务端入口文件（如index.php），检测到测试会话Cookie时，启动覆盖率收集，并在请求结束后把数据写入临时文件：

// 检查是否为测试覆盖率请求
if (isset($_COOKIE['XDEBUG_COVERAGE_SESSION'])) {
    $sessionId = $_COOKIE['XDEBUG_COVERAGE_SESSION'];
    // 启动覆盖率收集（保持你原有的参数配置）
    xdebug_start_code_coverage(XDEBUG_CC_UNUSED | XDEBUG_CC_DEAD_CODE);
    
    // 注册 shutdown 函数，请求结束时保存覆盖率数据
    register_shutdown_function(function() use ($sessionId) {
        $coverageData = xdebug_get_code_coverage();
        xdebug_stop_code_coverage(true); // 当前进程结束，无需保留会话
        
        // 保存到临时文件，Docker环境要确保路径可读写
        $tempFile = "/tmp/coverage_{$sessionId}.dat";
        file_put_contents($tempFile, serialize($coverageData));
    });
}

// 原有服务端业务逻辑...

步骤3：PHPUnit中合并覆盖率数据 #

推荐用PHPUnit扩展实现全局覆盖率合并，也可以在单个测试类中处理：

方法A：全局PHPUnit扩展（推荐） #

创建CoverageMergerExtension.php：

<?php
use PHPUnit\Runner\AfterTestHook;
use SebastianBergmann\CodeCoverage\CodeCoverage;

class CoverageMergerExtension implements AfterTestHook
{
    public function executeAfterTest(string $test, float $time): void
    {
        // 读取所有临时覆盖率文件
        $tempFiles = glob("/tmp/coverage_*.dat");
        $coverage = $this->getCurrentCoverage();
        
        foreach ($tempFiles as $file) {
            $serverCoverage = unserialize(file_get_contents($file));
            // 合并覆盖率数据
            foreach ($serverCoverage as $filePath => $lines) {
                if (!$coverage->hasFile($filePath)) {
                    $coverage->addFileToWhitelist($filePath);
                }
                $coverage->setData($filePath, $lines);
            }
            // 删除临时文件，避免累积
            unlink($file);
        }
    }
    
    private function getCurrentCoverage(): CodeCoverage
    {
        return $GLOBALS['PHPUNIT_COVERAGE'];
    }
}

在phpunit.xml中注册扩展：

<phpunit>
    <!-- 原有配置 -->
    <extensions>
        <extension class="CoverageMergerExtension"/>
    </extensions>
</phpunit>

方法B：单个测试类中处理 #

class ApiTest extends PHPUnit\Framework\TestCase
{
    public static function tearDownAfterClass(): void
    {
        $tempFiles = glob("/tmp/coverage_*.dat");
        $coverage = self::$coverage; // 通过PHPUnit内部变量获取覆盖率实例
        
        foreach ($tempFiles as $file) {
            $serverCoverage = unserialize(file_get_contents($file));
            // 合并逻辑同上
            foreach ($serverCoverage as $filePath => $lines) {
                if (!$coverage->hasFile($filePath)) {
                    $coverage->addFileToWhitelist($filePath);
                }
                $coverage->setData($filePath, $lines);
            }
            unlink($file);
        }
    }
}

步骤4：调整Xdebug和PHPUnit配置 #

1. 服务端Xdebug配置确保开启coverage模式：

[xdebug]
xdebug.remote_enable=1
xdebug.remote_host="host.docker.internal"
xdebug.idekey=docker
xdebug.mode=coverage,debug
xdebug.remote_log="/tmp/xdebug.log"

（如果是Xdebug 3版本，需将xdebug.remote_*替换为xdebug.client_*系列配置，比如xdebug.client_host）

2. 运行PHPUnit的命令保持原有配置即可：

/usr/bin/php -dxdebug.mode=coverage /usr/share/php/phpunit.phar --coverage-clover unitTest_xml --configuration configuration.xml --teamcity

关键注意事项 #

• Docker路径共享：确保/tmp目录在测试容器和服务端容器之间通过volume挂载共享，否则测试进程无法读取服务端生成的临时文件。
• 会话ID唯一性：每个curl请求使用唯一会话ID，避免不同测试用例的覆盖率数据互相覆盖。
• Xdebug版本兼容：严格区分Xdebug 2和Xdebug 3的配置项差异，避免因版本不匹配导致功能失效。

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