# 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*