PHP 8 Named Arguments在测试代码中的应用：提高测试用例的可读性

PHP 8 Named Arguments 在测试代码中的应用：提高测试用例的可读性

大家好！今天我们来聊聊 PHP 8 中一个非常实用的特性：Named Arguments（命名参数），以及它如何显著提升测试代码的可读性和可维护性。在软件开发中，测试的重要性不言而喻。良好的测试用例不仅能保障代码质量，还能在需求变更时提供快速反馈，降低重构风险。而可读性强的测试代码，能让团队成员更容易理解测试意图，快速定位问题，提高协作效率。

什么是 Named Arguments？

在 PHP 8 之前，调用函数时，我们需要按照函数定义中参数的顺序依次传递参数。如果函数有很多可选参数，或者参数的默认值不符合我们的需求，我们就需要传入大量的 null 或默认值来占位，这使得代码可读性变得很差。

Named Arguments 允许我们在调用函数时，通过指定参数名称来传递参数，而不再需要按照参数顺序。 这极大地提高了代码的可读性和灵活性。

例如，考虑以下函数：

function createUser(string $username, string $email, string $password, ?string $firstName = null, ?string $lastName = null, bool $isActive = true): User
{
    // 创建用户的逻辑
    return new User($username, $email, $password, $firstName, $lastName, $isActive);
}

在 PHP 7.x 中，如果要创建一个激活的用户，但只想设置 lastName，则需要这样调用：

$user = createUser('testuser', '[email protected]', 'password', null, 'Doe', true);

这很糟糕！很难一眼看出每个 null 和 true 代表什么。

而在 PHP 8 中，我们可以使用 Named Arguments：

$user = createUser(
    username: 'testuser',
    email: '[email protected]',
    password: 'password',
    lastName: 'Doe',
    isActive: true
);

现在，代码的意图就非常明确了。

Named Arguments 在测试代码中的优势

Named Arguments 在测试代码中带来的优势主要体现在以下几个方面：

• 提高可读性： 通过明确指定参数名称，测试意图更加清晰，更容易理解测试用例的目的。
• 减少维护成本： 当函数签名发生变化时，使用 Named Arguments 的测试用例受到的影响更小，更容易维护。
• 提高灵活性： 可以只传递需要测试的参数，而无需关心其他可选参数的默认值。
• 减少错误： 避免因参数顺序错误而导致的 bug。

下面我们通过几个具体的例子来展示 Named Arguments 在测试代码中的应用。

示例 1: 测试数据生成器

很多测试都需要用到测试数据。我们可以创建一个测试数据生成器函数，利用 Named Arguments 来灵活地配置数据。

function createTestData(
    string $name = 'Test Name',
    int $age = 30,
    string $email = '[email protected]',
    bool $isActive = true,
    ?string $address = null
): array {
    return [
        'name' => $name,
        'age' => $age,
        'email' => $email,
        'isActive' => $isActive,
        'address' => $address,
    ];
}

在 PHP 7.x 中，要创建一个 age 为 25 的测试数据，我们需要这样：

$data = createTestData('Test Name', 25, '[email protected]', true, null);

而在 PHP 8 中，我们可以这样：

$data = createTestData(age: 25);

或者，如果我们需要同时修改 age 和 isActive：

$data = createTestData(age: 25, isActive: false);

使用 Named Arguments，我们可以清晰地知道哪些数据被修改了，而其他参数则使用了默认值。这在测试用例中非常有用，因为我们可以专注于测试特定的场景，而无需关心其他无关的参数。

下面是一个使用 PHPUnit 的示例：

use PHPUnitFrameworkTestCase;

class DataTest extends TestCase
{
    public function testAgeIsCorrect(): void
    {
        $data = createTestData(age: 25);
        $this->assertEquals(25, $data['age']);
    }

    public function testIsActiveIsFalse(): void
    {
        $data = createTestData(isActive: false);
        $this->assertFalse($data['isActive']);
    }

    public function testAgeAndIsActiveAreCorrect(): void
    {
        $data = createTestData(age: 25, isActive: false);
        $this->assertEquals(25, $data['age']);
        $this->assertFalse($data['isActive']);
    }
}

示例 2: Mock 对象配置

在使用 Mock 对象进行单元测试时，我们经常需要配置 Mock 对象的行为。Named Arguments 可以使 Mock 对象的配置更加清晰。

假设我们有一个 UserRepository 类，它有一个 findUserById 方法：

class UserRepository
{
    public function findUserById(int $id): ?User
    {
        // 从数据库中查找用户的逻辑
        return null; // 假设找不到用户
    }
}

我们想要测试一个 UserService 类，它使用 UserRepository 来查找用户：

class UserService
{
    private UserRepository $userRepository;

    public function __construct(UserRepository $userRepository)
    {
        $this->userRepository = $userRepository;
    }

    public function getUserById(int $id): ?User
    {
        return $this->userRepository->findUserById($id);
    }
}

我们可以使用 PHPUnit 的 Mock 对象来模拟 UserRepository 的行为：

use PHPUnitFrameworkTestCase;

class UserServiceTest extends TestCase
{
    public function testGetUserByIdReturnsUser(): void
    {
        $user = new User('testuser', '[email protected]', 'password');

        $userRepositoryMock = $this->createMock(UserRepository::class);
        $userRepositoryMock->expects($this->once())
                           ->method('findUserById')
                           ->with(123)
                           ->willReturn($user);

        $userService = new UserService($userRepositoryMock);

        $result = $userService->getUserById(123);

        $this->assertSame($user, $result);
    }

    public function testGetUserByIdReturnsNull(): void
    {
        $userRepositoryMock = $this->createMock(UserRepository::class);
        $userRepositoryMock->expects($this->once())
                           ->method('findUserById')
                           ->with(123)
                           ->willReturn(null);

        $userService = new UserService($userRepositoryMock);

        $result = $userService->getUserById(123);

        $this->assertNull($result);
    }
}

虽然上面的代码能够正常工作，但是当 Mock 对象的方法有多个参数时，配置起来会变得非常复杂。我们可以使用一个自定义的 Mock 对象配置函数，利用 Named Arguments 来简化配置：

function configureUserRepositoryMock(
    $userRepositoryMock,
    int $id = 123,
    ?User $returnValue = null
): void {
    $userRepositoryMock->expects(once())
                       ->method('findUserById')
                       ->with($id)
                       ->willReturn($returnValue);
}

现在，测试用例可以这样写：

use PHPUnitFrameworkTestCase;

class UserServiceTest extends TestCase
{
    public function testGetUserByIdReturnsUser(): void
    {
        $user = new User('testuser', '[email protected]', 'password');

        $userRepositoryMock = $this->createMock(UserRepository::class);
        configureUserRepositoryMock($userRepositoryMock, returnValue: $user);

        $userService = new UserService($userRepositoryMock);

        $result = $userService->getUserById(123);

        $this->assertSame($user, $result);
    }

    public function testGetUserByIdReturnsNull(): void
    {
        $userRepositoryMock = $this->createMock(UserRepository::class);
        configureUserRepositoryMock($userRepositoryMock, returnValue: null);

        $userService = new UserService($userRepositoryMock);

        $result = $userService->getUserById(123);

        $this->assertNull($result);
    }
}

在这个例子中，我们只关心 returnValue 参数，而 id 参数使用了默认值。使用 Named Arguments，我们可以更清晰地表达测试意图。

示例 3: 复杂的配置对象

在一些复杂的系统中，我们可能需要使用配置对象来传递大量的配置参数。Named Arguments 可以使配置对象的创建更加清晰。

假设我们有一个 PaymentProcessor 类，它需要一个 PaymentConfiguration 对象：

class PaymentConfiguration
{
    private string $apiKey;
    private string $apiSecret;
    private string $apiUrl;
    private int $timeout;
    private bool $debugMode;

    public function __construct(
        string $apiKey,
        string $apiSecret,
        string $apiUrl,
        int $timeout = 30,
        bool $debugMode = false
    ) {
        $this->apiKey = $apiKey;
        $this->apiSecret = $apiSecret;
        $this->apiUrl = $apiUrl;
        $this->timeout = $timeout;
        $this->debugMode = $debugMode;
    }

    // Getters
}

在测试中，我们可能只需要修改 debugMode 参数：

use PHPUnitFrameworkTestCase;

class PaymentProcessorTest extends TestCase
{
    public function testProcessPaymentInDebugMode(): void
    {
        $configuration = new PaymentConfiguration(
            apiKey: 'test_api_key',
            apiSecret: 'test_api_secret',
            apiUrl: 'https://example.com/api',
            debugMode: true
        );

        $paymentProcessor = new PaymentProcessor($configuration);

        // 断言 paymentProcessor 在 debug mode 下的行为
    }
}

使用 Named Arguments，我们可以清晰地知道 debugMode 参数被设置为 true，而其他参数则使用了默认值。

示例 4: 测试框架的扩展

一些测试框架提供了扩展点，允许我们自定义测试行为。Named Arguments 可以使这些扩展点的使用更加灵活。

例如，假设我们有一个自定义的 PHPUnit 约束，用于检查字符串是否包含特定的子字符串：

use PHPUnitFrameworkConstraintConstraint;

class StringContainsSubstring extends Constraint
{
    private string $substring;
    private bool $caseSensitive;

    public function __construct(string $substring, bool $caseSensitive = true)
    {
        $this->substring = $substring;
        $this->caseSensitive = $caseSensitive;
    }

    protected function matches($other): bool
    {
        if ($this->caseSensitive) {
            return strpos($other, $this->substring) !== false;
        } else {
            return stripos($other, $this->substring) !== false;
        }
    }

    public function toString(): string
    {
        return sprintf('contains substring "%s"', $this->substring);
    }
}

在测试用例中，我们可以使用这个约束来检查字符串是否包含特定的子字符串：

use PHPUnitFrameworkTestCase;

class StringTest extends TestCase
{
    public function testStringContainsSubstring(): void
    {
        $string = 'This is a test string.';

        $this->assertThat($string, new StringContainsSubstring('test'));
    }

    public function testStringContainsSubstringCaseInsensitive(): void
    {
        $string = 'This is a test string.';

        $this->assertThat($string, new StringContainsSubstring(substring: 'TEST', caseSensitive: false));
    }
}

使用 Named Arguments，我们可以清晰地指定 caseSensitive 参数的值，而无需关心其他参数的顺序。

总结一下Named Arguments带来的好处

特性	PHP 7.x	PHP 8 (Named Arguments)	优势
可读性	难以理解参数含义，需要查阅文档才能理解	通过参数名称，清晰表达参数含义	大幅提升代码可读性，更容易理解测试意图
灵活性	必须按照参数顺序传递参数，即使只想修改后面的参数	可以只传递需要修改的参数，无需关心参数顺序	提高灵活性，可以专注于测试特定的场景
维护性	函数签名变化可能导致大量测试用例失效	函数签名变化对使用 Named Arguments 的测试用例影响较小	提高维护性，降低重构风险
避免错误	容易因参数顺序错误而导致 bug	避免因参数顺序错误而导致的 bug	减少错误，提高代码质量

如何在现有项目中引入 Named Arguments

在现有项目中引入 Named Arguments，需要注意以下几点：

• PHP 版本要求： Named Arguments 是 PHP 8 的特性，需要升级到 PHP 8 或更高版本才能使用。
• 兼容性： 如果项目中存在需要兼容 PHP 7.x 的代码，需要使用条件判断来区分是否使用 Named Arguments。
• 逐步迁移： 不建议一次性将所有代码都修改为使用 Named Arguments，可以逐步迁移，优先修改可读性较差的代码。
• 代码规范： 制定代码规范，明确何时使用 Named Arguments，以保持代码风格的一致性。

一些使用建议

• 对于参数较多，或者参数默认值不符合需求的函数，优先使用 Named Arguments。
• 在测试代码中，尽量使用 Named Arguments，以提高可读性和可维护性。
• 在公共 API 中，为了向后兼容，可以同时支持 positional arguments 和 named arguments。
• 不要滥用 Named Arguments，对于参数较少的简单函数，可以使用 positional arguments。

小小的总结

PHP 8 的 Named Arguments 是一个强大的特性，它能显著提高测试代码的可读性、灵活性和可维护性。通过在测试代码中合理使用 Named Arguments，我们可以编写出更加清晰、易于理解和维护的测试用例，从而提高代码质量，降低维护成本。在日常开发中，充分利用这一特性，能让我们的代码更上一层楼。