Story 004.002: 认证API实际请求测试

父史诗: 史诗004 - API实际请求测试基础设施 docs/prd/epic-004-api-actual-request-testing.md

Status

Draft

Story

As a 质量保证工程师 I want 实现认证API的实际HTTP请求测试 so that 我可以在真实数据库环境下验证认证和授权流程的正确性，确保系统安全功能的可靠性

Acceptance Criteria

登录端点测试实现 - 支持多种认证场景（正确凭据、错误凭据、禁用账户）
令牌验证端点测试实现 - 验证JWT令牌的有效性和过期处理
权限检查端点测试实现 - 验证基于角色的访问控制
错误处理测试覆盖 - 包含认证失败、令牌过期、权限不足等场景
性能基准测试 - 认证操作响应时间<200ms

Tasks / Subtasks

实现登录端点测试 (AC: #1)
- 正确凭据登录测试
- 错误凭据登录测试
- 禁用账户登录测试
实现令牌验证端点测试 (AC: #2)
- 有效令牌验证测试
- 过期令牌验证测试
- 无效令牌验证测试
实现权限检查端点测试 (AC: #3)
- 管理员权限验证测试
- 用户权限验证测试
- 无权限访问测试
实现错误处理测试 (AC: #4)
- 认证失败错误处理测试
- 令牌过期错误处理测试
- 权限不足错误处理测试
实现性能基准测试 (AC: #5)
- 登录操作性能测试
- 令牌验证性能测试

Dev Notes

技术栈和测试框架 [Source: architecture/tech-stack.md#测试框架]

测试框架: Vitest 2.x + Hono Testing (testClient)
测试位置: src/server/api/auth/__tests__/ 目录
数据库: 使用真实PostgreSQL数据库连接进行测试
认证机制: JWT Bearer Token认证
覆盖率目标: 核心认证API端点测试覆盖率100%

项目结构指导 [Source: architecture/source-tree.md#API测试]

遵循架构设计: API测试文件应位于对应API端点的 __tests__ 文件夹中
目录结构: 认证测试放到 src/server/api/auth/__tests__/
测试工具: 复用现有的集成测试工具函数
测试数据: 使用现有的TestDataFactory创建测试用户和角色

现有测试基础设施 [Source: 故事004.001实现]

✅ 已有测试数据库工具: src/server/__test_utils__/integration-test-db.ts
✅ 已有集成测试工具: src/server/__test_utils__/integration-test-utils.ts
✅ 已有测试数据工厂: TestDataFactory.createTestUser()
✅ 已有用户API测试示例: src/server/api/users/__tests__/users.integration.test.ts
✅ 使用hono/testing的testClient()，提供类型安全
✅ 使用真实数据库连接而不是mock

API端点信息 [Source: api-design-integration.md]

认证端点:
- POST /api/v1/auth/login - 用户登录
- POST /api/v1/auth/verify - 令牌验证
- GET /api/v1/auth/permissions - 权限检查
认证机制: JWT Bearer Token
权限控制: 基于角色的访问控制(RBAC)

安全考虑 [Source: architecture/security-integration.md]

测试环境使用独立的测试数据库，与生产环境完全隔离
测试数据使用生成的测试用户，不包含真实凭据
敏感测试数据（如JWT令牌）进行适当处理
测试完成后自动清理所有测试数据
测试环境网络隔离，防止安全风险

测试标准要求 [Source: architecture/coding-standards.md#测试标准]

测试文件命名: auth.integration.test.ts
测试组织: 使用describe/it块结构
断言风格: Expect语法
测试数据: 使用工厂函数创建测试用户和角色
错误测试: 包含各种错误场景的测试用例

Testing

测试策略

测试类型: 集成测试（实际HTTP请求 + 真实数据库）
测试范围: 所有核心认证API端点
测试数据: 使用工厂模式创建测试用户、角色和权限
清理机制: 每个测试用例后清理测试数据
安全测试: 包含各种认证失败场景

测试验证点

HTTP状态码验证（200, 401, 403等）
JWT令牌生成和验证正确性
响应数据结构验证
数据库状态验证（用户会话等）
错误处理验证
性能基准验证（响应时间 < 200ms）

测试报告

Vitest测试报告生成
覆盖率报告集成
CI/CD流水线自动执行

Change Log

Date	Version	Description	Author
2025-09-17	1.0	初始故事创建	Sarah (PO)

Dev Agent Record

Agent Model Used

-

Debug Log References

-

Completion Notes List

-

File List

src/server/api/auth/__tests__/auth.integration.test.ts - 认证API集成测试
可能需要更新的相关文件：
- src/server/__test_utils__/integration-test-db.ts - 如果需要添加认证相关测试数据
- src/server/__test_utils__/integration-test-utils.ts - 如果需要添加认证测试工具函数

QA Results