docs/v1.0/server/guides/testing-ai-api.md

AI API 测试覆盖分析

日期: 2026-01-31
文件: server/app/api/v1/ai.py
测试文件: server/tests/integration/test_ai_api_workflow.py

端点列表

生成任务 API

端点	方法	测试状态	测试用例
/generate-image	POST	✅ 已测试	test_complete_image_generation_workflow
/generate-video	POST	✅ 已测试	test_text2video_workflow, test_img2video_workflow
/generate-sound	POST	⚠️ 部分测试	test_query_with_type_filter (仅创建)
/generate-voice	POST	❌ 未测试	-
/generate-subtitle	POST	❌ 未测试	-
/process-text	POST	❌ 未测试	-

任务管理 API

端点	方法	测试状态	测试用例
/jobs	GET	✅ 已测试	test_query_multiple_jobs, test_query_with_type_filter, test_pagination
/jobs/{job_id}	GET	✅ 已测试	test_complete_image_generation_workflow, test_query_nonexistent_job
/jobs/{job_id}/cancel	POST	✅ 已测试	test_complete_image_generation_workflow, test_cancel_nonexistent_job

统计和监控 API

端点	方法	测试状态	测试用例
/statistics	GET	✅ 已测试	test_job_statistics
/usage/stats	GET	✅ 已测试	test_usage_statistics
/queue/status	GET	✅ 已测试	test_queue_status

模型管理 API

端点	方法	测试状态	测试用例
/models	GET	✅ 已测试	test_get_all_models, test_get_models_by_type

测试覆盖率统计

• 总端点数: 13
• 已测试: 9 (69%)
• 部分测试: 1 (8%)
• 未测试: 3 (23%)

缺失的测试用例

1. /generate-voice (配音生成) ❌

优先级: 高

需要测试的场景:

• ✅ 成功创建配音任务
• ✅ 查询配音任务状态
• ✅ 不同语音类型（alloy, echo, fable, onyx, nova, shimmer）
• ✅ 不同语速（0.25 - 4.0）
• ✅ 不同语言（zh-CN, en-US）
• ✅ 积分不足
• ✅ 缺少必需字段（text）
• ✅ 无效的语音类型
• ✅ 无效的语速

测试代码示例:

async def test_voice_generation_workflow(
    async_client: AsyncClient,
    test_user_token: str,
    test_ai_pricing_configs,
    test_ai_models
):
    """测试配音生成流程"""
    response = await async_client.post(
        '/api/v1/ai/generate-voice',
        json={
            'text': 'Hello, this is a test',
            'voice_type': 'alloy',
            'speed': 1.0,
            'language': 'en-US'
        },
        headers={'Authorization': f'Bearer {test_user_token}'}
    )
    
    assert response.status_code == 200
    data = response.json()
    assert data['code'] == 0
    assert 'job_id' in data['data']

2. /generate-subtitle (字幕生成) ❌

优先级: 高

需要测试的场景:

• ✅ 成功创建字幕任务
• ✅ 查询字幕任务状态
• ✅ 不同语言（zh, en, ja, ko）
• ✅ 积分不足
• ✅ 缺少必需字段（audio_url）
• ✅ 无效的音频 URL
• ✅ 不支持的语言代码

测试代码示例:

async def test_subtitle_generation_workflow(
    async_client: AsyncClient,
    test_user_token: str,
    test_ai_pricing_configs,
    test_ai_models
):
    """测试字幕生成流程"""
    response = await async_client.post(
        '/api/v1/ai/generate-subtitle',
        json={
            'audio_url': 'https://example.com/audio.mp3',
            'language': 'zh'
        },
        headers={'Authorization': f'Bearer {test_user_token}'}
    )
    
    assert response.status_code == 200
    data = response.json()
    assert data['code'] == 0
    assert 'job_id' in data['data']

3. /process-text (文本处理) ❌

优先级: 高

需要测试的场景:

• ✅ 剧本解析（screenplay_parse）
• ✅ 内容分析（content_analysis）
• ✅ 风格转换（style_transform）
• ✅ 提示词生成（prompt_generation）
• ✅ 不同输出格式（json, text）
• ✅ 不同温度参数（0.0 - 2.0）
• ✅ 不同 max_tokens（100 - 8000）
• ✅ 积分不足
• ✅ 缺少必需字段（text, task_type）
• ✅ 无效的任务类型

测试代码示例:

async def test_text_processing_workflow(
    async_client: AsyncClient,
    test_user_token: str,
    test_ai_pricing_configs,
    test_ai_models
):
    """测试文本处理流程"""
    response = await async_client.post(
        '/api/v1/ai/process-text',
        json={
            'task_type': 'screenplay_parse',
            'text': '场景1：室内 - 白天\n一个男人走进房间。',
            'output_format': 'json',
            'temperature': 0.7,
            'max_tokens': 2000
        },
        headers={'Authorization': f'Bearer {test_user_token}'}
    )
    
    assert response.status_code == 200
    data = response.json()
    assert data['code'] == 0
    assert 'job_id' in data['data']

4. /generate-sound (音效生成) ⚠️

优先级: 中（已明确不支持）

当前状态: 返回 501 Not Implemented

需要测试的场景:

• ✅ 验证返回 501 状态码
• ✅ 验证错误信息清晰
• ✅ 验证不扣除积分
• ✅ 验证不创建任务

测试代码示例:

async def test_sound_generation_not_implemented(
    async_client: AsyncClient,
    test_user_token: str,
    test_ai_pricing_configs,
    test_ai_models
):
    """测试音效生成功能不可用"""
    response = await async_client.post(
        '/api/v1/ai/generate-sound',
        json={
            'description': 'Ocean waves',
            'duration': 5
        },
        headers={'Authorization': f'Bearer {test_user_token}'}
    )
    
    assert response.status_code == 501
    data = response.json()
    assert '暂不可用' in data['message']
    assert 'TTS' in data['message']

额外需要的测试场景

边界条件测试

1. 图片尺寸边界

   • 最小尺寸（256x256）
   • 最大尺寸（2048x2048）
   • 无效尺寸（负数、0、超大）

2. 视频时长边界

   • 最小时长（1秒）
   • 最大时长（60秒）
   • 无效时长（负数、0、超大）

3. 文本长度边界

   • 空文本
   • 超长文本（> 4096 字符）
   • 特殊字符

4. 并发限制

   • 单用户并发任务数限制
   • 系统总并发任务数限制

性能测试

1. 响应时间

   • 任务创建响应时间 < 500ms
   • 任务查询响应时间 < 200ms
   • 批量查询响应时间 < 1s

2. 吞吐量

   • 每秒可处理的请求数
   • 并发用户数

安全测试

1. SQL 注入

   • 在 prompt、description 等字段中注入 SQL
   • 在查询参数中注入 SQL

2. XSS 攻击

   • 在文本字段中注入脚本

3. 权限提升

   • 尝试访问管理员功能
   • 尝试修改其他用户的任务

4. 速率限制

   • 短时间内大量请求
   • DDoS 防护

测试优先级

P0 (必须)

1. ✅ /generate-voice - 配音生成（核心功能）
2. ✅ /generate-subtitle - 字幕生成（核心功能）
3. ✅ /process-text - 文本处理（核心功能）
4. ✅ /generate-sound - 音效生成 501 测试

P1 (重要)

1. ✅ 边界条件测试
2. ✅ 错误处理测试
3. ✅ 并发测试

P2 (可选)

1. ⚠️ 性能测试
2. ⚠️ 安全测试
3. ⚠️ 压力测试

建议的测试文件结构

tests/integration/
├── test_ai_api_workflow.py          # 现有：基础工作流测试
├── test_ai_voice_generation.py      # 新增：配音生成测试
├── test_ai_subtitle_generation.py   # 新增：字幕生成测试
├── test_ai_text_processing.py       # 新增：文本处理测试
├── test_ai_sound_generation.py      # 新增：音效生成 501 测试
├── test_ai_boundary_conditions.py   # 新增：边界条件测试
└── test_ai_security.py              # 新增：安全测试

测试数据准备

Fixtures 需求

1. 测试音频文件

   • 用于字幕生成测试
   • 格式：MP3, WAV
   • 时长：5-10秒

2. 测试图片文件

   • 用于图生视频测试
   • 格式：JPG, PNG
   • 尺寸：1024x1024

3. 测试文本

   • 剧本样本
   • 不同语言的文本
   • 特殊字符文本

下一步行动

1. 立即执行 (本周)

   • 创建 /generate-voice 测试
   • 创建 /generate-subtitle 测试
   • 创建 /process-text 测试
   • 创建 /generate-sound 501 测试

2. 短期计划 (下周)

   • 添加边界条件测试
   • 添加错误处理测试
   • 提高测试覆盖率到 90%+

3. 长期计划 (本月)

   • 添加性能测试
   • 添加安全测试
   • 集成到 CI/CD 流程

测试执行

运行所有 AI API 测试

# 在容器内执行
docker exec jointo-server-app pytest tests/integration/test_ai_api_workflow.py -v

# 运行特定测试类
docker exec jointo-server-app pytest tests/integration/test_ai_api_workflow.py::TestImageGenerationWorkflow -v

# 运行特定测试用例
docker exec jointo-server-app pytest tests/integration/test_ai_api_workflow.py::TestImageGenerationWorkflow::test_complete_image_generation_workflow -v

# 生成覆盖率报告
docker exec jointo-server-app pytest tests/integration/test_ai_api_workflow.py --cov=app/api/v1/ai --cov-report=html

测试覆盖率目标

• 当前覆盖率: ~69%
• 短期目标: 90%
• 长期目标: 95%+

总结

当前 AI API 测试覆盖了大部分核心功能，但仍有 3 个重要端点缺少测试：

1. /generate-voice - 配音生成
2. /generate-subtitle - 字幕生成
3. /process-text - 文本处理

建议优先补充这些测试用例，以确保 API 的稳定性和可靠性。