PHP TDD完整实践：从PHPUnit配置到CI集成与踩坑指南

说实话，我干了十几年 PHP，早年也是"先写完功能再说"那一派的。线上改一行代码、手一抖把>写成>=，结果整站订单金额全错这种事，摊上一次就够你记一辈子。后来我认真把 TDD（Test-Driven Development，测试驱动开发）在 PHP 项目里完整走了一遍，从环境搭建到 CI 集成都摸了一遍，才意识到：PHP 这种动态弱类型语言，恰恰是最需要 TDD 兜底的。这篇文章就把我在 PHP 里跑通 TDD 完整流程的整套方案写出来，包括工具选型、红绿重构循环、数据库和队列怎么测、以及我踩过的那些坑。不管你是刚接触测试的新手，还是团队想推测试文化的老兵，这套流程都能直接抄作业。

1. 为什么 PHP 项目尤其需要 TDD：从一次线上事故说起

1.1 PHP 项目的"裸奔"现状

PHP 上手快、部署简单，这是它的优点，但也是它的诅咒。Java 有编译器帮你查类型错误，Go 有严格的静态检查，而 PHP 呢？变量可以不声明直接用，数组和对象的形态可以随手变，一个函数传错类型，很多时候不是报错，而是静默地把null或者0传下去，最后在离事故现场十万八千里的地方炸开。

我做过的很多 PHP 项目，尤其是用原生 PHP 或者轻量框架写的那种，测试覆盖率常年是零。大家不写测试的理由也高度一致：业务赶、老板催、测试写起来啰嗦。结果就是，代码库越改越乱，一个看似无关的小改动，可能把三个月前正常的功能干趴。

1.2 那次事故：改动一行，全站订单金额错误

有一次，客户提了个需求：会员折扣从"满 1000 减 50"改成"满 1000 打 9 折"。我心想这不就改一行比较逻辑吗？改完本地手点了几下，看着没问题，直接上了生产。结果当天晚上工单就爆了——有一批用户的订单金额算出来是负数。

排查了一整夜，最后发现根因是：我改的那段折扣逻辑，被另一个模块在某种特殊条件下二次调用，而那个条件分支里$subtotal还没初始化，传进来的是null。null * 0.9在 PHP 里不会报致命错误，而是得到0，再走一轮减价逻辑，订单就变负数了。

那一刻我特别想把 PHP 骂一顿，但冷静下来想想，根子不在语言，在流程。如果我先写一个"折扣计算必须正确处理空值"的测试，这个 bug 在写代码的那一刻就会被拦下来，根本活不到生产环境。也是从那以后，我开始认真研究 PHP 里的 TDD。

1.3 TDD 与"事后补测试"的本质区别

很多人觉得"写测试"和"TDD"是一回事，其实差得很远。事后补测试，是你先把代码写完、bug 已经埋进去了，再用测试去"证明"代码没事。这时候你的潜意识会不自觉地把测试写成"配合实现"，怎么都能过。而 TDD 的核心纪律是：先写一个会因为需求未实现而失败的测试，再写让它通过的最简代码。测试先行，意味着你被迫在动手前想清楚"到底要什么样的行为"，而不是写着写着把需求写歪。

TDD 的循环就三个字：红、绿、重构。红，是你的新测试跑不过去，因为功能还不存在；绿，是最小改动让测试通过；重构，是在保证全绿的前提下顺手优化设计。这三个字看着简单，真正执行起来门道不少，后面我用一个订单折扣的例子完整演示一遍。

提示：TDD 不是银弹，它管不了"需求本身是错的"这种问题。但它能保证你写出来的每一行代码，都有明确的、可验证的行为契约。

2. 工具链准备：PHPUnit 为主，Xdebug 作为覆盖率支撑

2.1 用 Composer 初始化项目并安装 PHPUnit

在 PHP 世界里做 TDD，绕不开的工具就是 PHPUnit。它是事实上的标准测试框架，生态最成熟，文档最全，踩坑资料也最多。第一步先把项目用 Composer 初始化：

composer init composer require --dev phpunit/phpunit:^11.0

我用的是 PHPUnit 11，搭配 PHP 8.2 以上。如果项目还在 PHP 7.4 或 8.0，建议用 PHPUnit 9 或 10，版本兼容性问题在 PHP 生态里非常常见，别盲目追新。

接下来安排目录结构。PHP 社区比较通用的做法是这样：

project/ ├── composer.json ├── phpunit.xml ├── src/ # 业务代码 └── tests/ ├── Unit/ # 纯逻辑单元测试 └── Feature/ # 涉及数据库、HTTP、队列的集成测试

然后去composer.json里配上 PSR-4 自动加载：

{ "autoload": { "psr-4": { "App\\": "src/" } }, "autoload-dev": { "psr-4": { "App\\Tests\\": "tests/" } } }

改完记得跑composer dump-autoload，不然新加的命名空间映射不会生效。这个步骤我见过太多人漏掉，然后一脸懵地报 Class not found。

2.2 phpunit.xml 的关键配置项

PHPUnit 运行时读的配置文件是phpunit.xml，我建议从一开始就配齐，不要裸跑命令行。这是我在实际项目里沉淀下来的一份基础配置：

<?xml version="1.0" encoding="UTF-8"?> <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" bootstrap="vendor/autoload.php" colors="true" failOnWarning="true" failOnRisky="true" cacheDirectory=".phpunit.cache"> <testsuites> <testsuite name="unit"> <directory>tests/Unit</directory> </testsuite> <testsuite name="feature"> <directory>tests/Feature</directory> </testsuite> </testsuites> <source> <include> <directory>src</directory> </include> </source> </phpunit>

有几个点值得展开说一下。

failOnWarning="true"和failOnRisky="true"是我强烈建议打开的。PHPUnit 有时候会给你"警告"，比如测试里执行了error_log、或者测试没有做任何断言。默认情况下这些只是警告，不会让 CI 变红，但恰恰是这些"软性信号"能暴露出测试写的烂。我打开这两个选项之后，逼着自己把一批"假测试"全部修掉了。

bootstrap="vendor/autoload.php"的作用是让测试环境能自动加载你的类和测试类。如果没有这个，每个测试文件里都要手动require一堆文件，那体验就太痛苦了。

2.3 为什么主力选 PHPUnit，而不是 Pest 或 Codeception

经常有人问我，Pest 写起来更简洁，Codeception 能测浏览器行为，为什么不用？我把三者的特点整理成一张表，方便你按场景选：

我的建议是：第一个项目老老实实用 PHPUnit。不是因为 Pest 不好，而是 PHPUnit 的报错信息、调试方式、和各类框架的整合资料最全。等你把 TDD 的红绿重构循环练熟了，再去看 Pest 完全不迟。至于 Codeception，我更愿意把它定位成"验收测试"工具，而不是日常 TDD 的主力。

2.4 Xdebug 与覆盖率统计

覆盖率统计需要 Xdebug 或者 PCOV 扩展。我日常用 Xdebug，因为除了覆盖率之外，调试也靠它。现在的 Xdebug 3 配置比早期简单多了，只需要在php.ini里写：

xdebug.mode=coverage

如果你还要用断点调试，那就写成xdebug.mode=debug,coverage。跑覆盖率的时候用：

vendor/bin/phpunit --coverage-text

这个命令会输出一个简单的文本报告，标明每个文件的行覆盖率是多少。我通常不追求 100%，后面会讲我怎么设质量门槛，这里只提醒一句：覆盖率数字只是参考，别把它当 KPI 供起来。

3. TDD 核心循环实战：红-绿-重构，跑通一个订单折扣案例

3.1 第一步（红）：先写一个注定失败的测试

理论讲再多，不如撸一个真实例子。假设我们要实现一个订单折扣功能：VIP 会员下单总额打 9 折。按照 TDD 的规矩，我先写测试，而且写的当下，Order类根本不存在。

<?php declare(strict_types=1); namespace App\Tests\Unit; use App\Order; use App\Customer; use PHPUnit\Framework\TestCase; final class OrderTest extends TestCase { public function testVipCustomerGetsTenPercentDiscount(): void { $customer = new Customer(type: 'vip'); $order = new Order(subtotal: 1000.0, customer: $customer); $this->assertSame(900.0, $order->total()); } }

跑一下测试：

vendor/bin/phpunit --filter testVipCustomerGetsTenPercentDiscount

结果毫无疑问是红的，报错要么是 Class "App\Order" not found，要么是找不到方法。这一步的"失败"是预期的，红的测试越明确，待会儿绿的信心就越足。认真看一眼报错信息，确认它失败在"类不存在"而不是"类存在但断言不对"，这也是一种基本功。

3.2 第二步（绿）：用最简代码让测试通过

红色的测试已经定义了边界：Order接收subtotal和customer，total()方法要返回打折后的金额。现在我用最少的代码让测试变绿：

<?php declare(strict_types=1); namespace App; final class Order { public function __construct( private readonly float $subtotal, private readonly Customer $customer ) { } public function total(): float { if ($this->customer->type === 'vip') { return $this->subtotal * 0.9; } return $this->subtotal; } }

对应的Customer类也建一个最简版本：

<?php declare(strict_types=1); namespace App; final class Customer { public function __construct( public readonly string $type ) { } }

再跑测试，绿的。这里有个 TDD 的关键纪律：绿了之后立刻停下来，不要顺手加功能。很多人的毛病就是走得太快，测试刚通过就开始"反正写着呢，把普通会员的 95 折也加上吧"。这会破坏 TDD 的小步快跑节奏，下一轮需求万一变了，你刚才的"顺手"全是返工成本。

3.3 第三步（重构）：优化设计，再补边界测试

第三个测试快速通过之后，马上进入重构阶段。现在这个折扣逻辑直接写死在Order::total()里，如果后续再加员工 85 折、节假日 8 折，这个类很快会膨胀成一堆if。趁现在测试全绿，我先做一轮小重构，把折扣计算抽出去：

<?php declare(strict_types=1); namespace App; final class DiscountCalculator { public function apply(float $subtotal, Customer $customer): float { return match ($customer->type) { 'vip' => $subtotal * 0.9, 'staff' => $subtotal * 0.85, default => $subtotal, }; } }

再看Order，变成这样：

<?php declare(strict_types=1); namespace App; final class Order { public function __construct( private readonly float $subtotal, private readonly Customer $customer, private readonly DiscountCalculator $discountCalculator = new DiscountCalculator() ) { } public function total(): float { return $this->discountCalculator->apply($this->subtotal, $this->customer); } }

重构完马上跑全量测试，确认还是绿的。然后，我接着用 TDD 的方式补员工折扣和普通用户的用例：

public function testStaffCustomerGetsFifteenPercentDiscount(): void { $order = new Order(subtotal: 1000.0, new Customer(type: 'staff')); $this->assertSame(850.0, $order->total()); } public function testNormalCustomerPaysFullPrice(): void { $order = new Order(subtotal: 1000.0, new Customer(type: 'normal')); $this->assertSame(1000.0, $order->total()); }

这两个测试同样先红后绿——严格来说，员工 85 折的行为已经在重构时实现了，但测试还没写，所以你写出来的那一刻跑一下，理论上会是绿的。这不是犯规，而是重构保护下的"行为已经存在、契约还没固化"的场景。补上之后，这套订单折扣的契约就算彻底锁定了。

3.4 这个案例里的三个关键认知

走完一遍红绿重构，有几个体会是纯看文档得不到的。

第一，步子要小。我见过太多人写测试一次写几百行，红了之后蒙圈，因为根本不知道是哪一行导致的。正确的姿势是一次只写一个断言，一次只让它过一步。

第二，最简实现不等于最终实现。绿的阶段允许你写很笨的代码，只要测试通过就行。真正让代码变漂亮的是重构阶段。很多人混淆了这两步，结果就是测试没写好，代码也没写稳。

第三，测试是设计工具，不只是验证工具。当我写new Order(subtotal: 1000.0, customer: $customer)的时候，我实际上是在设计Order的构造器参数。如果参数顺序容易记混，如果某个依赖让测试很难构造，那这个设计大概率有问题。TDD 会把这类"坏味道"提前暴露出来。

4. 数据库、队列与外部接口：PHP 项目里最难测的三种依赖

4.1 数据库：用 SQLite 内存库还是测试库？

很多 PHP 项目里，业务逻辑和数据库查询是缠在一起的，这让测试变得很麻烦。我的经验是分两层处理：纯逻辑用单元测试，涉及数据库的用 feature test。

feature test 里最省事的方式是 SQLite 内存库。在phpunit.xml或者测试基类里把连接切到sqlite::memory:，然后在每个测试方法开始前建表、结束后回滚。Laravel 项目里自带的RefreshDatabasetrait 就是这个思路的封装。但如果你用的是原生 PDO 或者自研的轻量框架，可以自己写一个简单的测试基类：

<?php declare(strict_types=1); namespace App\Tests\Feature; use PDO; use PHPUnit\Framework\TestCase; abstract class DatabaseTestCase extends TestCase { protected PDO $pdo; protected function setUp(): void { $this->pdo = new PDO('sqlite::memory:'); $this->pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION); $this->pdo->exec('CREATE TABLE orders (id INTEGER PRIMARY KEY, amount REAL, customer_type TEXT)'); } protected function tearDown(): void { $this->pdo = null; } }

用 SQLite 内存库的好处是快、隔离、不需要外部服务。坏处是它和 MySQL/PostgreSQL 的 SQL 方言有差异，某些查询（比如 JSON 字段操作、特定的聚合语法）在 SQLite 里可能表现不一样。所以我会在团队里定一条规则：单测和 CI 全绿只是底线，发布前必须有人在真实数据库上跑一遍冒烟测试。

4.2 外部 API：PHPUnit Mock 的正确姿势

真实场景里，订单结算要调支付网关、要调短信服务、要调物流查询。这些外部 API 不可能在测试环境里真实调用，一来慢，二来不可控，三来可能产生真实扣款。处理方式就是 Mock——造一个替身对象，定义好它该被怎么调用、返回什么结果。

看一个支付网关的测试：

<?php declare(strict_types=1); namespace App\Tests\Unit; use App\PaymentGateway; use App\Order; use App\Customer; use PHPUnit\Framework\TestCase; final class CheckoutTest extends TestCase { public function testCheckoutChargesDiscountedAmount(): void { $gateway = $this->createMock(PaymentGateway::class); $gateway->expects($this->once()) ->method('charge') ->with($this->equalTo(900.0)) ->willReturn(true); $customer = new Customer(type: 'vip'); $order = new Order(subtotal: 1000.0, customer: $customer); $checkout = new Checkout($gateway); $result = $checkout->run($order); $this->assertTrue($result); } }

这里最核心的是expects($this->once())和with($this->equalTo(900.0))。它们不光验证"调用成功返回 true"，还验证了调用次数和调用参数。如果下单逻辑里不小心传了原价 1000 而不是折后价 900，测试会直接红。

Mock 的一个常见误区是"为了让测试过，把 Mock 配得无限宽松"。method('charge')->willReturn(true)这种写法虽然能让测试绿，但它没有验证任何交互细节，掩盖的问题和没有测试差不多。我现在的习惯是：关键业务路径上的外部调用，一定要用expects明确次数和参数；只有无关紧要的辅助服务才用松散的method。

4.3 Redis 队列、缓存场景的测试思路

PHP 项目里越来越常见的一种架构是：接口收到请求，把任务丢进 Redis 队列，后台 worker 消费处理。这种异步逻辑特别容易变成"测试盲区"，因为默认的 PHPUnit 测试是一次性的，不会自动等 worker 跑完。

我的做法分两种情况。

如果队列消费逻辑本身是核心业务（比如订单超时关单），我会把"消费者"写成纯 PHP 类，输入是任务数据，输出是处理结果，然后对消费者类做单元测试。测试里 Mock 掉 Redis 客户端：

<?php declare(strict_types=1); namespace App\Tests\Unit; use App\OrderCloseConsumer; use PHPUnit\Framework\TestCase; use Redis; final class OrderCloseConsumerTest extends TestCase { public function testConsumerClosesExpiredOrder(): void { $redis = $this->createMock(Redis::class); $redis->method('brpop') ->willReturn(['order_queue', json_encode(['order_id' => 12345])]); $sut = new OrderCloseConsumer($redis); $result = $sut->processOne(); $this->assertTrue($result); } }

如果只是想验证"任务被正确投递到队列"，那直接 Mock 生产者，断言调用了lpush且参数正确，和 4.2 节的思路一样。

另一种情况是团队里已经搭了测试用的 Redis 实例，那我会跑一个小的集成测试：真实地lpush一条数据，再同步调用消费者处理，验证数据库里的状态变化。这种测试跑得慢一点，但覆盖链路更真实。我的原则是：能 Mock 就 Mock，Mock 不了的才上真实依赖，永远不要依赖一个连 CI 环境都没有的外部服务。

5. 踩坑实录：测试全绿，但上线还是炸了的五个原因

5.1 坑一：测试之间存在顺序依赖

PHPUnit 默认按字母顺序跑测试，但它不保证每个测试方法之间的状态完全隔离。我踩过最典型的一次：tests/Unit/OrderTest.php里的某个测试往一个静态数组里塞了数据，下一个测试读这个静态数组，单跑没问题，全量跑就报错。

后来我把全量跑的顺序打乱（--order-by=random），果然又红了一片，说明测试之间确实有隐性的顺序依赖。从那以后我定了两条死规矩：每个测试方法必须完全自给自足，setUp 里重建所有依赖，tearDown 里清干净所有残留。治好了这个毛病，测试的可信度上了一个台阶。

5.2 坑二：时间函数、随机数没有注入

业务代码里直接写time()和rand()是 TDD 的隐形杀手。比如"订单超过 30 分钟未支付自动取消"这种逻辑，测试的时候你怎么构造"超过 30 分钟"的场景？总不能真sleep(1800)吧。

正确的解法是把时间变成一个依赖注入进去。最朴素的做法：

public function __construct( private readonly ?\DateTimeImmutable $now = null ) { $this->now = $now ?? new \DateTimeImmutable(); }

测试里就能写：

$now = new \DateTimeImmutable('2025-01-01 10:00:00'); $order = new Order(..., now: $now); $order->markPaidAt(new \DateTimeImmutable('2025-01-01 09:00:00'));

用固定的时间对象来构造"已过期"和"未过期"两种边界。随机数同理——如果逻辑依赖随机数，就把随机数生成器抽成一个接口，测试里注入固定序列。一句话总结：所有不确定的东西，都要变成你可以控制的参数。

5.3 坑三：静态方法和全局状态让 Mock 失效

PHP 的静态方法很难 Mock，这是 TDD 在 PHP 里最头疼的问题之一。假设你的代码里到处都是Logger::info('...')这样的静态调用，测试的时候想验证"有没有记录日志"，就非常被动。

我的处理思路是分阶段治理。短期应急：用 PHPUnit 的MockBuilder对静态方法做有限度的 stub，但这玩意维护成本高，能不用就不用。长期方案：逐步把静态调用改成实例注入，或者用一个可替换的单例容器。这个过程不用一步到位，但每次改到相关代码时顺手推进一点，代码的可测试性就会慢慢变好。

另外提一句$GLOBALS、$_SESSION这类超级全局变量。只要你的业务代码里直接读写它们，测试就必然受环境污染。我的铁律是：所有外部状态，都给我通过参数或构造器进来。

5.4 坑四：浮点数直接 assertEquals

PHP 的浮点数有精度问题，0.1 + 0.2在 PHP 里打印出来是0.30000000000000004这种鬼样子。如果你在订单金额的测试里写assertEquals(0.3, $total)，大概率会因精度误差而挂。

处理浮点数断言有两个办法。一个是把金额换成整数分：接口处接收 10.00 元，内部存 1000 分，计算全程用整数。这也是很多支付系统的标准做法。另一个是在 PHPUnit 里用带精度的断言：

$this->assertEqualsWithDelta(0.3, $subtotal * 0.9 / 100, 0.00001);

我个人强烈推荐第一种——整数分方案。它不光让测试好写，也让线上计算更稳，你不会想在生产环境里排查"为什么金额差了一分钱"这种问题。

5.5 坑五：只测"happy path"，漏掉异常分支

新人写测试容易有一个倾向：测的都是"正常情况"。传一个正常用户、正常金额、正常调用链，一路绿灯。但线上炸掉的地方，几乎都在边界和异常上。

我后来养成了一个习惯：每写一个功能测试，至少再补两个异常场景。比如刚才的订单折扣：

public function testZeroAmountOrderIsAllowed(): void { // 边界：0 元订单 } public function testNegativeAmountOrderThrowsException(): void { $this->expectException(\InvalidArgumentException::class); // 负数金额应该被拒绝 }

给功能加测试的时候，问自己三个问题：输入异常怎么办？依赖返回异常怎么办？临界值两边的行为分别是什么？把这三个问题答完，测试才算是真正够用了。

6. 把 TDD 固化到日常：持续集成与覆盖率门槛

6.1 本地一遍完整的工作流

很多人在 IDE 里写代码、开个浏览器手点两下就算"验证过了"。但 TDD 的日常工作流应该是这样：

1. 从需求里挑一个最小的行为点，写一个失败的测试；
2. 本地跑vendor/bin/phpunit --filter 测试名，确认红；
3. 写最简实现，再跑，确认绿；
4. 重构，再跑全量，确认没有回归；
5. 重复 1 到 4，直到这个功能的所有行为点都被覆盖；
6. 全量测试 + 静态分析，比如phpstan analyse src tests，都通过再提交。

第 6 步里我加了 PHPStan，它和 TDD 是互补关系：测试管行为，静态分析管类型隐患。两个都跑绿了，才算这次改动真的稳。

6.2 GitHub Actions 自动跑测试

本地全绿只是第一步，团队协作里更关键的是 CI。没有 CI 的 TDD，相当于"没人监督的作业"，迟早有人偷懒跳过测试。我用 GitHub Actions 做演示，配置非常简洁：

name: php-tests on: push: branches: [ main ] pull_request: jobs: test: runs-on: ubuntu-latest strategy: matrix: php: [ '8.2', '8.3' ] steps: - uses: actions/checkout@v4 - uses: shivammathur/setup-php@v2 with: php-version: ${{ matrix.php }} coverage: xdebug - run: composer install --no-interaction --prefer-dist - run: vendor/bin/phpunit --coverage-clover build/logs/clover.xml - run: vendor/bin/phpstan analyse src tests --no-progress

配置里用矩阵跑了两个 PHP 版本，这样能提前发现"在我机器上好好的，在别的 PHP 版本上挂了"这类兼容性问题。每次 PR 一提交，CI 自动跑测试和静态分析，任何没写测试或者测试红了的改动，都会被挡在合并之前。

6.3 覆盖率不是 KPI：我如何设定质量门槛

覆盖率到底定多少才合理？见过不少团队硬性要求 100%，结果测试全在测 getter/setter 和空对象，毫无营养；也见过完全不管覆盖率，测试写了等于没写。我的做法是分层设门槛：

执行上，CI 里加一个最低门槛命令：

vendor/bin/phpunit --coverage-clover build/logs/clover.xml --coverage-min 80

覆盖率一旦低于 80%，CI 直接红。这个 80% 是全项目平均值，SQLite 内存库跑出来的数字会虚高一点，所以我还定期在真实数据库环境上跑一次差异对比，防止"测试里能过、生产上换种数据就挂"的情况。

6.4 让 TDD 在团队里活下来

工具和流程都配好了，最后一个问题往往是人的问题。我给想在团队里推 TDD 的朋友一个很实用的建议：别一上来就要求"所有功能必须 TDD"。先选一个不那么紧急、边界清晰的模块（比如优惠券计算、积分换算），用这套流程跑通，让团队看到收益，再逐步扩大范围。强行一刀切推行，只会让测试变成应付了事的仪式。

我自己带团队的时候，PR 里有一条硬性检查：功能代码和测试代码要一起出现。只要看到只有功能没有测试的 PR，直接打回。一开始大家叫苦连天，但三个月之后，线上 bug 数量肉眼可见地往下掉，最直接的变化是：再也没人半夜爬起来抢修订单计算的问题了。这大概就是 TDD 在 PHP 项目里最实在的回报——它不是让你多写代码，而是让你少在深夜挨骂。