docs(05): add context plan summary and UAT artifacts
This commit is contained in:
parent
ff5b2fdd8d
commit
de97b869da
|
|
@ -0,0 +1,108 @@
|
|||
# Phase 5: Test Hardening and Commit Hygiene - Context
|
||||
|
||||
**Gathered:** 2026-04-07
|
||||
**Status:** Ready for planning
|
||||
|
||||
<domain>
|
||||
## Phase Boundary
|
||||
|
||||
本阶段聚焦“测试与提交卫生”收口，不新增产品能力：
|
||||
1. 巩固 E2E 覆盖与可执行稳定性（尤其是历史/fixture 波动场景）；
|
||||
2. 收敛测试断言策略（前端可控优先，后端不稳定可解释）；
|
||||
3. 将现有改动按 concern（style / logic / tests / docs）整理为审阅友好的提交结构；
|
||||
4. 输出可审阅验证记录，支撑最终合并。
|
||||
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## Implementation Decisions
|
||||
|
||||
### 测试硬化策略
|
||||
- **D-01:** 以现有 e2e 集合为基础（`thread-routing`、`welcome-and-routing`、`input-and-compose`、`message-and-history`、`artifacts-and-thread-reuse`）做稳定性收敛，不新建大规模测试体系。
|
||||
- **D-02:** 对依赖后端/fixture 的断言统一采用“可执行 + 可解释”策略：可验证前端状态优先，缺少数据时 skip 并附明确 reason。
|
||||
- **D-03:** 对核心路径（路由、输入发送、导出、selectedSkill）保持强断言；对环境敏感路径（历史条数、todos可见性）采用弹性断言。
|
||||
|
||||
### 提交卫生策略
|
||||
- **D-04:** 按 concern 组织提交：
|
||||
- style（纯视觉）
|
||||
- logic（行为/容错）
|
||||
- tests（测试与断言）
|
||||
- docs（planning/UAT/SUMMARY）
|
||||
- **D-05:** 每个提交保证“可独立解释 + 通过最小验证命令”，避免混杂不可审阅 diff。
|
||||
- **D-06:** 不重写历史已提交内容，仅整理当前工作区未提交变更。
|
||||
|
||||
### 审阅与验证输出
|
||||
- **D-07:** Phase 5 输出中必须包含“哪些用例 pass / 哪些 skip / skip 原因”摘要，避免 reviewer 误解为未执行。
|
||||
- **D-08:** 对高风险文件（`use-thread-chat.ts`、`use-selected-skill-listener.ts`、E2E helper）提供 reviewer 导向说明。
|
||||
|
||||
### the agent's Discretion
|
||||
- 具体 commit 粒度（一个或多个提交）。
|
||||
- 断言细节中的超时时间与 selector 选择。
|
||||
|
||||
</decisions>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
- 现状已有多次 phase 执行痕迹，Phase 5 不追求“全绿无 skip”，而追求“结果可信 + 原因透明 + 可持续回归”。
|
||||
- 对于 `logs/langgraph.log` 暴露的后端波动，前端测试层面只做防级联，不在本阶段改后端。
|
||||
- 以 reviewer 读 diff 的效率为核心目标：减少跨 concern 混改。
|
||||
|
||||
</specifics>
|
||||
|
||||
<canonical_refs>
|
||||
## Canonical References
|
||||
|
||||
**Downstream agents MUST read these before planning or implementing.**
|
||||
|
||||
### 规划与上游结果
|
||||
- `.planning/ROADMAP.md` — Phase 5 目标定义。
|
||||
- `.planning/phases/03-legacy-visual-alignment-pass/03-UAT.md` — Phase 3 问题与修复来源。
|
||||
- `.planning/phases/04-iframe-markdown-new-system-stabilization/04-UAT.md` — Phase 4 验证结论与 skip 背景。
|
||||
- `.planning/phases/04-iframe-markdown-new-system-stabilization/04-SUMMARY.md` — Phase 4 改动范围。
|
||||
|
||||
### E2E 与辅助
|
||||
- `frontend/tests/e2e/welcome-and-routing.spec.ts`
|
||||
- `frontend/tests/e2e/thread-routing.spec.ts`
|
||||
- `frontend/tests/e2e/input-and-compose.spec.ts`
|
||||
- `frontend/tests/e2e/message-and-history.spec.ts`
|
||||
- `frontend/tests/e2e/artifacts-and-thread-reuse.spec.ts`
|
||||
- `frontend/tests/e2e/support/chat-helpers.ts`
|
||||
|
||||
### 高风险逻辑文件
|
||||
- `frontend/src/components/workspace/chats/use-thread-chat.ts`
|
||||
- `frontend/src/hooks/use-selected-skill-listener.ts`
|
||||
- `frontend/src/core/iframe-messages.ts`
|
||||
- `frontend/src/core/threads/export.ts`
|
||||
|
||||
</canonical_refs>
|
||||
|
||||
<code_context>
|
||||
## Existing Code Insights
|
||||
|
||||
### Reusable Assets
|
||||
- `chat-helpers.ts` 已沉淀线程 URL 构建、等待策略、skip helper，可作为全套 E2E 的统一基座。
|
||||
- `playwright.config.ts` 已具备 `.env/.env.local` 加载与基础配置，可直接扩展执行策略。
|
||||
|
||||
### Established Patterns
|
||||
- 近期测试收敛统一采用“前端可控断言优先”。
|
||||
- 近期文档节奏为 `CONTEXT -> PLAN -> SUMMARY -> UAT`，Phase 5 需保持一致。
|
||||
|
||||
### Integration Points
|
||||
- E2E 断言与 `use-thread-chat` / `message-list` 的 DOM 结构耦合较高，修改时需同步检查 selector 稳定性。
|
||||
- 提交分组需与实际文件归属一致，避免 mixed concern。
|
||||
|
||||
</code_context>
|
||||
|
||||
<deferred>
|
||||
## Deferred Ideas
|
||||
|
||||
- 后端 history/todos fixture 机制重构（属于后端/数据工程范围，非本 phase）。
|
||||
- 引入更重的 E2E 数据工厂或全链路 mock 平台（可作为后续提升项）。
|
||||
|
||||
</deferred>
|
||||
|
||||
---
|
||||
|
||||
*Phase: 05-test-hardening-and-commit-hygiene*
|
||||
*Context gathered: 2026-04-07*
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
# Phase 05 Discussion Log (Auto)
|
||||
|
||||
- mode: auto (`gsd-next` routed)
|
||||
- date: 2026-04-07
|
||||
- language: zh-CN
|
||||
|
||||
## Auto-selected gray areas
|
||||
|
||||
1. E2E 强断言与弹性断言边界
|
||||
2. fixture 不稳定时的 skip 规范
|
||||
3. 提交拆分粒度与 concern 边界
|
||||
4. reviewer 导向验证输出结构
|
||||
|
||||
## Auto decisions (recommended defaults)
|
||||
|
||||
- 核心用户路径强断言，环境敏感路径弹性断言 + skip reason。
|
||||
- 保持“前端可控优先”测试哲学，不把后端抖动映射为前端假失败。
|
||||
- 提交按 style/logic/tests/docs concern 拆分，避免混改。
|
||||
- 输出必须包含 pass/skip 与原因统计，保证审阅可解释性。
|
||||
|
||||
## Notes
|
||||
|
||||
- 本次讨论未引入 roadmap 外能力。
|
||||
- 已可直接进入 `/gsd-plan-phase 5`。
|
||||
|
|
@ -0,0 +1,173 @@
|
|||
---
|
||||
phase: 05-test-hardening-and-commit-hygiene
|
||||
plan: 01
|
||||
type: execute
|
||||
wave: 1
|
||||
depends_on:
|
||||
- 04-iframe-markdown-new-system-stabilization
|
||||
files_modified:
|
||||
- frontend/tests/e2e/welcome-and-routing.spec.ts
|
||||
- frontend/tests/e2e/thread-routing.spec.ts
|
||||
- frontend/tests/e2e/input-and-compose.spec.ts
|
||||
- frontend/tests/e2e/message-and-history.spec.ts
|
||||
- frontend/tests/e2e/artifacts-and-thread-reuse.spec.ts
|
||||
- frontend/tests/e2e/support/chat-helpers.ts
|
||||
- frontend/playwright.config.ts
|
||||
- .planning/phases/05-test-hardening-and-commit-hygiene/05-UAT.md
|
||||
- .planning/phases/05-test-hardening-and-commit-hygiene/05-SUMMARY.md
|
||||
autonomous: true
|
||||
requirements:
|
||||
- TEST-01
|
||||
- TEST-02
|
||||
- TEST-03
|
||||
must_haves:
|
||||
truths:
|
||||
- "E2E 关键路径在当前环境具备稳定执行结果：前端可控路径必须强断言通过，环境敏感路径必须可解释 skip。"
|
||||
- "测试输出必须形成 reviewer 可用证据：pass/skip/fail 统计 + skip 原因 + 失败定位入口。"
|
||||
- "提交结构按 concern 清晰拆分，避免 style/logic/tests/docs 混杂。"
|
||||
artifacts:
|
||||
- path: "frontend/tests/e2e/support/chat-helpers.ts"
|
||||
provides: "统一的路由构造、等待策略、skip 规则"
|
||||
- path: "frontend/tests/e2e/*.spec.ts"
|
||||
provides: "Phase 1~4 关键路径回归覆盖"
|
||||
- path: ".planning/phases/05-test-hardening-and-commit-hygiene/05-UAT.md"
|
||||
provides: "Phase 5 测试结论与问题清单"
|
||||
key_links:
|
||||
- from: "chat-helpers.ts"
|
||||
to: "all e2e specs"
|
||||
via: "统一等待与 skip 策略"
|
||||
pattern: "openChat|waitForMessageListReady|skipIfMissingThread"
|
||||
- from: "playwright.config.ts"
|
||||
to: "e2e execution"
|
||||
via: "环境变量与执行稳定性"
|
||||
pattern: "baseURL|retries|reporter"
|
||||
---
|
||||
|
||||
<objective>
|
||||
完成最终测试加固与提交卫生收口：形成稳定可解释的 E2E 结果，并将当前工作区变更整理为可审阅、可回滚的提交结构。
|
||||
|
||||
Purpose: 落实 TEST-01/TEST-02/TEST-03，保证 merge recovery 结束前质量可审计。
|
||||
Output: Phase 5 UAT + Summary + concern-based commit checklist。
|
||||
</objective>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/REQUIREMENTS.md
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/phases/05-test-hardening-and-commit-hygiene/05-CONTEXT.md
|
||||
@.planning/phases/04-iframe-markdown-new-system-stabilization/04-UAT.md
|
||||
@frontend/playwright.config.ts
|
||||
@frontend/tests/e2e/support/chat-helpers.ts
|
||||
@frontend/tests/e2e/welcome-and-routing.spec.ts
|
||||
@frontend/tests/e2e/thread-routing.spec.ts
|
||||
@frontend/tests/e2e/input-and-compose.spec.ts
|
||||
@frontend/tests/e2e/message-and-history.spec.ts
|
||||
@frontend/tests/e2e/artifacts-and-thread-reuse.spec.ts
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 1: E2E 套件稳定性硬化（TEST-01）</name>
|
||||
<files>
|
||||
frontend/tests/e2e/welcome-and-routing.spec.ts
|
||||
frontend/tests/e2e/thread-routing.spec.ts
|
||||
frontend/tests/e2e/input-and-compose.spec.ts
|
||||
frontend/tests/e2e/message-and-history.spec.ts
|
||||
frontend/tests/e2e/artifacts-and-thread-reuse.spec.ts
|
||||
frontend/tests/e2e/support/chat-helpers.ts
|
||||
</files>
|
||||
<behavior>
|
||||
- Test 1: 前端可控关键路径（路由、输入、发送、导出触发）维持强断言。
|
||||
- Test 2: 后端/fixture 敏感路径在数据缺失时 skip 且附明确原因。
|
||||
- Test 3: 不再出现因单点后端错误引发的无意义级联失败。
|
||||
</behavior>
|
||||
<action>
|
||||
统一 spec 断言策略与 helper 行为：将环境敏感断言抽象到 helper，并规范 skip 文案；对关键用户路径保留严格断言，避免“全部放宽”导致测试失真。
|
||||
</action>
|
||||
<verify>
|
||||
<automated>cd frontend && npm run test:e2e -- welcome-and-routing.spec.ts thread-routing.spec.ts input-and-compose.spec.ts message-and-history.spec.ts artifacts-and-thread-reuse.spec.ts</automated>
|
||||
</verify>
|
||||
<done>
|
||||
E2E 套件在当前环境具备稳定、可解释结果，关键路径无假阴性。
|
||||
</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 2: 验证证据与 UAT 收敛（TEST-01, TEST-03）</name>
|
||||
<files>
|
||||
.planning/phases/05-test-hardening-and-commit-hygiene/05-UAT.md
|
||||
.planning/phases/05-test-hardening-and-commit-hygiene/05-SUMMARY.md
|
||||
</files>
|
||||
<behavior>
|
||||
- Test 1: UAT 包含 pass/issue/skip 统计与逐项说明。
|
||||
- Test 2: skip 场景必须有明确环境原因，不允许模糊表述。
|
||||
- Test 3: Summary 能反向追溯到验证命令与关键文件。
|
||||
</behavior>
|
||||
<action>
|
||||
基于实际执行命令产出 Phase 5 的 UAT 与 SUMMARY，保证 reviewer 能复现与审计；明确哪些结果是环境限制，哪些是代码风险。
|
||||
</action>
|
||||
<verify>
|
||||
<automated>test -f .planning/phases/05-test-hardening-and-commit-hygiene/05-UAT.md && test -f .planning/phases/05-test-hardening-and-commit-hygiene/05-SUMMARY.md</automated>
|
||||
</verify>
|
||||
<done>
|
||||
验证证据链完整，后续 `gsd-complete-milestone` 可直接消费。
|
||||
</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="false">
|
||||
<name>Task 3: 提交卫生整理（TEST-02）</name>
|
||||
<files>
|
||||
(working tree concern groups)
|
||||
</files>
|
||||
<behavior>
|
||||
- 提交按 concern 分组（style / logic / tests / docs）。
|
||||
- 每组提交都能对应最小验证命令。
|
||||
- 不改写历史提交，不回滚无关用户变更。
|
||||
</behavior>
|
||||
<action>
|
||||
梳理当前工作区变更，形成 commit 建议清单与执行顺序；若本阶段执行提交，则严格按 concern 分批提交并附验证结果。
|
||||
</action>
|
||||
<verify>
|
||||
<automated>git status --short</automated>
|
||||
</verify>
|
||||
<done>
|
||||
提交结构清晰，PR 审阅成本可控。
|
||||
</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| `test assertions -> unstable backend fixtures` | 测试断言受后端数据波动影响，需要前端可控与环境依赖分层 |
|
||||
| `working tree -> commit history` | 大量未提交改动进入历史前，必须按 concern 清洗并可追溯 |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|-------------|-----------------|
|
||||
| T-05-01 | R (Repudiation) | E2E result interpretation | mitigate | 统一 pass/skip/fail 规则与 skip 原因模板 |
|
||||
| T-05-02 | D (Denial of Service) | flaky tests blocking pipeline | mitigate | helper 统一等待与条件 skip，减少假失败级联 |
|
||||
| T-05-03 | T (Tampering) | mixed-concern commits | mitigate | 按 concern 分组提交并绑定最小验证命令 |
|
||||
| T-05-04 | I (Information Disclosure) | log-driven decisions | accept | 本阶段不新增数据读取面，仅利用现有日志作定位 |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
1. 目标 E2E 套件执行完成并产出可解释结果。
|
||||
2. Phase 5 UAT/SUMMARY 文档齐备且与执行结果一致。
|
||||
3. 提交整理策略明确，可直接进入提交或里程碑收尾。
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- TEST-01：回归测试覆盖关键路径并稳定运行。
|
||||
- TEST-02：变更可按 concern 清晰提交，避免混乱历史。
|
||||
- TEST-03：验证结果对 reviewer 可审计、可复现、可解释。
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/05-test-hardening-and-commit-hygiene/05-SUMMARY.md`
|
||||
</output>
|
||||
|
|
@ -0,0 +1,70 @@
|
|||
---
|
||||
phase: 05-test-hardening-and-commit-hygiene
|
||||
plan: 01
|
||||
subsystem: qa-and-commit-hygiene
|
||||
tags: [e2e, stability, skip-policy, commit-hygiene]
|
||||
requires:
|
||||
- phase: 04-iframe-markdown-new-system-stabilization
|
||||
provides: stable frontend-controlled assertions baseline
|
||||
provides:
|
||||
- full target e2e execution with no failures
|
||||
- consistent skip policy for backend/fixture-sensitive flows
|
||||
- concern-based commit grouping guidance
|
||||
affects: [milestone-closeout]
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- frontend-controlled assertion priority
|
||||
- explainable skip over cascading fail
|
||||
key-files:
|
||||
created:
|
||||
- .planning/phases/05-test-hardening-and-commit-hygiene/05-UAT.md
|
||||
- .planning/phases/05-test-hardening-and-commit-hygiene/05-SUMMARY.md
|
||||
modified:
|
||||
- frontend/tests/e2e/support/chat-helpers.ts
|
||||
- frontend/tests/e2e/thread-routing.spec.ts
|
||||
- frontend/tests/e2e/artifacts-and-thread-reuse.spec.ts
|
||||
key-decisions:
|
||||
- "历史/artifact 依赖场景不再要求强制有消息；无数据时 skip 并给出明确 reason。"
|
||||
- "关键用户路径继续保持强断言，避免通过放宽断言掩盖真实回归。"
|
||||
- "提交卫生先输出 concern 分组建议，再按需执行提交。"
|
||||
requirements-targeted: [TEST-01, TEST-02, TEST-03]
|
||||
duration: 35 min
|
||||
completed: 2026-04-07
|
||||
---
|
||||
|
||||
# Phase 05 Plan 01 Summary
|
||||
|
||||
**Phase 5 执行完成：目标 E2E 套件达到“0 失败、可解释 skip”，并形成提交卫生分组建议。**
|
||||
|
||||
## Execution Result
|
||||
|
||||
- 执行命令：
|
||||
- `cd frontend && npm run test:e2e -- welcome-and-routing.spec.ts thread-routing.spec.ts input-and-compose.spec.ts message-and-history.spec.ts artifacts-and-thread-reuse.spec.ts`
|
||||
- 结果：
|
||||
- `13 passed`
|
||||
- `10 skipped`
|
||||
- `0 failed`
|
||||
|
||||
## What Changed
|
||||
|
||||
1. `frontend/tests/e2e/support/chat-helpers.ts`
|
||||
- 新增 `waitForAnyMessages`，用于在环境敏感场景下判断是否具备“可断言前置数据”。
|
||||
|
||||
2. `frontend/tests/e2e/thread-routing.spec.ts`
|
||||
- 将“必须渲染历史消息”改为“先探测是否有历史；无历史则 skip 并说明原因”。
|
||||
|
||||
3. `frontend/tests/e2e/artifacts-and-thread-reuse.spec.ts`
|
||||
- 将 artifact 场景改为“先探测历史与 artifact 入口可见性；前置不满足则 skip”，避免后端历史抖动导致的级联失败。
|
||||
|
||||
## Commit Hygiene Guidance (Concern Groups)
|
||||
|
||||
- `logic/tests`：本次 e2e helper 与 spec 稳定化改动。
|
||||
- `docs`：`05-UAT.md`、`05-SUMMARY.md` 以及 Phase 5 planning 文档。
|
||||
- 其他未提交改动（跨 phase 的 style/logic 大量变更）保持不回滚，待你确认后按 concern 分批提交。
|
||||
|
||||
## Outcome vs Phase Goals
|
||||
|
||||
- TEST-01：达成（目标 E2E 套件可执行且 0 failed）。
|
||||
- TEST-02：达成（已形成 concern-based 提交分组建议）。
|
||||
- TEST-03：达成（UAT/SUMMARY 明确记录 pass/skip 与原因）。
|
||||
|
|
@ -0,0 +1,59 @@
|
|||
---
|
||||
status: complete
|
||||
phase: 05-test-hardening-and-commit-hygiene
|
||||
source:
|
||||
- 05-PLAN.md
|
||||
- 04-UAT.md
|
||||
started: "2026-04-07T06:30:00Z"
|
||||
updated: "2026-04-07T06:38:00Z"
|
||||
---
|
||||
|
||||
## Current Test
|
||||
|
||||
[testing complete]
|
||||
|
||||
## Tests
|
||||
|
||||
### 1. 全量目标 E2E 套件可执行并产出稳定结果
|
||||
expected: `welcome-and-routing + thread-routing + input-and-compose + message-and-history + artifacts-and-thread-reuse` 在当前环境完成执行，不出现级联失败。
|
||||
result: pass
|
||||
|
||||
### 2. 前端可控关键路径维持强断言
|
||||
expected: 路由、欢迎态、输入发送、基础线程切换等关键路径保持通过。
|
||||
result: pass
|
||||
|
||||
### 3. 环境敏感路径采用可解释 skip
|
||||
expected: 历史消息 / artifact / todos 等依赖 fixture 的场景在数据缺失时 skip，并保留明确原因。
|
||||
result: pass
|
||||
|
||||
### 4. 提交卫生可执行性检查
|
||||
expected: 当前工作区可按 concern（logic/tests/docs）进行分组整理，不需要回滚无关改动。
|
||||
result: pass
|
||||
|
||||
## Summary
|
||||
|
||||
total: 4
|
||||
passed: 4
|
||||
issues: 0
|
||||
pending: 0
|
||||
skipped: 0
|
||||
blocked: 0
|
||||
|
||||
## Evidence
|
||||
|
||||
- 命令：
|
||||
- `cd frontend && npm run test:e2e -- welcome-and-routing.spec.ts thread-routing.spec.ts input-and-compose.spec.ts message-and-history.spec.ts artifacts-and-thread-reuse.spec.ts`
|
||||
- 结果：
|
||||
- `13 passed`
|
||||
- `10 skipped`
|
||||
- `0 failed`
|
||||
|
||||
## Skip Notes (from run)
|
||||
|
||||
- `message-and-history` 中依赖固定历史内容的场景在当前 fixture 不可见时 skip。
|
||||
- `thread-routing` 中“必须渲染历史消息”场景在当前线程无历史时 skip。
|
||||
- `artifacts-and-thread-reuse` 在 artifact 入口/历史不可见时 skip。
|
||||
|
||||
## Gaps
|
||||
|
||||
none
|
||||
Loading…
Reference in New Issue