generate_excel.py 使用说明

概述

generate_excel.py 是一个灵活的 Excel 报告生成工具，用于创建 CRM E2E 测试 SOP 文档。该脚本支持通过命令行参数自定义各种配置，避免了硬编码常量。

安装依赖

# 激活虚拟环境（如果有的话）
source .venv/bin/activate

# 安装依赖
pip install -r requirements.txt

基本用法

1. 从 Markdown 文件自动生成（推荐）

python generate_excel.py --markdown sop-003-product-creation-e2e.md

这将自动从 SOP markdown 文档中提取任务表格，生成 Excel 文件。

优势： - ✅ 自动化程度高，无需手动维护数据 - ✅ 保持文档和 Excel 的一致性 - ✅ 支持任意多个任务和步骤 - ✅ 自动识别任务标题、前置条件和表格数据

2. 使用默认参数（硬编码数据）

python generate_excel.py

这将生成默认配置的 Excel 文件： - 文件名：CRM产品创建E2E测试SOP_YYYYMMDD_HHMMSS.xlsx - 基础 URL：http://localhost:3000/crm - 截图目录：screenshots/ - 使用内置的产品创建测试数据

3. 查看帮助信息

python generate_excel.py --help

参数说明

输入参数

参数	简写	默认值	说明
`--markdown`	`-m`	无	从 markdown 文件读取任务数据（推荐使用）

基础参数

参数	简写	默认值	说明
`--output-prefix`	`-o`	`CRM产品创建E2E测试SOP`	输出文件名前缀
`--base-url`	`-u`	`http://localhost:3000/crm`	测试系统的基础 URL
`--screenshot-dir`	`-s`	`screenshots`	截图存放目录

样式参数

参数	默认值	说明
`--header-color`	`#4472C4`	表头背景色（十六进制颜色代码）
`--title-font-size`	`14`	标题字体大小
`--checkbox-font-size`	`16`	复选框字体大小

图片参数

参数	默认值	说明
`--with-screenshots`	`False`	生成截图列（默认不生成，添加此参数启用截图列）
`--image-scale-x`	`0.225`	图片横向缩放比例（仅在启用截图时生效）
`--image-scale-y`	`0.22`	图片纵向缩放比例（仅在启用截图时生效）
`--row-height`	`80`	包含图片的行高（仅在启用截图时生效）

使用示例

示例 1：从 Markdown 生成（最常用）

python generate_excel.py --markdown sop-003-product-creation-e2e.md

自动提取 markdown 中的任务表格，生成完整的 Excel 测试报告。

示例 2：从 Markdown 生成并自定义配置

python generate_excel.py \
  --markdown sop-003-product-creation-e2e.md \
  --output-prefix "产品测试报告" \
  --base-url "https://test.example.com/crm" \
  --screenshot-dir "test_screenshots"

示例 3：批量生成不同 SOP 的 Excel

# 客户创建 SOP
python generate_excel.py -m sop-001-customer-creation-e2e.md -o "客户创建测试"

# 产品创建 SOP
python generate_excel.py -m sop-003-product-creation-e2e.md -o "产品创建测试"

# 政策标签 SOP
python generate_excel.py -m sop-101-policy-label-create.md -o "政策标签测试"

示例 4：修改输出文件名和 URL（不使用 Markdown）

python generate_excel.py \
  --output-prefix "CRM订单测试SOP" \
  --base-url "http://192.168.1.100:3000/crm"

生成文件：CRM订单测试SOP_20251222_143022.xlsx

示例 5：使用不同的截图目录

python generate_excel.py \
  --markdown sop-003-product-creation-e2e.md \
  --screenshot-dir "my_screenshots"

脚本将在 my_screenshots/ 目录中查找截图文件。

示例 6：自定义样式

python generate_excel.py \
  --markdown sop-003-product-creation-e2e.md \
  --header-color "#FF5733" \
  --title-font-size 16 \
  --checkbox-font-size 18

示例 7：调整图片显示

python generate_excel.py \
  --markdown sop-003-product-creation-e2e.md \
  --image-scale-x 0.3 \
  --image-scale-y 0.3 \
  --row-height 100

图片会更大，行高也相应增加。

示例 8：生成生产环境测试报告

python generate_excel.py \
  --markdown sop-003-product-creation-e2e.md \
  --output-prefix "生产环境测试报告" \
  --base-url "https://crm.example.com" \
  --screenshot-dir "prod_screenshots" \
  --header-color "#2E7D32"

示例 9：包含截图列

python generate_excel.py \
  --markdown sop-101-policy-label-create.md \
  --output-prefix "政策标签测试" \
  --with-screenshots

这将生成一个包含截图列的 Excel，可以嵌入测试截图。注意：默认不生成截图列，需要添加 --with-screenshots 参数才会包含。

示例 10：组合所有参数

python generate_excel.py \
  -m sop-003-product-creation-e2e.md \
  -o "UAT测试SOP" \
  -u "https://uat.example.com/crm" \
  -s "uat_screenshots" \
  --header-color "#1976D2" \
  --title-font-size 15 \
  --row-height 90

输出说明

脚本执行成功后会：

在当前目录生成带时间戳的 Excel 文件
显示文件路径和生成信息
提示复选框使用方法
说明超链接跳转功能
提醒截图文件的放置位置

Markdown 文件格式要求

如果使用 --markdown 参数从 Markdown 文件读取数据，文件需要遵循以下格式：

任务标题格式

### 任务 T1：环境与账号验证

入口：`http://localhost:3000/crm`

或

### 任务 T2：新建产品 UI 操作

前置条件：T1 成功且当前在产品列表

表格格式

| Action Steps | Input / Payload | 预期结果 | 验证方式 | 证据 | 状态 | 下游任务 |
|--------------|----------------|----------|----------|------|------|----------|
| 步骤1：打开浏览器 | — | 浏览器启动成功 | 浏览器窗口打开 | 屏幕截图 | `[ ]` | 步骤 2 |
| 步骤2：输入 URL | `http://localhost:3000/crm` | 页面开始加载 | 地址栏显示正确 URL | 屏幕截图 | `[ ]` | 步骤 3 |

要求： - 任务标题必须以 ### 任务 T{编号}： 开头 - 表格必须包含至少 7 列 - 表格紧跟在任务标题或前置条件之后

自动处理： - 脚本会自动移除 markdown 代码标记（`） - 自动生成截图路径：{screenshot_dir}/T{任务编号}-step{步骤编号}.png - 支持中文冒号（：）和英文冒号（:）

注意事项

截图列默认不生成：从版本 3.1 开始，默认不生成截图列，表格更简洁
如需截图列，添加 --with-screenshots 参数
示例：python generate_excel.py -m sop-003.md --with-screenshots
截图路径：（仅在使用 --with-screenshots 时）确保截图文件按照命名规则放置在指定目录中
使用 markdown 输入时：T{任务编号}-step{步骤编号}.png
使用默认数据时：T{任务编号}-step{步骤编号}-{描述}.png
例如：T1-step1.png 或 T1-step1-browser.png
颜色代码：使用十六进制颜色代码（如 #4472C4）
缩放比例：（仅在使用 --with-screenshots 时）根据实际截图大小调整 image-scale-x 和 image-scale-y
值越大，图片显示越大
建议范围：0.1 - 0.5
行高：（仅在使用 --with-screenshots 时）如果图片显示不完整，增加 --row-height 参数
Markdown 文件：参考项目中现有的 SOP 文档格式（如 sop-003-product-creation-e2e.md）

故障排除

问题 1：ModuleNotFoundError: No module named 'xlsxwriter'

解决方案：安装依赖

pip install xlsxwriter
# 或
pip install -r requirements.txt

问题 2：图片无法加载

解决方案： 1. 检查截图文件是否存在 2. 确认路径是否正确 3. 验证文件名是否匹配

问题 3：颜色显示不正确

解决方案：确保使用正确的十六进制颜色代码格式： - 正确：#4472C4 - 错误：4472C4、#44C

高级用法

批量生成不同环境的报告

# 开发环境
python generate_excel.py -o "DEV测试" -u "http://localhost:3000/crm"

# 测试环境
python generate_excel.py -o "TEST测试" -u "http://test.example.com/crm"

# 生产环境
python generate_excel.py -o "PROD测试" -u "https://prod.example.com/crm"

创建自定义样式的报告

# 深色主题
python generate_excel.py \
  --header-color "#263238" \
  --title-font-size 16

# 彩色主题
python generate_excel.py \
  --header-color "#E91E63" \
  --title-font-size 15 \
  --checkbox-font-size 18

参考资源

反馈与贡献

如有问题或建议，请联系项目维护者。

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search