PHP 单元测试：PHPUnit 入门与持续集成配置

学完这篇，你能在自己的 PHP 项目里跑起第一个单元测试，并让 GitHub 在每次提交时自动帮你跑一遍。

第一步：装 PHPUnit

PHPUnit 走 Composer 分发，在项目根目录执行：

composer require --dev phpunit/phpunit ^11

装完验证：

vendor/bin/phpunit --version

注意：PHPUnit 版本和 PHP 版本是强绑定的。PHPUnit 11 要 PHP 8.2+，PHPUnit 10 要 PHP 8.1+，PHP 7.4 的项目只能用 PHPUnit 9.x。装最新版在旧 PHP 上会直接依赖解析失败，别硬试。

第二步：写配置文件

根目录新建 phpunit.xml：

<?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"
         cacheDirectory=".phpunit.cache">
    <testsuites>
        <testsuite name="unit">
            <directory>tests</directory>
        </testsuite>
    </testsuites>
    <source>
        <include>
            <directory>src</directory>
        </include>
    </source>
</phpunit>

tests 是测试代码目录，src 是被测代码目录，按你的实际结构改。<source> 是 PHPUnit 10 之后的新写法，老教程里的 <filter><whitelist> 已经废弃。

第三步：写第一个测试

假设有个 src/Cart.php，测试文件放 tests/CartTest.php：

<?php
declare(strict_types=1);

use PHPUnit\Framework\TestCase;
use App\Cart;

final class CartTest extends TestCase
{
    public function testEmptyTotalIsZero(): void
    {
        $this->assertSame(0, (new Cart())->total());
    }
}

跑一下：

vendor/bin/phpunit

文件命名必须 *Test.php，类必须继承 TestCase，方法名以 test 开头（或加 #[Test] 属性）。

常用断言：assertSame（类型和值都相等，优先用这个）、assertEquals、assertTrue、assertNull、assertCount、expectException。

第四步：参数化与替身

同一段逻辑要测多组数据，用数据提供器，别复制粘贴：

#[DataProvider('priceProvider')]
public function testTotal(array $prices, int $expected): void
{
    $cart = new Cart();
    foreach ($prices as $p) {
        $cart->add($p);
    }
    $this->assertSame($expected, $cart->total());
}

public static function priceProvider(): array
{
    return [
        '单件' => [[100], 100],
        '多件' => [[100, 250], 350],
    ];
}

注意：PHPUnit 10 之后数据提供器必须是 public static，写成普通方法会直接报错——这是从老版本迁移时最常见的一处改动。

要隔离数据库、HTTP 这类外部依赖，用 createMock() 造替身，断言调用行为而不是真实副作用：

$mailer = $this->createMock(Mailer::class);
$mailer->expects($this->once())->method('send');

第五步：看覆盖率

vendor/bin/phpunit --coverage-text

注意：覆盖率依赖 Xdebug 或 PCOV 扩展，没装的话 PHPUnit 只会给一行警告，不给数字。别以为是自己配置写错了。

覆盖率是参考值不是 KPI，追 100% 通常换来一堆没意义的断言。核心业务逻辑（金额计算、权限判断、状态流转）优先覆盖。

第六步：接入持续集成

在项目根目录建 .github/workflows/tests.yml：

name: tests
on: [push, pull_request]

jobs:
  phpunit:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        php: ['8.1', '8.2', '8.3']
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php }}
          coverage: xdebug
      - run: composer install --prefer-dist --no-progress
      - run: vendor/bin/phpunit --coverage-text

提交后到仓库的 Actions 页就能看到结果，失败会标红并把断言差异打印出来。

几个要点：

• 矩阵里列几个 PHP 版本，就相当于同时验证几个环境，避免"我本地能跑"。
• 测试要连 MySQL 的话，用 job 级 services: 起一个 mysql 容器，再把连接参数通过环境变量传进去。
• composer.lock 必须提交，CI 里才能装出与本地一致的依赖版本；vendor/ 则要写进 .gitignore。

注意：CI 是无状态环境。任何依赖本地文件、本地数据库、绝对路径的测试都会挂，写测试时就要把这些东西做成可注入的配置。

用 GitLab 的话思路一样，.gitlab-ci.yml 里换成 image: php:8.3，加 before_script: composer install 即可。

小结

• 用 composer require --dev phpunit/phpunit 安装，PHPUnit 版本必须匹配 PHP 版本。
• phpunit.xml 里配 testsuites 和 source，后者是新版写法。
• 测试类继承 TestCase，断言优先用 assertSame。
• 数据提供器必须 public static，外部依赖用 createMock() 隔离。
• 覆盖率需要 Xdebug/PCOV；CI 用 GitHub Actions 矩阵跑多 PHP 版本，composer.lock 要提交。