Skip to content

testing.md

Latest commit

 

History

History
343 lines (250 loc) · 7.45 KB

testing.md

File metadata and controls

343 lines (250 loc) · 7.45 KB

Coze SDK 测试指南

概述

本文档介绍了 Coze SDK 的测试策略、运行方法和最佳实践。

测试架构

测试分类

  1. 单元测试 (Unit Tests)

    • 不依赖外部API
    • 测试核心逻辑和数据处理
    • 快速执行，高可靠性

  2. 流式传输测试 (Stream Tests)

    • 测试流式传输功能
    • 验证各种流式处理器
    • 模拟流式数据传输

  3. API测试 (API Tests)

    • 需要有效的API配置
    • 测试与Coze API的集成
    • 验证完整的业务流程

运行测试

使用Composer脚本

# 运行单元测试（推荐）
composer test:unit

# 运行流式传输测试
composer test:stream

# 运行API测试（需要有效配置）
composer test:api

# 运行所有测试
composer test:all

# 生成测试覆盖率报告
composer test:coverage

# 生成测试报告
composer test:report

使用PHPUnit直接运行

# 运行特定测试文件
./vendor/bin/phpunit tests/Chat/StreamUnitTest.php

# 运行特定测试套件
./vendor/bin/phpunit --testsuite "Unit Tests"

# 运行特定测试方法
./vendor/bin/phpunit --filter testConsoleStreamHandler tests/Chat/StreamUnitTest.php

使用测试脚本

# 运行单元测试
php run_tests.php --unit

# 运行流式传输测试
php run_tests.php --stream

# 运行所有测试
php run_tests.php --all

# 显示帮助信息
php run_tests.php --help

测试环境配置

模拟模式（默认）

默认情况下，测试运行在模拟模式下，不需要真实的API配置：

// 在测试中
protected bool $useMockMode = true; // 默认值

真实API模式

如果需要测试真实的API集成，可以启用真实API模式：

// 在测试中
protected function setUp(): void
{
    parent::setUp();
    $this->enableRealApiMode(); // 启用真实API模式
}

环境变量

可以通过环境变量控制测试行为：

# 设置测试模式
export COZE_SDK_TEST_MODE=mock    # 模拟模式
export COZE_SDK_TEST_MODE=real    # 真实API模式

# 设置API配置（真实模式需要）
export COZE_SDK_KID=your_kid_here
export COZE_SDK_ISS=your_iss_here
export COZE_SDK_KEY_PATH=/path/to/private_key.pem
export COZE_SDK_SPACE_ID=your_space_id
export COZE_SDK_BOT_ID=your_bot_id

测试用例说明

单元测试用例

StreamUnitTest.php

测试流式传输的核心组件：

  • testConsoleStreamHandler(): 测试控制台输出处理器
  • testJsonStreamHandler(): 测试JSON数据解析处理器
  • testMemoryStreamHandler(): 测试内存存储处理器
  • testCallbackStreamHandler(): 测试回调处理器
  • testRealTimeTextHandler(): 测试实时文本处理器
  • testProgressMonitorHandler(): 测试进度监控处理器
  • testEnhancedStreamHandler(): 测试增强处理器
  • testStreamProcessor(): 测试流式数据处理器
  • testStreamInterruption(): 测试流式传输中断
  • testErrorHandling(): 测试错误处理
  • testStreamProcessorReset(): 测试处理器重置
  • testMultipleDataFormats(): 测试多种数据格式
  • testPerformanceStatistics(): 测试性能统计

流式传输测试用例

StreamChatTest.php

测试Chat类的流式传输功能：

  • testConsoleStreamHandler(): 测试控制台流式处理器
  • testJsonStreamHandler(): 测试JSON流式处理器
  • testMemoryStreamHandler(): 测试内存流式处理器
  • testCallbackStreamHandler(): 测试回调流式处理器
  • testStreamErrorHandling(): 测试流式传输错误处理
  • testStreamInterruption(): 测试流式传输中断
  • testStreamMetadata(): 测试流式传输元数据
  • testStreamPerformance(): 测试流式传输性能
  • testStreamCompatibility(): 测试流式传输兼容性

AdvancedStreamTest.php

测试高级流式传输功能：

  • testRealTimeTextHandler(): 测试实时文本流式传输
  • testProgressMonitorHandler(): 测试进度监控流式传输
  • testEnhancedStreamHandler(): 测试增强流式处理器
  • testStreamInterruption(): 测试流式传输中断
  • testStreamProcessor(): 测试流式数据处理器
  • testStreamPerformance(): 测试流式传输性能
  • testStreamErrorHandling(): 测试流式传输错误处理
  • testStreamMetadata(): 测试流式传输元数据
  • testStreamStatistics(): 测试流式传输统计信息
  • testStreamCompatibility(): 测试流式传输兼容性

测试数据

模拟数据

测试使用模拟数据，避免依赖外部服务：

// 模拟SSE格式数据
$sseData = "data: {\"choices\":[{\"delta\":{\"content\":\"Hello\"}}]}\n";

// 模拟JSON数据
$jsonData = '{"choices":[{"delta":{"content":"Hello"}}]}';

// 模拟结束标记
$endData = "data: [DONE]\n";

测试配置

// 模拟配置
$config = [
    'kid' => 'test_kid_' . time(),
    'iss' => 'test_iss_' . time(),
    'keyPath' => '/path/to/test/key.pem',
    'spaceId' => 'test_space_id',
    'botId' => 'test_bot_id'
];

测试最佳实践

1. 测试隔离

每个测试应该是独立的，不依赖其他测试的状态：

protected function setUp(): void
{
    parent::setUp();
    // 重置测试状态
    $this->clearLogs();
}

protected function tearDown(): void
{
    // 清理测试资源
    parent::tearDown();
}

2. 模拟外部依赖

使用模拟对象替代外部依赖：

// 使用内存缓存替代文件缓存
$this->cache = new Psr16Cache(new ArrayAdapter());

// 使用模拟日志器
$this->logger = new SimpleLogger(true);

3. 测试覆盖率

确保测试覆盖核心功能：

# 生成覆盖率报告
composer test:coverage

# 查看覆盖率报告
open tests/reports/coverage/index.html

4. 性能测试

监控测试性能，确保测试快速执行：

public function testPerformance(): void
{
    $startTime = microtime(true);
    
    // 执行测试逻辑
    
    $duration = microtime(true) - $startTime;
    $this->assertLessThan(1, $duration); // 应该在1秒内完成
}

故障排除

常见问题

  1. JWT Token错误

    • 检查API配置是否正确
    • 确认私钥文件存在且有效
    • 验证kid和iss参数

  2. 测试超时

    • 增加PHP执行时间限制
    • 检查网络连接
    • 使用模拟模式避免API调用

  3. 内存不足

    • 增加PHP内存限制
    • 优化测试数据大小
    • 及时清理测试资源

调试技巧

  1. 启用详细日志

    $this->logger = new SimpleLogger(true);

  2. 查看测试输出

    ./vendor/bin/phpunit --verbose tests/Chat/StreamUnitTest.php

  3. 检查测试报告

    composer test:report

持续集成

GitHub Actions

name: Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
      - run: composer install
      - run: composer test:unit
      - run: composer test:coverage

本地开发

# 开发时运行测试
composer test:unit

# 提交前运行完整测试
composer test:all

# 生成测试报告
composer test:report

总结

Coze SDK 的测试架构提供了：

  • 分层测试: 单元测试、流式测试、API测试
  • 灵活配置: 支持模拟模式和真实API模式
  • 全面覆盖: 测试核心功能和边界情况
  • 性能监控: 确保测试快速可靠
  • 易于维护: 清晰的测试结构和文档

通过遵循这些测试最佳实践，可以确保SDK的质量和稳定性。