t-web-demo-run-all

Files (1)

• SKILL.md

SKILL.md (first lines)

`demo/e2e/extension/` 下的扩展用户故事演示属于 `extension-demo` phase；批次发现时排除该目录，单文件使用 `/t-tools:t-extension-demo-run`。


# 批量运行 Demo 测试（主会话逐文件驱动）

运行时边界：`${CLAUDE_PLUGIN_ROOT}/protocols/runtime-boundaries.md`（判断脚本入口或项目事实与插件默认冲突时读）
单文件运行与修复闭环：`${CLAUDE_PLUGIN_ROOT}/protocols/web-demo-run-repair-contract.md`（处理任一失败文件前读）

## 目标

- 自动发现除 `live/`、`fixtures/`、`templates/`、`verification/` 和文件名含 `test-` 之外的全部 Demo 测试（发现规则脚本内固化，不在 skill 层重写）。
- **由当前主会话逐个文件驱动**，每一步都是可观察、可中断的短 Bash / Agent 调用。
- 单文件失败时按 `web-demo-run-repair-contract.md` 的修复闭环处理，每文件最多 6 次尝试。
- 文件之间按共享协议的环境模式隔离数据，避免前一文件产生的业务数据影响后续测试。
- 每文件达到上限仍失败则标记 `FAILED` 并继续下一个文件，不阻塞整批。
- 持续写盘批次状态，支持 `continue` 从未完成文件的断点恢复；产出 Markdown + JSON 汇总报告。

## 两种模式

默认逐文件模式（无参数 / `continue`）：发现 → 逐文件跑 → 失败就当场修复 → 文件间数据隔离 → 收尾。每个文件独立诊断修复，互不参照。

扫描模式（`scan`）：先纯 Bash 预跑全部文件**不修复**，按归一化错误指纹聚类失败，再对每个 unique cluster 只修一次（用 representative 文件），最后回扫所有受影响文件。

**何时用扫描模式**：失败密集且疑似共享根因（如一批文件都挂在同一个失效 selector 或同一个后端接口变更上）。先用 `${CLAUDE_PLUGIN_ROOT}/guides/web-demo/batch-token-profiling.md` 的决策树判断；孤立失败为主或文件数少（< 5）时用默认模式，扫描模式的聚类开销不划算。不确定时先跑默认模式一次，再用该指南读画像决定。

## 执行流程（默认逐文件模式）

### A. 发现阶段（一次性，脚本辅助）

首次、`continue` 及 `scan` 都先按共享修复协议读取项目 `scripts/index.md` 和 fixture，恢复环境模式、URL、身份及清理入口。下列 B2 / S2 runner 示例展示默认 Web 命令；Shopify 模式必须追加 `--no-auto-env`，其清理与修复后加载验证均按协议的 Shopify Demo 运行模式执行。

```bash
uv run scripts/web-demo-run-all.py discover [--filter-file <path>]   # fresh
uv run scripts/web-demo-run-all.py discover continue                 # 断点恢复
```

stdout 打印单行 JSON，**必须解析它**，后续循环使用其中的 `discovered_files`（仓库相对路径列表）、`batch_run_id`、`json_report`（批次产物路径）和 `resume_index`（fresh 为 0）等字段，字段语义以脚本输出为准。脚本同时已写好初始批次 JSON（fresh）或已截断/重置好状态（continue）。脚本返回非零时按其错误信息处理（如 `continue` 找不到可继续内容则终止）。

### B. 主循环：对 `discovered_files[resume_index:]` 逐个文件

对每个文件记其 `zero_based_index`（在 `discovered_files` 中的全量下标，不是切片下标），依次执行：

#### B1. 写断点

```bash
uv run scripts/web-demo-run-all.py checkpoint --json <json_report> --index <zero_based_index>
```

#### B2. 运行整个测试文件

```bash
uv run scripts/web-demo-test-runner.py "<rel_path>" --run-id "<batch_run_id>-<file_key>-initial" --mode fast
```

默认 Web 模式下 `web-demo-test-runner.py` 会自检并按需启动/恢复 demo 环境；Shopify 模式使用已就绪的外部环境。解析其**最后一行** `Result: {...}`，按 `web-demo-run-repair-contract.md` 的 Runner 输出适配映射为 snake_case 批次 entry 字段。`file_key` 必须由相对路径的稳定 slug 或短哈希生成，避免不同目录的同名文件冲突。

#### B3. 整文件通过

`success == "true"`：本文件标记 `passed`、`fixed=false`，跳到 B5。

#### B4. 整文件失败 → 执行共享修复闭环

按 `web-demo-run-repair-contract.md` 的单文件执行顺序和修复行为处理当前失败用例，最多 6 轮。终验通过才记 `status=passed, fixed=true`；达到上限仍失败时记 `status=failed, fixed=false`，保留最后失败证据并继续批次。

#### B5. 持久化 + 文件间数据隔离

1. **保留最小结果**：只保留 `{status, exit_code, duration, run_id, logs, fixed}`；仅失败时再保留一句简短 `error`。文件名、下标、计数和总耗时由脚本推导。
2. **数据隔离**：若还有下一个文件，无论当前文件成功或失败，均按共享修复协议选择隔离方式。Shopify 模式核查项目 fixture 已清理本次测试数据；独立扩展模式确认 fixture 已清理 profile/stub；默认 Web 模式重建 Demo 环境和数据容器。隔离失败时执行 `block` 后中止批次（该命令保留断点且不追加结果）。以下 stop/start 仅用于默认 Web 模式：
   ```bash
   uv run scripts/demo-stop.py --quiet && uv run scripts/demo-start.py
   uv run scripts/web-demo-run-all.py block --json <json_report> --error "<简短原因>"
   ```
3. **写结果并推进断点**：数据隔离成功，或当前已是最后一个文件时，执行一条短命令。`record` 自动补齐 `test_file`，更新断点、计数和总耗时；成功结果不传 `--error`：

   ```bash
   uv run scripts/web-demo-run-all.py record --json <json_report> --status <passed|failed> --exit-code <n> --duration <s> --run-id <id> --logs <path> [--fixed] [--error "<失败摘要>"]
   ```

#### B6. 进入下一个文件

主会话进度只输出一行，不复述诊断、命令或 JSON：

```text
[<完成数>/<总数>] <PASS|FIXED|FAIL> <test_file> (<duration>s)
```

仅在 `FAIL` 或批次阻塞时追加一句原因；run ID、日志路径和累计统计留在最终报告中。

### C. 收尾

所有文件处理完（或切片耗尽）后：

```bash
uv run scripts/web-demo-run-all.py finalize --json <json_report>
```

脚本渲染 Markdown 报告并置 `batch_status=completed`，在 stdout 打印 `Passed: N  Failed: M`；`failed_count == 0` 时返回 0，否则返回 1。失败文件的诊断报告已在 B4 内联生成，**批次结束后不再单独批量跑 `web-demo-diagnose`**。

## 恢复机制

中断（手动 Ctrl-C、会话结束、上下文压缩）后：

```bash
/t-tools:t-web-demo-run-all continue
```

- `discover continue` 只恢复最近且 `batch_status=running` 的批次：存在 `current_file` 时从该文件重跑，否则从 `current_index`（必须等于已持久化 entry 数）继续。已持久化的成功或失败文件都不重跑。
- 无可继续内容时脚本返回非零并提示，skill 终止。
- 恢复点总是某个尚未写最终 entry 的文件；从 B1 重跑该文件并重建当次修复上下文。

## 批次状态契约

批次 JSON 由 `web-demo-run-all.py` 维护（`batch_status` / `discovered_files` / `entries[]` / `current_file` / `last_error` 等派生字段见脚本实现）。主会话不得读取、展开或整份重写 JSON，只通过 `discover` / `checkpoint` / `record` / `block` / `finalize` 子命令推进状态。

## 执行流程（扫描模式）

扫描模式把"先看全貌、再按唯一根因修"作为前置阶段，复用同一份批次 JSON 的 `scan_results` 字段。`scan`/`cluster` 子命令在 `${CLAUDE_PLUGIN_ROOT}/scripts/web-demo-run-all.py` 中定义。

### S1. 发现阶段

From timzaak/web-dev-skills, Apache-2.0.

More from timzaak/web-dev-skills