lingma-openai-gateway/tests/TEST_PLAN.md

lingma-openai-gateway 测试计划（tests）

1. 目标

• 覆盖网关核心稳定性路径：认证、并发限流、会话复用、协议内容规范化。
• 在不引入外部依赖（Lingma 进程/Playwright）的前提下，使用 unittest 完成可重复回归。
• 与现有 tests/test_tool_call_bridge.py 互补：该文件聚焦工具桥接，本计划补齐基础模块行为。

2. 范围与优先级

• P0（必须）
  1. 认证行为（app/auth.py）
  2. 并发守卫行为（app/concurrency.py）
  3. 会话缓存与工具配置指纹（app/session_cache.py）
• P1（应覆盖） 4) OpenAI/Anthropic 内容规范化（app/openai_schema.py, app/anthropic_schema.py）

3. 用例矩阵

用例ID	优先级	模块	场景	预期
TC-AUTH-01	P0	auth	Bearer 正确 token	认证通过
TC-AUTH-02	P0	auth	缺失/错误 Authorization	401 + invalid_api_key
TC-AUTH-03	P0	auth	Anthropic x-api-key 与 Bearer 兜底	正确 key 通过，缺失时报 AnthropicAuthError
TC-AUTH-04	P0	auth	metrics 在未配置 token 且非 public	503 + metrics_disabled
TC-CONC-01	P0	concurrency	max_in_flight<=0 无限制模式	获取/释放计数正确，release 幂等
TC-CONC-02	P0	concurrency	单槽占用后第二请求超时	抛 BackpressureRejected，rejected 计数+1
TC-SESS-01	P0	session_cache	hash_user_context 忽略 assistant/tool	哈希不受 assistant/tool 变化影响
TC-SESS-02	P0	session_cache	key 包含 tool_config 指纹	同语义配置同 key，配置变化 key 变化
TC-SESS-03	P0	session_cache	LRU 淘汰	超限后旧项淘汰，evict_total 增加
TC-SESS-04	P0	session_cache	TTL 过期	读取 miss，expire_total 增加
TC-SCHEMA-01	P1	openai_schema	多类型 content flatten	文本合并，图片/音频占位
TC-SCHEMA-02	P1	anthropic_schema	tool_use/tool_result flatten	生成可读文本片段
TC-SCHEMA-03	P1	anthropic_schema	anthropic_to_internal_messages	system + messages 正确映射
TC-SCHEMA-04	P1	anthropic_schema	affinity_key_for_anthropic 优先级	metadata.user_id 优先，fallback 为 hash 前缀

4. 测试文件落地

• 既有：tests/test_tool_call_bridge.py
• 新增：
  • tests/test_auth_concurrency.py
  • tests/test_session_cache_tooling.py
  • tests/test_schema_normalization.py

5. 执行步骤

1. 定点执行新增测试文件。
2. 全量执行 tests/ 下 test_*.py。
3. 汇总通过率与失败项（若失败，给出定位与修复建议）。

6. 执行命令

python3 -m unittest tests/test_auth_concurrency.py
python3 -m unittest tests/test_session_cache_tooling.py
python3 -m unittest tests/test_schema_normalization.py
python3 -m unittest tests/test_tool_call_bridge.py
python3 -m unittest discover -s tests -p "test_*.py"