woocommerce/packages/php/email-editor/zh-cn/writing-tests.md

为 WooCommerce 电子邮件编辑 PHP 库撰写测试

目录

1. 前置条件
2. 测试结构
3. 单元测试
4. 集成测试
5. 最佳实践
6. 调试测试

前置条件

1. 环境设置:

   # 安装 wp-env
   npm install
   
   # 开始测试环境
   composer run env:start
   

2. 必填依赖项:

   • Node
   • PNPM
   • Docker (为 wp-env)
   • Composer

测试结构

1. 目录结构

tests/
├── unit/
│   ├── Engine/
│   ├── Integrations/
│   ├── bootstrap.php
│   └── stubs.php
└── integration/

2. 测试组织

• 单元测试在 tests/unit/ 目录中
• 集成测试在 tests/integration/ 目录中
• 使用描述性的文件名，并以 _Test.php 为后缀
• 使用 @group 注解对相关测试进行分组

单元测试

1. 运行单元测试

# 运行所有单元测试
composer run test:unit

# 运行特定测试文件
pnpm --filter='@woocommerce/email-editor-config' test:unit -- tests/unit/Engine/Settings_Controller_Test.php

# 运行特定组的测试
composer run test:unit -- --group=settings

2. 基础单元测试模板

<?php
declare(strict_types = 1);
namespace Automattic\WooCommerce\EmailEditor\Engine;

class Settings_Controller_Test extends \Email_Editor_Unit_Test  {
    /**
     * @var Settings_Controller
     */
    private $controller;

    public function setUp(): void {
        parent::setUp();
        $this->controller = new Settings_Controller();
    }

    public function tearDown(): void {
        parent::tearDown();
    }

    /**
     * @test
     * @group settings
     */
    public function test_can_register_settings() {
        // 准备
        $expected_settings = [
            'email_subject' => 'Test Subject',
            'email_preheader' => 'Test Preheader'
        ];

        // 执行
        $this->controller->register_settings($expected_settings);

        // 断言
        $this->assertEquals(
            $expected_settings,
            $this->controller->get_settings()
        );
    }
}

3. 何时编写单元测试

• 测试单个类和单个方法
• 隔离测试业务逻辑
• 测试边界情况和错误条件
• 测试数据转换
• 测试工具函数

集成测试

1. 运行集成测试

# 运行所有集成测试
composer run test:integration

# 运行特定的集成测试
pnpm --filter='@woocommerce/email-editor-config' test:integration -- tests/integration/Integrations/Core/Renderer/Blocks/Social_Links_Test.php

# 运行特定组的测试
composer run test:integration -- --group=email-templates

2. 基础集成测试模板

<?php
declare(strict_types = 1);
namespace Automattic\WooCommerce\EmailEditor\Integrations\Core\Renderer;

class Renderer_Test extends \Email_Editor_Integration_Test_Case {
    /**
     * @var Renderer
     */
    private $renderer;

    public function setUp(): void {
        parent::setUp();
        $this->renderer = $this->renderer = $this->di_container->get( Renderer::class );
    }

    /**
     * @test
     * @group email-templates
     */
    public function test_can_render_email_template() {
        // 在此处进行测试
    }

    private function create_mock_order() {
        // 为测试创建一个模拟订单
        return wc_create_order();
    }
}

3. 何时编写集成测试

• 测试多个类之间的交互
• 测试 WordPress 钩子和筛选
• 测试数据库操作
• 测试电子邮件模板渲染
• 测试 API 端点
• 测试复杂工作流

最佳实践

1. 测试隔离：

   • 每个测试应该独立
   • 使用 setUp() 和 tearDown() 进行测试夹具设置
   • 测试后清理
   • 尽可能使用数据库事务

2. 命名约定：

   • 测试方法应具有描述性
   • 使用 test_ 前缀或 @test 注解
   • 使用 @group 注解对相关测试进行分组
   • 遵循 PSR-4 自动加载标准

3. 断言：

   • 使用特定的断言
   • 每个测试方法只测试一件事
   • 包含正向和反向测试用例
   • 测试边界情况和错误条件

4. 模拟：

   • 使用 WordPress 测试工具
   • 模拟外部依赖
   • 在适当的时候使用测试替身
   • 保持模拟简单且聚焦

调试测试

1. 在调试模式下运行测试：

   composer run test:unit -- --debug
   

2. 使用 Xdebug：

   • 在 php.ini 中配置 Xdebug
   • 在您的 IDE 中设置断点
   • 运行测试并生成覆盖率报告

3. 查看测试覆盖率：

   composer run test:unit -- --coverage-html coverage/
   

4. 使用 wp-env 进行测试：

   # 启动测试环境
   composer run env:start
   
   # 停止测试环境
   composer run env:stop
   
   # 重置测试环境
   composer run env:clean
   

撰写 E2E 测试的指南可在 packages/js/email-editor/writing-e2e-tests.md 找到