API Platform 4.1 升级后测试失败的解决方案分析

在 API Platform 4.1 版本升级后，许多开发者遇到了测试套件失败的问题。本文将深入分析问题的根源，并提供完整的解决方案。

问题背景

API Platform 4.1 引入了一个重要的内部优化，改变了测试客户端的行为模式。这个变化主要影响了以下两种测试场景：

1. 使用 RefreshDatabaseTrait 自动加载测试夹具的测试用例
2. 在单个测试方法中执行多个请求的测试场景

核心问题分析

问题的根源在于 API Platform 4.1 对客户端创建机制的优化。在 4.1 版本之前，每次调用 createClient() 方法都会触发内核重启，这会导致：

• 数据库被完全重建
• 测试夹具重新加载
• 所有服务容器被重新初始化

4.1 版本通过 PR #6976 优化了这一行为，现在客户端创建不会自动重启内核，这带来了性能提升，但也破坏了部分现有测试的预期行为。

具体表现

开发者报告了两种主要的问题表现：

1. 夹具加载失败：测试类继承自自定义的 AbstractApiTestCase，其中包含 setUp() 方法调用 self::bootKernel()，导致夹具无法正确加载。

2. 多请求测试失败：在单个测试方法中执行多个请求时，第二个请求会意外失败（例如出现 JWT Token 未找到的错误）。

解决方案

针对夹具加载问题

修改测试基类的 setUp() 方法，使用静态调用：

public function setUp(): void
{
    static::bootKernel();  // 注意使用 static 而非 self
}

针对多请求测试问题

有两种可行的解决方案：

1. 重用客户端实例：避免在测试中重复创建客户端，而是重用同一个实例。

public function testExample(): void
{
    $client = self::createClient();
    $user = /* 获取用户 */;
    $client->loginUser($user);
    
    // 第一个请求
    $client->request(/* ... */);
    
    // 第二个请求 - 使用同一个客户端
    $client->request(/* ... */);
}

2. 强制内核重启：在需要时手动重启内核。

public function testExample(): void
{
    $client = self::createClient();
    // 第一个请求...
    
    // 强制重启内核
    static::$booted = false;
    $client = self::createClient();
    // 第二个请求...
}

最佳实践建议

1. 避免不必要的内核重启：只在必要时才创建新的客户端实例。

2. 使用 disableReboot：对于需要保持状态的测试，可以使用 Symfony 的 disableReboot 功能。

3. 准备迁移到 5.0：虽然 4.1 会保留向后兼容性，但建议逐步调整测试代码以适应未来的行为变更。

技术原理

API Platform 的测试客户端底层依赖于 Symfony 的测试框架。内核启动和客户端创建的关系是：

• 内核启动会重置整个应用程序状态
• 客户端创建默认会共享已启动的内核
• 认证状态等是存储在客户端实例中的

4.1 版本的优化正是通过减少不必要的内核重启来提高测试性能，但这改变了之前的行为预期。

结论

API Platform 4.1 的这项优化总体上是有益的，虽然短期内需要开发者调整测试代码，但长期来看能提供更高效的测试执行。建议开发者：

1. 审查现有测试中对客户端创建和内核启动的依赖
2. 采用更高效的测试模式
3. 关注未来版本中相关配置参数的变更

通过以上调整，可以确保测试在 API Platform 4.1 及未来版本中稳定运行。