Skip to content

docs(test): Go 测试架构主设计 + 三阶段计划 + Phase 1 完整实现 (22/22 tasks)#49

Merged
ULookup merged 32 commits into
3.0-devfrom
docs/test-architecture-design
Jul 16, 2026
Merged

docs(test): Go 测试架构主设计 + 三阶段计划 + Phase 1 完整实现 (22/22 tasks)#49
ULookup merged 32 commits into
3.0-devfrom
docs/test-architecture-design

Conversation

@ULookup

@ULookup ULookup commented Jul 8, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

概述

重新设计 ChatNow 测试架构为纯 Go 测试栈，废弃之前的 C++ gtest/gmock 方案。本 PR 包含设计 spec + 三阶段实现计划 + Phase 1 完整代码实现（22/22 tasks，41 个测试用例）。

背景

3.0-dev 已有成熟的 Go 测试套件（tests/func/ 2502 行 + tests/perf/ 233 行 + tests/pkg/ 294 行），但：

  • 无 CI（.github/workflows/ 不存在）
  • C++ 测试（common/test/、media/test/）与 Go 测试并存，栈不统一
  • media/presence 覆盖薄，错误路径缺失

本 PR 确立方向：全部测试统一为 Go，C++ 测试逐步移除。

包含内容

1. 统一主设计 Spec（已归档原 4 份）

docs/superpowers/specs/2026-07-09-test-architecture-master-design.md（759 行）

  • 9 条设计原则、5 层测试金字塔（L0-L4）、4 目录 + 4 build tag
  • CI 5 job 设计、测试隔离策略、5 个基础设施包、统一 ID 方案
  • 256 条用例目录、4 阶段计划、11 项风险

2. 三阶段实现计划

  • docs/superpowers/plans/2026-07-09-phase1-bvt-core-and-infra.md（22 tasks, 41 cases）
  • docs/superpowers/plans/2026-07-09-phase2-media-presence-cpp-removal.md（22 tasks, 49 cases）
  • docs/superpowers/plans/2026-07-09-phase3-reliability-perf-baseline.md（15 tasks, 26 cases）

3. Phase 1 完整实现（22/22 tasks，code-only 模式，全部 review 通过）

基础设施包（Tasks 1-4）：

Task 内容 文件
1 cleanup 包 + config database 段 tests/pkg/cleanup/cleanup.go
2 WebSocket 客户端 + push proto tests/pkg/client/ws.go, tests/proto/chatnow/push/
3 DB + ES 直查验证包 tests/pkg/verify/db.go, es.go
4 Fixture 扩展（group + message + ws） tests/pkg/fixture/group.go, message.go, ws.go

BVT 烟雾测试（18 用例，//go:build bvt）：

Task 用例 文件
5 BVT setup（TestMain + CleanupAll） tests/bvt/setup_test.go
6 BVT-001~003 基础设施健康检查 tests/bvt/health_test.go
7 BVT-004~006 认证链路 tests/bvt/auth_test.go
8 BVT-007~008 社交链路 tests/bvt/social_test.go
9 BVT-009~011 消息链路 tests/bvt/message_test.go
10 BVT-012~014 会话链路 tests/bvt/conversation_test.go
11 BVT-015~017 媒体链路 tests/bvt/media_test.go
12 BVT-018 presence 链路 tests/bvt/presence_test.go

L2 功能补充 + 横切测试（//go:build func）：

Task 用例 文件
13 FN-TM-01/03/04 transmite 错误路径 + 读扩散 tests/func/transmite_test.go
14 FN-MS-01/06/10 + SelectByClientMsgId + UpdateReadAck tests/func/message_test.go
15 GetMemberIds 成功 + 非成员拒绝 tests/func/conversation_test.go
16 FN-WS-01/02 WebSocket 推送验证 tests/func/ws_notify_test.go
17 FN-DC-01/02/03 数据一致性验证 tests/func/consistency_test.go
18 FN-CC-01 并发幂等验证 tests/func/concurrency_test.go
19 FN-SEC-01/02/06 安全测试 tests/func/security_test.go

L3 场景测试（//go:build func）：

Task 用例 文件
20 SC-04 离线消息同步 tests/func/scenarios_test.go
21 SC-06 消息可靠性（MQ 可用版本） tests/func/scenarios_test.go

CI（Task 22）：

Task 内容 文件
22 BVT job 门禁 + test-bvt Makefile target .github/workflows/ci.yml, tests/Makefile

4. 最终全分支审查 + 修复

对 31 个提交（608KB diff）进行了最终全分支审查，发现并修复：

  • Critical: FN-SEC-06 endpoint path change_member_role -> change_role
  • Critical: push server (port 10008) 加入 WaitForStackReady 健康检查
  • Important: proto 生成文件加入 .gitignore + unstage
  • Important: SEC-01 双路径断言（HTTP error OR Header.Success=false）
  • Important: Redis FLUSHALL 响应解析（检查 +OK）
  • Additional: 3 个预存 gofmt 违规修复

执行模式

Code-only 模式：业务服务栈无法在 macOS 运行（Dockerfile 依赖 Linux 预编译二进制），所有代码通过 go build + go vet + gofmt 验证，go test 待 Linux CI 环境执行。每 task 经 subagent 实现 + 独立 reviewer 审查 + 最终全分支审查。

已知未阻塞问题

  • scripts/wait_for_services.sh 缺失（Phase 0 交付物，CI 实际运行前需创建）
  • ES 查询 JSON 注入（plan-mandated，当前 hex-only keyword 安全，Phase 2 需修）
  • FN-TM-01 创建 200 用户（~15-30s，CI 可接受）
  • Phase 0 plan 端口分配与 docker-compose.yml 不一致（文档问题）
  • verify/fixture 包部分方法未使用（Phase 2 预留）

评审要点

  1. 统一主设计 是否认同（5 层金字塔 + 4 目录 + 4 tag）
  2. Phase 1 用例覆盖 是否充分（18 BVT + 12 L2/横切 + 2 L3 + CI = 41 新用例）
  3. code-only 模式 是否接受（编译通过但未运行测试，待 Linux CI）
  4. 已知未阻塞问题 是否需要在合并前修

状态

Phase 1 完整完成（22/22 tasks + 最终审查 + 修复），准备合并到 3.0-dev。

ULookup added 26 commits July 8, 2026 18:31
@ULookup
docs(test): 核心功能测试架构设计（单元 + 集成 + E2E）
a470827 
设计三层测试金字塔：
- 单元测试：gtest + gmock，ServiceImpl 持有接口，mock 隔离依赖
- DAO 集成测试：真实 MySQL/Redis/ES/MQ/MinIO，docker-compose.test.yml
- E2E 测试：全栈 docker-compose，覆盖消息链路 + 媒体上传

CI 单 workflow 三 job 串联（unit -> integration -> e2e）。
Phase 0 搭基础设施，Phase 1 覆盖 transmite + message 核心链路。

接口抽取：i_*.hpp 接口头 + <concrete>.hpp 实现，分文件存放。
@ULookup
docs(test): spec self-review 修正
827a35d 
- 修正测试文件总数 22 -> 21（合并 1.3/1.4 避免重复计数）
- CI workflow 的 <同上依赖> 占位符替换为完整 apt install 列表
- mock_channel_manager.hpp 改为 mock_user_client.hpp（与 2.4 节 RPC mock 策略一致）
- 目录结构补充 Phase 1 范围说明
@ULookup
plan(test): Phase 0a 测试基础设施实现计划
be5197e 
7 个 Task 覆盖 spec 0.1-0.7：
- Task 1: docker-compose.test.yml + 健康检查脚本
- Task 2: CI workflow（三 job 串联）
- Task 3: CMake CTest 集成 + dummy 测试
- Task 4: 共享 fixtures（db/mq/fake_closure/proto_helpers）
- Task 5: E2E helpers 骨架（http/ws/test_users）
- Task 6: mocks 目录骨架
- Task 7: 验收

接口抽取（spec 0.8）拆到 Phase 0b 独立 plan。
@ULookup
docs(test): 重新设计为 Go 测试架构 + Phase 0 CI 计划
3bf3fb5 
废弃 C++ gtest/gmock 方案（接口抽取成本高、与 3.0-dev 服务结构不匹配），
改为纯 Go 测试栈，复用 3.0-dev 现有 tests/func + tests/perf 基础设施。

新 spec（2026-07-08-go-testing-design.md）：
- L2 功能测试 tests/func/ + L3 场景测试 + L4 性能测试
- 评估现有覆盖（identity/conversation/transmite 较完整，media/presence 薄）
- C++ 测试迁移映射（mime/jwt/content_hash 等 -> Go 行为测试）
- CI 三 job 串联（func 每 PR / scenario PR to 3.0-dev / perf nightly）
- 分期：Phase 0 CI / Phase 1 消息链路 / Phase 2 media+移除C++ / Phase 3 perf

新 plan（2026-07-08-phase0-ci-infrastructure.md）：
- Task 1: scripts/wait_for_services.sh
- Task 2: tests/.gitignore 忽略生成 proto
- Task 3: .github/workflows/ci.yml
- Task 4: Makefile 验证
- Task 5: 本地模拟 CI 验收
@ULookup
docs(test): 测试用例目录补充设计（124 个补充用例）
647cb12 
在 Go 测试架构 spec 基础上，细化每服务/每分类应有测试用例：

未测试 API 清单（P0）：
- media: CompleteUpload + 4 个 multipart API 完全未覆盖
- message: SelectByClientMsgId + UpdateReadAck 未覆盖
- conversation: GetMemberIds 未覆盖

各服务补充用例（83 个 L2）：
- identity +12 / relationship +8 / conversation +10
- message +14 / transmite +8 / media +18
- presence +8 / auth_middleware +5

新增跨服务测试分类（35 个）：
- WebSocket 推送 7 个（当前完全缺失）
- 数据一致性 7 个（DB/ES 直查验证）
- 并发 5 个（幂等/竞态）
- 可靠性 4 个（MQ/服务重启）
- 安全 6 个（注入/越权/提权）
- 限流配额 4 个

场景测试补充 5 个：
- 离线消息同步 / 媒体三步上传 / 消息可靠性
- 多设备登录 / 大群读扩散

按 Phase 分配：Phase 1 ~60 个 P0 / Phase 2 ~45 个 / Phase 3 ~19 个
@ULookup
docs(test): BVT 测试设计（18 个烟雾测试用例）
cc771ab 
- L0 烟雾测试定位：构建后 <2min 验证核心链路可用性
- 18 个用例覆盖 5 条命脉链路（认证/社交/消息/会话/媒体）+ presence + 基础设施健康
- 独立 build tag //go:build bvt + tests/bvt/ 目录 + make test-bvt 目标
- CI 集成：bvt job 作为最前置门控，func 依赖 bvt
- 维护规则：硬上限 25 个，零 flaky 容忍，失败不 retry
- Phase 0 归属：BVT 是 CI 第一道门，纳入 Phase 0 范围
@ULookup
docs(test): E2E 场景测试设计（12 个场景）
fb46cf9 
- L3 端到端测试定位：跨服务链路 + 数据一致性 + WS 推送验证
- 12 个场景：现有 3（SC-01~03）+ 已规划 5（SC-04~08）+ 新增 4（SC-09~12）
- 新增 SC-09 未读数一致性 / SC-10 撤回可见性 / SC-11 token 刷新 / SC-12 ES 搜索
- 基础设施设计：tests/pkg/client/ws.go + tests/pkg/verify/{db,es,minio}.go + tests/pkg/docker/compose.go
- 每个场景含完整 Go 代码 + 数据一致性断言点
- Phase 归属：Phase 1 落地 SC-04/05/09/10 + 基础设施，Phase 2 落地 SC-06/07/11，Phase 3 落地 SC-08/12
- 维护规则：硬上限 20 个，允许有限 flaky（与 BVT 零容忍不同）
@ULookup
docs(test): 统一测试架构主设计，归档原 4 份 spec
393d53c 
将 go-testing-design / bvt-test-design / e2e-test-design / test-case-catalog
合并为单一主设计文档，补齐横切缺口（测试隔离/可靠性基建/fixture/ID 方案），
CI 升级为 5 job（build/bvt/func/perf/reliability），目录改为 4 目录 + 4 build tag。

原 4 份 spec 移入 archive/ 作为历史参考。
@ULookup
docs(test): 新增 Phase 1/2/3 实现计划
ecf6485 
Phase 1 (3555 行, 22 tasks, 41 用例): BVT 18 + 核心消息链路错误路径 +
横切基建 (cleanup/ws client/verify/fixture) + WS/DC/CC/SEC P0 + SC-04/06

Phase 2 (2633 行, 22 tasks, 49 用例): media 18 + presence 8 + security 3 +
7 L3 场景 (SC-05/07/08/09/10/11/12) + 横切 13 + C++ 测试移除

Phase 3 (2358 行, 15 tasks, 26 用例): reliability 4 + quota 4 + perf 3 +
P2 边角 15 + chaos 包 + CI nightly perf/reliability job

3 个 subagent 并行编写，发现 master spec 中 17 处事实性偏差
(表名/ES 索引名/字段类型/proto 字段名等)，计划中使用实际代码的正确名称。
@ULookup
feat(test): cleanup 包 + config database 段 + func setup 调用 CleanupAll …
3b816c4 
…(code-only, tests pending stack)

- tests/pkg/cleanup/cleanup.go: TRUNCATE MySQL + FLUSHALL Redis + DELETE ES indices
- WaitForStackReady: 轮询 9 端口 + gateway /health
- EtcdServiceCount: etcd v3 REST API 查询服务注册数（BVT-003 用）
- config.yaml 新增 database 段（mysql_dsn/es_url/redis_nodes）
- func/setup_test.go 调用 CleanupAll 保证确定性状态
@ULookup
feat(test): WebSocket 客户端 + push proto 生成 (code-only, tests pending s…
30f384e 
…tack)

- tests/pkg/client/ws.go: NewWSClient/WaitForNotify/WaitForNotifyCount/Close
- 连接后发送 CLIENT_AUTH 帧（access_token + device_id）
- readLoop 解析 binary protobuf 帧按 NotifyType 分发
- Makefile proto target 添加 push 目录 + 动态 M flag 生成（适配 protoc-gen-go v1.36）
- 生成 notify.pb.go（NotifyMessage/NotifyType/NotifyClientAuth 等）
  和 push_service.pb.go（PushToUserReq/PushBatchReq 等）
- DEVIATION: 未跳过 notify.proto。原计划假设与 push_service.proto 类型重复，
  实际两文件定义不同类型（零重叠），均需生成否则 ws.go 编译失败
- ws.go: int32 参数与 NotifyType 比较时加 push.NotifyType() 类型转换
@ULookup
feat(test): verify 包 - DB + ES 直查验证 (code-only, tests pending stack)
2977043 
- verify/db.go: MessageExists/MessageCount/UserTimelineExists/FriendRelationExists/
  UnreadCount(计算)/MessageStatus/MessageByClientMsgId/MediaQuota/MemberRole
- verify/es.go: MessageIndexed/SearchHitCount/IndexExists（轮询 5s 等待异步索引）
- DB 列名修正：message.session_id=conversation_id, conversation_member 无 unread_count 列
@ULookup
feat(test): fixture 扩展 - group/message/ws
befb3b0 
- fixture/group.go: CreateGroup/AddMembers/CreateGroupSimple
- fixture/message.go: SendTextMessage/SendTextMessageWithClientMsgId/SendImageMessage
- fixture/ws.go: ConnectWS/ConnectWSWithDeviceID
- 所有 fixture 不做断言（除 t.Fatal），返回关键 ID 供测试断言
@ULookup
feat(bvt): setup_test.go - TestMain 加载 config + WaitForStackReady + C…
15ecdcd 
…leanupAll
@ULookup
test(bvt): BVT-001~003 基础设施健康检查
0819cf0 
- BVT-001: gateway HTTP /health 返回 200
- BVT-002: gateway WS 端口可连接
- BVT-003: etcd /service/ 下注册服务数 >= 8
@ULookup
test(bvt): BVT-004~006 认证链路冒烟
5ca5674 
- BVT-004: 用户名注册成功返回 user_id + tokens
- BVT-005: 登录成功返回 access_token + refresh_token
- BVT-006: 带 token 调 GetProfile 返回自身信息
@ULookup
test(bvt): BVT-007~008 社交链路冒烟
d30efa5 
- BVT-007: 发好友申请返回 notify_event_id
- BVT-008: 通过好友申请返回 new_conversation_id + 好友列表验证
@ULookup
test(bvt): BVT-009~011 消息链路冒烟
1c3f4be 
- BVT-009: 发文本消息返回 message_id + seq_id
- BVT-010: SyncMessages 返回刚发的消息
- BVT-011: GetHistory 返回消息列表
@ULookup
test(bvt): BVT-012~014 会话链路冒烟
84b3919 
- BVT-012: 创建群会话返回 conversation_id
- BVT-013: 添加成员到群会话 + 验证成员数
- BVT-014: 列出会话包含刚建的群
@ULookup
test(bvt): BVT-015~017 媒体链路冒烟
96882b1 
- BVT-015: apply_upload 返回 file_id + upload_url
- BVT-016: PUT MinIO + complete_upload success=true
- BVT-017: apply_download + 下载内容一致性验证
@ULookup
test(bvt): BVT-018 presence 链路冒烟
6e4ea01 
- BVT-018: 登录后 GetPresence 返回 ONLINE

BVT 套件 18 用例全量完成。
@ULookup
test(func): FN-TM-01/03/04 transmite 错误路径 + 读扩散
04b3e60 
- FN-TM-01: 大群读扩散验证（DB 直查 message 仅 1 条）
- FN-TM-03: client_msg_id 幂等去重（DB 直查不重复）
- FN-TM-04: 向已解散会话发消息失败（3001）
@ULookup
test(func): FN-MS-01/06/10 + SelectByClientMsgId + UpdateReadAck
dc203e6 
- FN-MS-01: 非成员 SyncMessages 失败(3002)
- FN-MS-06: 非发送者 RecallMessage 失败(3003)
- FN-MS-10: 删除他人消息失败(3003)
- SelectByClientMsgId_Found: 按 client_msg_id 查到消息
- SelectByClientMsgId_NotFound: 不存在的 client_msg_id 返回 nil
- UpdateReadAck_Success: 更新 last_read_seq + DB 直查验证
- UpdateReadAck_Idempotent: 重复 ACK 不回退 + DB 直查验证
@ULookup
test(func): GetMemberIds 成功 + 非成员拒绝
953fae8 
- GetMemberIds_Success: 返回 4 个成员 ID，包含 owner + 所有 members
- GetMemberIds_NotMember: 非成员调用失败(3002)
@ULookup
test(func): FN-WS-01/02 WebSocket 推送验证
332ab07 
- FN-WS-01: 发消息后接收方 WS 收到 CHAT_MESSAGE_NOTIFY
- FN-WS-02: 好友申请后被申请方 WS 收到 FRIEND_ADD_APPLY_NOTIFY
- 使用 fixture.ConnectWS 建立 WS + WaitForNotify 超时等待
@ULookup
test(func): FN-DC-01/02/03 数据一致性验证
ccca47f 
- FN-DC-01: 发消息后 DB message 1 行 + user_timeline 2 行（写扩散）
- FN-DC-02: 文本消息 ES 索引存在 + 内容匹配 + DB 一致
- FN-DC-03: 发 3 条消息后 DB 未读数 = 3（max_seq - last_read_seq 计算）
@ULookup ULookup changed the title docs(test): Go 测试架构设计 + Phase 0 CI 计划 docs(test): Go 测试架构主设计 + 三阶段计划 + Phase 1 实现 (Tasks 1-17/22) Jul 10, 2026
ULookup added 3 commits July 10, 2026 18:54
@ULookup
test(func): FN-CC-01 并发相同 client_msg_id 幂等
4cb1643 
- 10 goroutine 并发用相同 client_msg_id 发消息
- 仅 1 条落库 + 所有成功请求返回相同 message_id
- DB 直查验证 message 表仅 1 行
@ULookup
test(func): FN-SEC-01/02/06 安全测试
5eb0015 
- FN-SEC-01: 无 token 访问受保护接口被拒绝
- FN-SEC-02: 用 A 的 token 访问 B 的会话数据被拒绝(3002)
- FN-SEC-06: 普通成员改自己为群主被拒绝(3003) + DB 角色验证
@ULookup
test(func): SC-04 离线消息同步
f93d17f 
- u2 离线 -> u1 发 3 条 -> u2 上线 sync -> 验证按序不丢
- WS 不应收到已 sync 的旧消息
- alice 再发 1 条 -> bob WS 收到实时推送
- 增量 sync 仅返回新 1 条
- DB 直查验证 4 条消息落库
ULookup added 3 commits July 13, 2026 13:08
@ULookup
test(func): SC-06 消息可靠性（MQ 可用版本）
8e09fee 
- alice 发消息 -> 相同 client_msg_id 重发 -> 幂等返回相同 message_id
- bob sync 仅收到 1 条（不重复）
- SelectByClientMsgId 查到唯一消息
- DB 直查验证 message 表仅 1 行

Phase 1 场景测试完成：SC-04 离线同步 + SC-06 消息可靠性。
@ULookup
ci: BVT job 门禁 + test-bvt Makefile target
6275421 
- Makefile: 新增 test-bvt target (-tags=bvt -timeout=300s)
- ci.yml: 新增 bvt job (needs: build, func needs: bvt)
  - BVT 失败时 func 不跑（短路门禁）
  - push (非 main) + PR + nightly 触发 bvt
- build job 新增 Go vet + gofmt 检查
- CI 5 job 串联：build -> bvt -> func -> perf (+ reliability Phase 3)

Phase 1 完成：BVT 18 + L2 P0 12 + 横切 P0 9 + L3 P0 2 = 41 用例。
@ULookup
fix(test): final review fixes - endpoint path, push health check, git…
59e6690 
…ignore, SEC-01, Redis error check
@ULookup ULookup changed the title docs(test): Go 测试架构主设计 + 三阶段计划 + Phase 1 实现 (Tasks 1-17/22) docs(test): Go 测试架构主设计 + 三阶段计划 + Phase 1 完整实现 (22/22 tasks) Jul 13, 2026
@ULookup ULookup mentioned this pull request Jul 13, 2026
Merged
@ULookup
ULookup marked this pull request as ready for review July 16, 2026 06:15
@ULookup
ULookup merged commit 3253fef into 3.0-dev Jul 16, 2026
3 of 4 checks passed
@ULookup ULookup mentioned this pull request Jul 16, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@ULookup