cfc/docs/tdd/test/runbook.md

CFC · 测试工作 Runbook（发现/跟踪 + 本机执行）

生成日期：2026-11-01 ｜ 模式：discovery-only（发现/跟踪） 本仓库的 tdd-orchestrator 定位为「发现 / 格式化 / 跟踪已有测试」，实际跑测试在开发机完成 （需 mvn / MySQL / 已配好的 Python 环境）。本沙箱负责发现、编目、规划与进度跟踪。 ⚠️ 测试目标环境：http://cfc.iwintrue.com（远程测试环境）。本机跑测试只针对该环境，不指向本地后端 / 不指向生产。

1. 当前测试资产（只读扫描，2026-11-01）

来源	文件数	用例/方法
结构化用例 tests/test-cases/*.md	9	678
Playwright tests/**/*.spec.js	70	411
Python pytest（cfc-langgraph + tools/xaf_agent_hub）	12	47
Java 后端 @Test（cfc-backend/src/test/java）	182	1379
用户场景 tests/user-scenarios/*.md	8	文件级
合计	—	2515

后端 Controller 共 357 个、handler 方法 1933，已覆盖仅 199（10.3%），未覆盖 271 个。

2. 后端覆盖缺口 Backlog（按模块，真实扫描结果）

缺口 = 当前测试源中没有任何 handler 被命中的 Controller。这是发现出的真实缺口，非发明。

模块	未覆盖	总数	覆盖率	优先级
admin（运营后台）	103	120	14%	P0
guide（规划师）	14	19	26%	P1
family（家庭）	8	15	47%	P1
mind（心理）	6	8	25%	P2
assessment（测评）	5	6	17%	P2
diet / recommendation / fatloss / task / wealth / user 等	各 3–5	0%	—	P2/P3

admin 占全部未覆盖的约 38%，且多为核心管理接口，补测收益最高。

3. 执行 Runbook（开发机）

3.1 Java 纯单测子集（无需数据库）

cd cfc-backend
mvn -q -DskipTests compile
# 只跑不依赖 Spring 上下文 / 数据库的纯单测包
mvn test -Dtest='com.etotem.cfc.unit.**,com.etotem.cfc.util.**,com.etotem.cfc.common.**'

3.2 Java 集成测试（需 MySQL@3306 + Redis@6379 已起）

cd cfc-backend
mvn test -Dtest='com.etotem.cfc.integration.**'
# 全量（耗时较长，需完整基础设施）：
mvn test

3.3 Python（cfc-langgraph）—— 远程执行，不在本地跑

⚠️ cfc-langgraph（Python / FastAPI / LangGraph）部署在 192.168.16.251（opencode.iwintrue.com）测试环境主机上，不在本机跑。其 pytest 通过 opencode_sessions.junit（client=opencode-iwintrue）远程派发执行。 本沙箱只做发现/编目（扫描 cfc-langgraph/tests 仓库内容），不本地安装 venv / 不本地运行 langgraph 测试。 此前"langgraph 需本地 Python 3.14 venv"的判断已作废 —— 该服务在远程测试环境运行，本地无需配置其运行环境。

# 发现/编目（本地只读扫描，OK）
python <skill>/test_inventory.py --project d:/cfc
# 实际运行 langgraph pytest：经 opencode.iwintrue.com 远程会话派发（delegation_enabled=true）
# 由 tdd_orchestrate.py 的 --auto / --alloc-session 选 label=python / langgraph 路由到 junit 会话

3.4 Playwright E2E / API（针对 cfc.iwintrue.com 测试环境）

项目 Playwright 配置默认已指向测试环境：

• playwright.config.api.js → baseURL 直接 http://cfc.iwintrue.com（API 级 e2e）
• playwright.config.js（主） → 默认 http://cfc.iwintrue.com（可用 PW_BASE_URL 覆盖）
• playwright.config.func.js / playwright.config.smoke.js → 默认 http://127.0.0.1:9082，跑测试环境需显式覆盖
• e2e_complete_test.py → BASE = http://cfc.iwintrue.com:80

⚠️ 后台小程序 Web 版前端部署在 http://cfc.iwintrue.com/frontend（根路径 / 返回 404 白标，非 API 路径 /frontend 才是 SPA）。 因此：

• API 级 e2e（走 request 上下文，不依赖前端）→ 直接对 cfc.iwintrue.com 跑（已验证）。
• UI 级 e2e（依赖 page.goto/DOM）→ baseURL 须指向 http://cfc.iwintrue.com/frontend，否则会因根路径 404 而全部失败。UI 用例可在本沙箱直接用已装 chromium 跑（不依赖 opencode）；也可经 opencode 派发到 189/本机跑（见 3.5）。

cd tests
npm install
npx playwright install chromium
# 针对测试环境（func/smoke 需带 PW_BASE_URL；api/主配置默认即是）
PW_BASE_URL=http://cfc.iwintrue.com npx playwright test --project=api      # API 级 e2e（默认指向测试环境）
PW_BASE_URL=http://cfc.iwintrue.com npx playwright test --project=smoke    # 冒烟（覆盖 localhost 默认）
PW_BASE_URL=http://cfc.iwintrue.com npx playwright test --project=func     # 功能（覆盖 localhost 默认）
PW_BASE_URL=http://cfc.iwintrue.com npx playwright test                    # 全量
# UI 级 e2e 针对小程序前端（baseURL 指向 /frontend）
PW_BASE_URL=http://cfc.iwintrue.com/frontend npx playwright test --project=desktop   # 桌面端 UI（如有）
# Python 端到端（已硬编码 cfc.iwintrue.com:80）
python e2e_complete_test.py

3.5 小程序 Web 自动化（opencode 派发，189 / 本机）

后台小程序的 Web 自动化测试在 192.168.16.189:4090（189）与 localhost:4091（本机）两台 opencode 会话上派发执行，均针对 http://cfc.iwintrue.com/frontend。

• opencode_sessions.testing（client=web-4091）→ 项目目录 d:/cfc（本机）
• opencode_sessions.production（client=web-189-4090）→ 项目目录 c:/code/cfc（189）
• 并发约束：agent_session_limit=1（每台 Web 自动化服务器同时最多 1 个会话，含跨项目）。

⚠️ 当前执行阻塞（R8）：三台 opencode 共用 AgnesAI LLM 配额已耗尽（429），agent 无法完成工具循环，故经 opencode 派发的小程序 Web 自动化暂时跑不起来。 替代方案：UI 级 e2e 可直接在本沙箱用 Playwright + chromium 对 cfc.iwintrue.com/frontend 跑（见 3.4），不依赖 opencode 配额。待 R8 解除后，opencode 派发即可恢复。

4. 推荐执行顺序（先立基线，再补重依赖）

1. Java 纯单测子集 —— 最快建立通过基线，本地编译运行、不依赖远程（验证代码层，非环境层）。
2. Python pytest（cfc-langgraph） —— 远程执行：经 opencode.iwintrue.com 会话派发（label=python/langgraph），不在本机跑。
3. Java 集成测试 —— 连测试环境 DB/Redis 或本地基础设施后跑（环境层验证）。
4. Playwright E2E / API —— 针对 cfc.iwintrue.com 测试环境跑（见 3.4，func/smoke 带 PW_BASE_URL）。

5. 进度跟踪（本沙箱侧车）

• 进度落 .tdd/test-progress.json，按 anchor = source_path#local_id 索引（如 tests/test-cases/admin.md#TC-A-01）。
• 执行后在本沙箱跑 test_inventory.py 即从侧车派生 docs/tdd/test/automation-status.md。
• 原始测试文件零侵入：只改侧车，不改 .md / .spec.js / .py / .java。

• 发现 / 台账命令（只读）：

  python <skill>/discover_tests.py --project d:/cfc
  python <skill>/test_inventory.py --project d:/cfc
  

  <skill> = C:/Users/iwt/.workbuddy/skills/tdd-orchestrator/scripts

6. 优先级与下一步

• 先补 admin 模块（103 未覆盖，核心管理接口），再 guide / family / mind / assessment。
• 在开发机执行完任一子集后，把结果回填侧车（通过 / 失败 / 阻塞），再跑 test_inventory.py 刷新共享台账。
• 所有 E2E / API 测试一律针对 http://cfc.iwintrue.com 测试环境；Java 单测为本地代码层验证，集成测试连测试环境基础设施。
• 本沙箱不推送 .tdd/；docs/tdd/test/*.md 可提交推送给测试团队。