ShopEx开放平台

# PHPUnit 测试用例编写规范

# 概述

本文档定义了在 OMS 系统中编写 PHPUnit 测试用例的标准规范和最佳实践，确保测试代码的一致性和可维护性。

# 核心原则

# 1. "先查后做"原则

  • 写测试前必须先查看项目中已有的测试文件
  • 找到相似功能的测试作为模板
  • 理解项目的测试结构和规范

# 2. "规范优先"原则

  • 严格按照项目测试规范编写
  • 遵循项目的命名和结构约定
  • 使用正确的依赖引入方式

# 测试文件结构

# 1. 基本结构

<?php
declare(strict_types=1);

use PHPUnit\Framework\TestCase;

class YourTestNameTest extends TestCase
{
    private $yourObject;

    protected function setUp(): void
    {
        parent::setUp();

        // 引入核心框架文件（必须）
        include_once 'config/config.php';
        include_once 'app/base/defined.php';
        include_once 'app/base/kernel.php';
        
        // 初始化测试对象
        $this->yourObject = new YourClass();
    }

    protected function tearDown(): void
    {
        $this->yourObject = null;
    }

    public function testYourMethod(): void
    {
        // 测试逻辑
        $this->assertTrue(true, '测试描述');
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

# 2. 关键要点

  • 类名必须以 Test 结尾
  • 测试方法必须以 test 开头
  • 必须调用 parent::setUp()
  • 必须引入三个核心框架文件

# 依赖引入规范

# 1. 核心框架文件（必须）

include_once 'config/config.php';      // 系统配置
include_once 'app/base/defined.php';   // 常量定义
include_once 'app/base/kernel.php';    // 核心框架
1
2
3

# 2. 业务类文件（不需要手动引入）

  • 框架会自动加载业务类
  • 不需要 include_once 具体的业务类文件
  • 直接使用 new ClassName() 即可

# 3. 错误示例

// ❌ 错误：手动引入业务类
include_once 'app/omeauto/lib/auto/type/abstract.php';
include_once 'app/omeauto/lib/auto/type/interface.php';
include_once 'app/omeauto/lib/auto/type/orderlabel.php';

// ✅ 正确：只引入核心框架
include_once 'config/config.php';
include_once 'app/base/defined.php';
include_once 'app/base/kernel.php';
1
2
3
4
5
6
7
8
9

# 测试前检查清单

# 每次写测试前必须检查：

❓ 我是否查看了项目中已有的测试文件？
❓ 我是否理解了项目的测试规范？
❓ 我是否遵循了项目的命名和结构约定？
❓ 我是否使用了正确的依赖引入方式？
❓ 我是否调用了 parent::setUp()？
❓ 我是否只引入了三个核心框架文件？
1
2
3
4
5
6

# 如果任何一个答案是"否"，必须立即停止并重新学习！

# 查找测试模板的步骤

# 1. 搜索现有测试

# 在项目根目录搜索测试文件
find tests/ -name "*Test.php" | grep -i yourfeature
1
2

# 2. 分析相似测试

  • 查看测试文件结构
  • 理解依赖引入方式
  • 学习测试方法命名

# 3. 参考最佳实践

  • 复制成功的测试结构
  • 保持一致的代码风格
  • 遵循项目约定

# 常见错误及避免方法

# 1. 错误：手动引入业务类

// ❌ 错误做法
include_once 'app/omeauto/lib/auto/type/orderlabel.php';

// ✅ 正确做法
// 不需要手动引入，框架自动加载
1
2
3
4
5

# 2. 错误：忘记调用 parent::setUp()

// ❌ 错误做法
protected function setUp(): void
{
    // 忘记调用父类方法
    include_once 'config/config.php';
}

// ✅ 正确做法
protected function setUp(): void
{
    parent::setUp();  // 必须调用
    include_once 'config/config.php';
}
1
2
3
4
5
6
7
8
9
10
11
12
13

# 3. 错误：使用绝对路径

// ❌ 错误做法
require_once dirname(__FILE__) . '/../../app/omeauto/lib/auto/type/orderlabel.php';

// ✅ 正确做法
// 只引入核心框架，业务类自动加载
1
2
3
4
5

# 测试方法命名规范

# 1. 基本命名

public function testMethodName(): void
public function testFeatureDescription(): void
public function testEdgeCase(): void
1
2
3

# 2. 具体示例

public function testFlashOrderGrouping(): void
public function testParameterValidation(): void
public function testComparisonTypes(): void
public function testRoleToString(): void
1
2
3
4

# 断言使用规范

# 1. 基本断言

$this->assertTrue($result, '描述信息');
$this->assertFalse($result, '描述信息');
$this->assertEquals($expected, $actual, '描述信息');
$this->assertFileExists($filePath, '描述信息');
1
2
3
4

# 2. 数组断言

$this->assertArrayHasKey('key', $array, '描述信息');
$this->assertCount($expectedCount, $array, '描述信息');
$this->assertIsArray($value, '描述信息');
1
2
3

# 3. 对象断言

$this->assertInstanceOf(ExpectedClass::class, $object, '描述信息');
$this->assertObjectHasAttribute('attribute', $object, '描述信息');
1
2

# 测试数据准备

# 1. Mock 对象创建

private function createMockObject($data)
{
    return new class($data) {
        private $data;
        
        public function __construct($data)
        {
            $this->data = $data;
        }
        
        public function getData()
        {
            return $this->data;
        }
    };
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 2. 测试数据组织

public function testYourMethod(): void
{
    // 准备测试数据
    $testData = [
        'key1' => 'value1',
        'key2' => 'value2'
    ];
    
    // 执行测试
    $result = $this->yourObject->yourMethod($testData);
    
    // 验证结果
    $this->assertTrue($result, '方法应该返回 true');
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 运行测试

# 1. 运行单个测试

./vendor/bin/phpunit tests/yourpath/YourTestNameTest.php
1

# 2. 运行所有测试

./vendor/bin/phpunit
1

# 3. 运行特定测试方法

./vendor/bin/phpunit --filter testMethodName tests/yourpath/YourTestNameTest.php
1

# 质量检查

# 1. 测试覆盖率

  • 确保测试覆盖所有主要功能
  • 包含正常流程和异常流程
  • 测试边界条件和错误情况

# 2. 测试独立性

  • 每个测试方法应该独立运行
  • 测试之间不应该有依赖关系
  • 使用 setUp() 和 tearDown() 确保测试环境干净

# 3. 测试可读性

  • 测试方法名清晰表达测试目的
  • 测试逻辑简单明了
  • 断言信息详细明确

# 学习资源

# 1. 项目中的测试示例

  • tests/material/fukubukuroTest.php - 基础测试结构
  • tests/omeauto/OrderLabelGroupingTest.php - 完整测试示例

# 2. PHPUnit 官方文档

# 总结

遵循这些规范可以：

  1. 避免重复犯错 - 建立标准流程
  2. 提高开发效率 - 减少调试时间
  3. 保证代码质量 - 统一的测试标准
  4. 便于维护 - 一致的代码风格

记住：每次写测试前，先查看项目模板，再动手编写！

最后更新: 11/11/2025, 9:12:34 PM

← 订单预处理机制 →