PHPUnit测试框架升级了什么

本文目录导读：

1. PHPUnit 8.x → 9.x (重大架构升级)
2. PHPUnit 9.x/10.x → 11.x (最新架构，2024-2025版本)
3. 升级注意事项（通用清单）
4. 升级工具推荐

PHPUnit 的版本迭代较快，不同大版本（如 8.x → 9.x → 10.x → 11.x）之间的升级通常包含重大变更、新特性和弃用功能。

由于你未指定具体从哪个版本升级到哪个版本,我将以最受关注的两个升级节点（8.x → 9.x 和 9.x/10.x → 11.x）作为核心，并简要说明 10.x 和 11.x 的新特性。

如果你需要更具体的版本比较（7.x → 9.x），请补充说明。

---

PHPUnit 8.x → 9.x (重大架构升级)

这是 PHPUnit 历史上一次“清理门户”的重大升级，引入了类型化和注解革命。

核心变化：基于注解的配置

• 弃用：@expectedException、@expectedExceptionMessage、@expectedExceptionCode。
• 替代：强制使用 $this->expectException()、$this->expectExceptionMessage() 等方法。
• 影响：所有基于注解的异常断言都失效了，必须改为方法调用。

类型系统彻底变革

• 强制类型：测试类必须实现 TestCase，且所有测试方法必须返回 void（即 public function testSomething(): void）。
• 严格类型声明：PHPUnit\Framework\TestCase 构造函数签名变为 ( ?string $name = null, array $data = [], $dataName = '' ) 并强制类型。
• Mock 对象：对 Mock 对象的类型感知更强，减少了运行时错误。

新特性

• @covers 注解改进：支持更细粒度的覆盖范围（如 @covers \MyClass::method）。
• setUpBeforeClass() 和 tearDownAfterClass() 支持返回值：可以返回 void 或 null。
• 更好的 PHP 8.0 支持：完全兼容 union types、named arguments（但有限制）。

移除项

• 移除：对 @runInSeparateProcess 的某些旧行为支持。
• 移除：assertPreConditions()、assertPostConditions() 的默认行为（需显式返回 void）。

---

PHPUnit 9.x/10.x → 11.x (最新架构，2024-2025版本)

PHPUnit 11 是一个更现代、更严格的版本，彻底告别了旧 PHPDoc 注解，并向静态分析友好迈进。

终结“纯 PHPDoc 注解”时代 (Attribute 时代)

• 强制使用 PHP 8 Attributes：@test、@dataProvider、@depends、@group 等老注解完全移除。
• 新写法：
  • #[Test] / #[DataProvider(‘method’)] / #[Depends(‘testA’)] / #[Group(‘fast’)]
• 影响：不升级 Attributes，测试将直接报错中断。

更严格的类型系统

• 禁止非 void 返回值：测试方法必须返回 void（之前版本警告，现在报错）。
• setUp() 和 tearDown()：签名必须为 protected function setUp(): void，不能传入参数，且必须调用 parent::setUp()（否则报错）。
• 数据提供器 (Data Provider)：必须返回 iterable 类型，不能返回 array（未指明索引的数组会警告）。

Mock 系统的突破

• createMock() 默认行为改变：不再自动调用 __construct()（除非显式调用 willReturn() 或 with()），这更容易创建隔离测试。
• 禁用 returnValueMap()：多数场景下被 willReturnCallback() 替代。
• expects() 方法的 once()：现在严格区分 ->once()->method(…) 和 ->method(…)->once() 的书写顺序。

测试执行引擎优化

• 并行测试 (Parallel Testing) 正式稳定：无需 --processes 扩展，内置 --parallel 参数（需安装 phpunit/phpunit ≥ 11.0）。
• 覆盖率报告改进：支持 HTML + 行覆盖率 + 分支覆盖率混合显示。
• 精确的错误显示：断言失败时，直接显示变量类型和值，不再截断长字符串。

弃用项 (将在 12.x 移除)

• assertInternalType() 系列（已弃用多年，现在完全移除）。
• @requires 注解（需改为 #[RequiresPhp(‘8.1’)]）。
• expectExceptionCode() 和 expectExceptionMessageRegExp() 的某些旧行为。

---

升级注意事项（通用清单）

无论你从哪个版本升级,以下都是需要检查的关键点：

检查项目	旧写法 (需修改)	新写法 (推荐/必须)
测试方法	public function testSomething()	public function testSomething(): void
异常断言	@expectedException \InvalidArgumentException	$this->expectException(\InvalidArgumentException::class);
数据提供器	@dataProvider dataForTest	#[DataProvider(‘dataForTest’)] (或 #[DataProvider(DataProvider::class, ‘method’)])
依赖测试	@depends testA	#[Depends(‘testA’)]
分组(groups)	@group slow	#[Group(‘slow’)]
setUp/tearDown	protected function setUp()	protected function setUp(): void + 必须调用 parent::setUp()
Mock创建	$this->getMockBuilder(...)->getMock()	多用 $this->createMock()，减少 getMockBuilder
返回值	不返回 (void)	必须显式 void
PHP版本要求	PHP 7.4 / 8.0	PHP 11.x 要求 PHP 8.1+ (推荐 PHP 8.2+)

升级工具推荐

1. Rector：自动扫描并修复注解 -> Attributes 的转换（rector.php 配置中开启 SetList::PHPUNIT_90、SetList::PHPUNIT_100 等）。
2. PHP-CS-Fixer：配合 @PHPUnit100Migration:risky 规则集。
3. 手动检查清单：运行 phpunit --migrate-configuration（生成新版 phpunit.xml.dist）和 phpunit --list-suites。

---

• 从 8.x 到 9.x：必须将注解异常改为方法调用，并统一返回 void，这是最痛苦的迁移点。
• 从 9.x/10.x 到 11.x：必须将 @test / @dataProvider 等所有注解改为 PHP 8 Attributes，并适配更严格的类型签名。
• 最推荐路径：如果项目刚启动，直接使用 PHPUnit 11.x；如果老旧项目，建议先升到 9.6（稳定版），再用 Rector 一步到位升到 11.x。

如果你有具体的 phpunit.xml 配置或测试代码片段，可以提供给我，我可以帮你分析具体的冲突点。