spark-omnioperator-test-design-generator

name	spark-omnioperator-test-design-generator
description	为Spark OMNI优化算子生成标准化测试设计文档。触发关键词：OMNI算子测试设计、OMNI算子测试、OMNI测试设计文档、omnioperator test design、omni TableWrite/TableRead/Filter/HashAggregate/Sort/HashJoin/Window算子测试设计

Spark OmniOperator 优化算子 — 测试设计文档生成

为指定算子生成标准化测试设计文档，穷举所有测试点，每条用例必须独立、具体、可执行。

适用场景

本技能在以下场景下激活：

• 为 Spark OMNI 优化算子（TableWrite、TableRead、Filter、HashAggregate、Sort、HashJoin、Window 等）生成标准化测试设计文档
• 对 OMNI 算子进行系统性测试点穷举，覆盖数据类型、边界值、场景、性能、可靠性、兼容性等维度
• 按标准化模板输出测试设计 Markdown 文档

输出文件：{OperatorName}_Test_Design_Document.md 输出目录：当前工作目录下的{OperatorName}_Test_Design/

参考文件

references/ 和 templates/ 目录提供参考文件，执行过程中按需加载：

文件	用途	加载时机
data-type-reference.md	数据类型矩阵、边界值规范、数据插入规则	Step 4 边界值分析法时
test-type-reference.md	测试设计方法定义、四大测试类型规范	Step 5 生成其他测试类型时
test_design_document_template.md	目标设计文档模板	Step 3 生成文档框架时
算子速查卡（见下方映射表）	输入因子与场景速查	Step 4 等价类/场景法时

算子速查卡映射表（仅加载目标算子对应的文件）：

功能语义	速查卡文件
写入类	write_operator.md
扫描类	scan_operator.md
过滤投影类	filter_project_operator.md
聚合类	aggregate_operator.md
排序类	sort_operator.md
关联类	join_operator.md
窗口类	window_operator.md

执行协议（CRITICAL）

必须使用任务管理工具（todowrite 或 TaskCreate），在任务开始时创建并显示任务列表，随进度更新状态：

1. 收集算子信息
   1.1 获取源码路径（必须询问用户）
   1.2 扫描Spark源码（必须执行，不可跳过）
   1.3 提取详设文档信息
2. ⏸️ 用户确认算子信息（必须展示源码扫描结果）
3. 生成测试设计文档框架（前4章）
4. 生成功能测试点（6种测试设计方法）
5. 生成其他测试类型（性能/可靠性/兼容性）
6. 用例统计与自检
   6.1 自动统计用例数量（grep验证）
   6.2 执行检视清单（逐项grep验证）
7. ⏸️ 用户最终确认
8. 输出最终文档

状态更新规则：

• 开始执行时设为 in_progress
• 完成时设为 completed
• ⏸️ 标记表示需要用户审批的检查点，不可跳过

---

流程

Phase 1: 算子定位与信息收集

流程概览：接收用户输入 → 源码扫描 → 详设文档提取 → 用户确认。

Step 1: 收集算子信息（源码扫描 + 详设文档提取）

接收用户输入：算子名称、输出目录（默认当前工作目录）、开发详设文档路径

Spark源码扫描（必须执行，不可跳过）

⚠️ 开发详设文档可能遗漏实现细节，源码扫描是验证和补充信息的唯一可靠来源。

源码位置：Spark 和 Gluten 源码位于工作目录根路径下（即 {workspace-root}/spark/ 和 {workspace-root}/Gluten/）。扫描前先用 ls 确认目录存在，不存在时询问用户实际路径。禁止直接报告"本地无源码"而不尝试查找。

源码组件	扫描内容	扫描文件路径
原生算子实现	核心逻辑、输入验证、异常处理	{workspace-root}/spark/sql/core/src/main/scala/org/apache/spark/sql/execution/datasources/
Omni算子实现	与原生算子的差异、数据类型支持	{workspace-root}/Gluten/backends-omni/src/main/scala/org/apache/spark/sql/execution/datasources/
开关配置	配置项名称、默认值	{workspace-root}/Gluten/shims/common/src/main/scala/org/apache/gluten/config/GlutenConfig.scala
算子触发条件	触发/回退条件	{workspace-root}/Gluten/backends-omni/src/main/scala/org/apache/gluten/extension/columnar/offload/

扫描输出（缺失项标记"未找到"）：

• 原生算子类名及关键方法
• Omni算子类名及触发条件
• 开关配置项（命名模式：spark.omni.sql.columnar.{算子名} 或 spark.gluten.sql.columnar.{算子名}）
• 支持/不支持的数据类型列表
• 异常处理逻辑

开发详设文档提取：

从用户提供的开发详设文档中提取：

设计文档内容	提取要点	输出
算子功能描述	核心功能、设计目标、使用场景	测试范围定义
技术实现方案	算法选择、数据结构、关键流程	测试设计重点
边界条件说明	支持的输入范围、限制条件	边界值测试用例
性能优化点	优化策略、预期提升、影响因素	性能测试场景
已知问题	待解决问题、限制条件	风险规避测试

⚠️ 如果用户未提供详设文档，必须要求用户补充以下信息后方可继续：

• 算子核心功能与设计目标
• 支持的数据类型列表
• 已知限制与边界条件
• 性能优化策略（如有）

Step 2: ⏸️ 用户确认算子信息（强制检查点）

⚠️ 用户确认后方可进入 Phase 2，不可跳过。

按以下模板生成确认信息，通过AskUserQuestion的preview展示并确认：

📋 {算子名称} 信息确认

一、源码扫描结果

扫描项	扫描结果	来源文件
原生算子类名	{如 InsertIntoHadoopFsRelationCommand}	{文件路径}
Omni算子类名	{如 OmniInsertIntoHadoopFsRelationCommand}	{文件路径}
开关配置项	{如 spark.omni.sql.columnar.dataWritingCommand}	{文件路径}
开关默认值	{如 true}	{文件路径}
支持的数据类型	{源码中确认的类型列表}	{文件路径}
不支持的数据类型	{源码中确认的类型列表}	{文件路径}
异常处理逻辑	{触发异常的条件描述}	{文件路径}

二、详设文档提取结果

类别	项目	内容
基础定位	算子名称	{如 HashJoin}
基础定位	数据流向	{写入类 / 读取类}
基础定位	功能语义	{关联类 / 聚合类 / 排序类 / 过滤投影类 / 窗口类 / 写入类 / 扫描类 }
基础定位	Omni算子名称	{如 OmniHashJoinExec}
基础定位	开关配置	{如 spark.omni.sql.columnar.hashjoin}
基础定位	风险等级	{极高 / 高 / 中}
数据类型	支持的类型	{如 INT, LONG, DOUBLE, STRING, DATE, DECIMAL...}
数据类型	不支持的类型	{如 BINARY, MAP, STRUCT...}
数据类型	包含中文的类型	{如 STRING, CHAR, VARCHAR}
算子判断	支持类型→Omni算子出现	{如 OmniHashJoinExec}
算子判断	不支持类型→原生算子出现	{如 HashJoinExec}
算子特有	{按算子类型展示}	{如 Join类→INNER/LEFT OUTER/...; Agg类→SUM/AVG/...; Write类→INSERT INTO/OVERWRITE}
源码文档	Spark源码扫描	✅ 已完成 / ❌ 未完成
源码文档	开发详设文档	✅ 已提供 / ❌ 未提供

三、信息一致性检查

检查项	源码扫描结果	详设文档结果	速查卡结果	一致性
支持数据类型	{源码}	{详设}	{速查卡}	✅一致 / ❌不一致
不支持数据类型	{源码}	{详设}	{速查卡}	✅一致 / ❌不一致
开关配置	{源码}	{详设}	{速查卡}	✅一致 / ❌不一致

四、差异项处理（如有不一致）

差异项	源码结果	详设文档结果	速查卡结果	用户确认结果
{差异项1}	{内容}	{内容}	{内容}	{用户确认以哪个为准}

⚠️ 不一致处理规则：

1. 源码扫描结果 > 详设文档结果 > 速查卡结果（优先级从高到低）
2. 如有不一致项，必须列出差异并让用户确认以哪个为准
3. 速查卡中的数据类型列表可能包含通用配置，必须以详设文档或源码扫描结果为准

使用AskUserQuestion确认，选项提供"信息正确，继续"和"需要修正"（用户选"需要修正"时在Other中说明具体修正项）。

---

Phase 2: 生成测试设计文档

流程概览：生成文档框架 → 6种方法展开功能测试点 → 补充其他测试类型 → 自检 → 用户确认 → 输出。

Step 3: 生成测试设计文档框架（前4章）

读取模板，填充Phase 1确认的算子基础信息，生成测试设计文档前4章。

读取 test_design_document_template.md，按模板结构生成以下章节：

#	章节	核心内容	数据来源
1	概述	算子功能与测试范围	Phase 1 定位结果
2	算子签名	名称/数据流向/开关/重要性	Phase 1 定位结果
3	参考实现分析	原生算子/Omni算子/验证方法/SQL模式	Phase 1 + 算子速查卡
4	输入因子	因子编号/分类/名称/可选值/权重	算子速查卡

自检（必须执行grep验证并展示输出）：

⚠️ 读取参考文件 ≠ 执行检查。必须用grep命令验证并展示结果，禁止直接写结论。

• 算子签名与定位信息是否一致 → grep 验证算子名称/数据流向/开关配置
• 输入因子表是否完整 → grep 对比速查卡因子数量与文档中因子数量
• 参考实现分析是否准确 → grep 验证原生/Omni算子类名

Step 4: 生成功能测试点（6种测试设计方法）

按6种测试设计方法逐层展开功能测试点，每条用例必须独立、具体、可区分。

1. 等价类划分法（EC/IE）

1. 加载算子速查卡中对应算子的输入因子表
2. 对每个"极高"权重因子，按其可选值逐个生成有效等价类（EC）
3. 对每个"极高"权重因子，生成无效等价类（IE）：非法输入、不支持类型、异常配置
4. 对"高"权重因子，按核心取值生成有效等价类
5. 对"中"权重因子，生成关键有效等价类

2. 边界值分析法（BV）

1. 加载 data-type-reference.md 中数据类型矩阵
2. 对每种支持的数据类型，生成边界值用例：最小值/最大值/零值/接近边界值/NULL
3. ⚠️ CRITICAL：边界值用例禁止写具体数值，只写边界值描述
   • ✅ 正确示例：SHORT类型最小值写入、INT类型最大值写入、LONG类型零值写入
   • ❌ 错误示例：SHORT类型-32768写入、INT类型2147483647写入
4. 边界值描述格式：{数据类型}{边界值类型}写入，如 SHORT类型最小值写入

3. 场景法（SC）

1. 加载算子速查卡中对应算子的测试场景清单
2. 将每个场景编号展开为独立测试点
3. 补充异常流程场景

4. 判定表法（DT）

1. 识别多条件组合场景
2. 列出所有条件取值组合

5. 正交试验法（OA）

1. 选取"极高×极高"因子对，生成2-wise核心组合
2. 选取"极高×极高×高"因子组合，生成3-wise高风险组合

6. 错误推测法（EG）

1. 补充易错场景：类型溢出、空值处理、并发冲突、精度丢失等

自检（必须执行grep验证并展示输出）：

⚠️ 读取参考文件 ≠ 执行检查。必须用grep命令验证并展示结果，禁止直接写结论。

• 6种方法是否都已覆盖 → grep -c "^| EC-\|^| IE-" / grep -c "^| BV-" / grep -c "^| SC-" / grep -c "^| DT-" / grep -c "^| OA-" / grep -c "^| EG-"
• 每种数据类型是否逐条展开（非合并为"各数据类型测试"）→ grep 检查是否存在"各数据类型"合并写法
• 边界值是否只写描述未写具体数值 → grep "^| BV-.*[0-9]\{4,\}" 有输出则需修正
• 是否存在范围合并编号（如"054-065 异常分支测试"）→ grep "[0-9]\{3\}-[0-9]\{3\}" 检查

注意：本步骤自检的是第五章（测试设计方法）的展开是否完整，最终输出到第六章（功能测试点）时需要按"合并原则"进行精简。

Step 5: 生成其他测试类型（性能/可靠性/兼容性）

在功能测试点基础上，补充性能、可靠性、兼容性测试点。

1. 性能测试：按 test-type-reference.md 性能测试节生成，重点覆盖TPC-DS场景、数据量级、数据类型下的端到端耗时对比
2. 可靠性测试：按 test-type-reference.md 可靠性测试节生成，覆盖异常输入、资源限制、并发等场景
3. 兼容性测试：按 test-type-reference.md 兼容性测试节生成，覆盖Spark版本、数据源、部署模式等维度

自检（必须执行grep验证并展示输出）：

⚠️ 读取参考文件 ≠ 执行检查。必须用grep命令验证并展示结果，禁止直接写结论。

• 三大测试类型是否都有规划 → grep -c "^| P-" / grep -c "^| R-" / grep -c "^| C-" 均大于0
• 各维度是否逐条展开 → grep 检查是否存在合并写法
• 性能测试是否包含TPC-DS场景 → grep "TPC-DS" 检查

Step 6: 用例统计与自检

汇总用例统计，使用参考文档进行自检。

用例统计（必须自动统计）：

⚠️ CRITICAL：必须通过脚本或工具自动统计用例数量，禁止人工计数，避免统计错误。

统计维度：

1. 按测试设计方法统计：等价类、边界值、场景法、判定表、正交试验、错误推测各多少条
2. 按测试类型统计：功能、性能、可靠性、兼容性各多少条
3. 按Level统计：Level0、Level1、Level2各多少条
4. 总计：总用例数

统计方法：

• 使用 grep 等工具统计各章节的用例编号数量
• 验证统计结果与实际生成的用例数量一致
• 在文档中输出统计结果

自检清单（必须逐项执行）：

⚠️ CRITICAL：必须加载检视文档并逐项检查，记录检查结果。

检视项	检视文档	检视内容	检查方法
数据类型覆盖	data-type-checklist.md	支持类型是否逐类型展开？不支持类型回退是否覆盖？边界值是否覆盖？	加载检视文档，逐项勾选
算子场景覆盖	算子速查卡	速查卡中每个场景编号是否都有对应测试点？Level0是否100%覆盖？	对比速查卡场景编号与生成的测试点
测试类型覆盖	test-type-checklist.md	四大测试类型是否都有规划？各维度是否逐条展开？	加载检视文档，逐项勾选
穷举完整性	—	第五章是否存在范围合并编号？每条是否独立可区分？第六章是否按合并原则精简？	检查编号连续性和合并规则
边界值格式	—	边界值用例是否只写描述未写具体数值？	检查边界值用例是否包含数字

自检执行步骤（必须执行命令并展示输出）：

⚠️ CRITICAL：每一步都必须执行指定的 grep/bash 命令并展示输出。禁止跳过任何步骤，禁止直接写"✅通过"而不执行命令。

1. 用例数量统计：执行以下命令并展示输出

   • grep -c "^| T-" {文档} / grep -c "^| P-" / grep -c "^| R-" / grep -c "^| C-"
   • grep "^| T-.*Level0" {文档} | wc -l / Level1 / Level2
   • 根据统计结果写入文档 7.1/7.2 节，然后再次 grep 验证写入的数据与实际用例数一致

2. 场景覆盖验证：对比速查卡 W-xxx 与文档测试点

   • grep "^| W-" {速查卡} | awk -F'|' '{print $2}' 提取速查卡场景编号
   • grep "场景法" {文档} | grep -o "SC-[0-9]*" | sort -u 提取文档覆盖的场景
   • 逐一对比每个 W-xxx 是否有对应测试点，未覆盖的必须补充

3. 边界值格式检查：

   • grep "^| BV-.*[0-9]{4,}" {文档} → 有输出则说明包含具体数值，必须修正为描述格式

4. 数据类型/测试类型检视：重新加载 checklist 文件逐项勾选（读取 ≠ 检查）

5. 生成自检报告：将以上命令输出和检查结果写入文档 7.4 节，格式：

   • 用例统计验证表（grep结果 vs 文档记录）
   • 场景覆盖验证表（速查卡编号 vs 测试点）
   • 检视清单执行结果
   • 问题汇总及修正记录

Step 7: ⏸️ 用户最终确认（强制检查点）

使用 AskUserQuestion 进行最终确认，不可直接输出最终文件。

⚠️ 用户确认后才可输出最终文件。如需修改，先修改再重新确认。

📋 {OperatorName} 测试设计文档已生成，请确认：

【算子定位】{OperatorName} → {数据流向} / {功能语义} / 风险等级：{Level}
【用例规划】
  - 功能测试：XX条（Level0:XX, Level1:XX, Level2:XX）
  - 性能测试：XX条（Level0:XX, Level1:XX）
  - 可靠性测试：XX条（Level0:XX, Level1:XX）
  - 兼容性测试：XX条（Level0:XX, Level1:XX）
  - 总计：XX条

【自检摘要】
  - 用例统计：grep验证 功能XX+性能XX+可靠性XX+兼容性XX=XX ✅/❌
  - 场景覆盖：Level0 XX/XX ✅/❌ / Level1 XX/XX ✅/❌
  - 边界值格式：无具体数值 ✅/❌
  - 完整自检报告见文档 7.4 节

如需调整请告知，确认后将输出最终文档。

Step 8: 输出最终文档

用户在 Step 7 确认后，将完整测试设计文档写入输出目录。

输出文件：{OperatorName}_Test_Design/{OperatorName}_Test_Design_Document.md

---

重要约束

约束项	说明
逐条罗列（第五章）	测试设计方法每条用例独占一行，禁止范围合并写法
具体可区分	去掉类型/模式标记后，步骤仍能与其他用例区分
边界值不写具体数值	边界值用例只写描述不写具体数值，如"SHORT类型最小值写入"而非"SHORT类型-32768写入"
不写SQL语句	测试设计文档只写测试点，不写具体SQL实现
数据类型展开（第五章）	支持的每种数据类型各一条用例，不合并
合并精简（第六章）	边界值合并到数据类型，错误推测作为覆盖因子
用例统计自动统计	必须使用工具自动统计用例数量，禁止人工计数
覆盖因子格式统一	格式：主方法-具体点 | 次方法-具体点
检视清单必须执行	必须加载并执行data-type-checklist.md和test-type-checklist.md
自检必须执行工具	禁止直接写结论，必须执行grep/bash命令并展示输出

输出格式规范

用例命名

• 格式：{算子名}_{场景描述}，如 TableWrite_支持BOOLEAN类型写入
• 自检：去掉类型/模式标记后，步骤仍能与其他用例区分

测试范围

• 具体可执行，包含测试数据：BOOLEAN类型(true/false/null)写入→SELECT验证结果正确

覆盖因子

⚠️ CRITICAL：覆盖因子格式必须统一，便于追溯和验证。

格式规范：

• 主要覆盖因子放在前面，次要覆盖因子作为补充
• 格式：主方法-具体点 | 次方法-具体点
• 示例：等价类-BOOLEAN | 边界值-true/false | 场景法-支持类型写入

覆盖因子类型：

1. 等价类-{因子名}：等价类划分法覆盖的因子
2. 边界值-{边界类型}：边界值分析法覆盖的边界（如：最小值、最大值、零值）
3. 场景法-{场景名}：场景法覆盖的场景
4. 判定表-{条件组合}：判定表法覆盖的条件组合
5. 正交试验-{因子组合}：正交试验法覆盖的因子组合
6. 错误推测-{易错场景}：错误推测法覆盖的易错场景

自检：

• 覆盖因子是否与第五章的测试设计方法对应
• 覆盖因子是否完整反映了该用例的测试点

合并原则

• 边界值 → 合并到对应数据类型测试，不单独列
• 错误推测 → 不作为独立用例，作为覆盖因子
• 判定表/正交 → 场景化，作为覆盖因子