summary-tool 2.0.1
Compare testdetails tables from HTML reports and generate diff/summary HTML reports.
License: MIT
Requires Python: >=3.11

# XTS Summary Tool

## 简介
`summary_tool` 是一个用于提取、比较本地或远程路径*ts文件下HTML内容并生成差异报告的 Python 包。它可以帮助对比两套不同版本跑测的xts report，并生成可视化的 HTML 汇总页面。

---

## 环境要求
- Python 3.11 或以上
- 运行环境：Linux (已在 Docker 镜像中测试)

---

## 安装步骤
1. 克隆或下载代码库（已在本目录下）。
2. 安装依赖：
   ```bash
   pip install -r requirements.txt
   ```
3. （可选）如果希望以命令行入口使用，推荐以可编辑方式安装：
   ```bash
   pip install -e .
   ```
   这会在 `PATH` 中添加 `summary-tool` 命令。

---

## 使用示例

比如以AATS实际目录为例，

交互模式：  
```bash
summary-tool -i http://12.22.193.246/AATS_XTS_REPORTS/_ANR16/DB28
在远程路径下发现以下子目录:
  1. /AATS_XTS_REPORTS/_ANR16
  2. 20251203_140
  3. 20251209_146
  4. 20251218_153
  5. 20251230_162
  6. 20260102_171
  7. 20260106_177
请选择目录编号:
  - 输入单个编号 → 生成该目录里XTS的汇总报告
  - 输入两个编号,用逗号分隔 → 生成两目录里XTS的对比报告
编号: 5,6
INFO: No testdetails for subdir 'gts', generating summary-only diff.
INFO: No testdetails for subdir 'sts', generating summary-only diff.
INFO: Merged diff report written to xts-diff_summary.html
```
```bash
summary-tool -i http://12.22.193.246/AATS_XTS_REPORTS/_ANR16/DB28
在远程路径下发现以下子目录:
  1. /AATS_XTS_REPORTS/_ANR16
  2. 20251203_140
  3. 20251209_146
  4. 20251218_153
  5. 20251230_162
  6. 20260102_171
  7. 20260106_177
请选择目录编号:
  - 输入单个编号 → 生成该目录里XTS的汇总报告
  - 输入两个编号,用逗号分隔 → 生成两目录里XTS的对比报告
编号: 6
INFO: Merged diff report written to xts_summary.html
```
单参数：  
```bash
summary-tool http://12.22.193.246/AATS_XTS_REPORTS/_ANR16/DB2881/20260102_171/
- 会把171版本下面所有的报告汇总到xts_summary.html，单列显示
```

双参数：  
```bash
summary-tool summary-tool http://12.22.193.246/AATS_XTS_REPORTS/287P_ANR14/DB23/20251130_667/ http://10.22.193.246/AATS_XTS_REPORTS/287P_ANR14/DB23/20251205_672/
- 会把667、672下面所有报告汇总，然后比对生成xts-diff_summary.html，双列显示
```

---
### 交互式模式（-i / --interactive）

`summary-tool -i <根URL>`

- 脚本会列出根 URL 下的子目录列表。
- 输入 **单个** 编号 → 生成该子目录的 **单列** 汇总报告（`xts_summary.html`）。
- 输入 **两个** 编号（用逗号分隔） → 对这两个子目录生成 **对比** 报告（`xts-diff_summary.html`），并递归搜索子目录中的所有 `test_result_failures_suite.html` 文件。
- 交互完成后，工具会自动进入原有的单列或双列流程，无需额外参数。

---

### 单列模式（单参数）
单列模式仅提供左侧路径（目录或 HTML 文件），工具会递归搜索 `test_result_failures_suite.html`（或首个 HTML）并生成单独的汇总报告。
```bash
# 左侧为本地目录，自动递归搜索子目录
python -m summary_tool.cli /path/to/left_root -s cts,gts -o xts_summary.html

# 左侧为远程 URL（目录）
python -m summary_tool.cli https://example.com/reports -r -o remote_summary.html
```
- `-s`：不指定之目录，就会递归搜索所有的子目录下的test_result_failures_suite.html。
- `-r/--recursive`：在单列模式下强制递归搜索（可选，默认若左路径是目录且包含目标文件也会递归）。
- 输出默认 `xts_summary.html`（未指定 `-o` 时）。

---

### 双列模式（双参数）
双列模式同时提供左、右路径，用于两套报告的对比，生成差异报告。
```bash
# 本地目录对比
python -m summary_tool.cli /path/to/left_root /path/to/right_root -s cts,gts -o xts-diff_summary.html

# 本地文件对比（单个子目录）
python -m summary_tool.cli /path/to/left.html /path/to/right.html -o diff.html

# 远程 URL 对比
python -m summary_tool.cli https://example.com/left https://example.com/right -s sts -o remote_diff.html
```
- `-s`：不指定之目录，就会递归搜索所有的子目录下的test_result_failures_suite.html。
- 输出默认 `xts-diff_summary.html`（未指定 `-o` 时）。
- 若只提供左侧路径，则进入单列模式，上述示例可省略右侧参数。

---

### 使用已安装的 CLI 命令（若已执行 `pip install -e .`）
```bash
summary-tool -a path/to/first -b path/to/second -o reports
```

运行后会在指定的输出目录生成以下文件，
默认缓存文件输出目录tmp_diff_reports：
- `*_1.html`、`*_2.html`：原始文本的 HTML 展示
- `*-diff.html`：对比后的差异报告
项目根目录：
- `xts_summary.html`、`xts-diff_summary.html`：整体汇总页面

---

## 常见错误及解决办法
| 错误信息                     | 可能原因                         | 解决方案 |
|----------------------------|--------------------------------|----------|
| `ModuleNotFoundError: No module named 'xxx'` | 依赖未安装或虚拟环境不匹配 | 确认已在当前环境执行 `pip install -r requirements.txt`，或使用 `python -m venv venv && source venv/bin/activate` 再安装。 |
| `FileNotFoundError: [Errno 2] No such file or directory` | 提供的路径不存在或拼写错误 | 检查 `--source-a`、`--source-b` 参数，确保路径正确且文件可读。 |
| `UnicodeDecodeError` | 输入文件编码不是 UTF-8 | 在 `extractor.py` 中添加 `encoding='utf-8'`，或先将文件转换为 UTF-8 编码。 |
| `git status` 报 “detected dubious ownership” | 在容器中挂载的目录所有权不被 Git 认可 | 执行 `git config --global --add safe.directory <repo_path>`（已在项目根目录做过此设置）。 |
| 空的 diff 报告 | 两个输入的内容完全相同或提取阶段出错 | 打印 `extractor` 的日志（`utils.py` 中的 `logger`），确认文本已被正确读取。 |

---

## 开发 & 贡献

Continue CLI