dolphindb-test

name	dolphindb-test
description	dolphindb 测试方案、测试文档及测试用例生成；用户提到“测试用例”或“测试文档”时触发；测试脚本使用 `.txt`后缀
argument-hint	testddb
user-invocable	true
disable-model-invocation	false

DolphinDB 测试方案和用例生成

1. 目标

• 为 DolphinDB 的计算函数、SQL 语句、存储引擎、流引擎、插件等功能生成测试方案和完整测试用例。
• 生成结果应符合现有项目风格，测试脚本通常使用 .txt 后缀。
• 先确认信息和规则来源，再生成内容。
• 除非用户明确要求“草案 / 骨架 / 代表性用例 / 主干用例”，否则默认输出完整版测试方案和完整版测试用例，不得降级为概括性结果。

2. 输入信息（不全就先追问）

• 待测对象：函数名 / SQL / 模块名。
• 设计文档：用户提供路径，或明确“无”。
• 测试文档：用户提供路径（若已提供则直接用于生成测试用例）。
• 输出路径：目标目录。

若信息不足，继续追问，直到能唯一定位函数并确定生成规则。

3. 执行流程（按顺序）

步骤 1：确认设计文档

• 先确认用户是否已提供设计文档。
• 已提供：先读取并提炼规则。
• 未提供：在参考文档 中查找是否存在函数对应文档
• 若两者都没有：先不要输出，向用户确认接口用法
• 若用户已提供测试文档（测试场景文档/测试要点文档），则直接进入“步骤 6：生成测试用例”；步骤 2-5 改为按需校验，不作为阻塞前置。

步骤 2：理解待测对象行为

• 读取完整待测对象实现，判断待测对象属于计算函数、SQL、存储引擎、流引擎、插件中的哪一类。
• 判断各个参数之间是否存在依赖关系，用于后续的测试场景设计（如参数间的依赖关系、排序、分区、键值列等）。
• 明确输入类型、返回值、异常条件、副作用和隐含约束。
• 思考是否有其他语言或系统中类似功能的测试可以参考。
• 不清楚时先补读调用方或现有测试，禁止猜测。

步骤 3：参考既有测试

• 根据步骤 2 的判断，在 代码示例 模块中查找相关测试。
• 优先参考：同名函数旧测试、同模块测试、同类型函数测试模板。
• 提炼命名、断言、数据准备、异常校验模式。

步骤 4：设计覆盖场景

• 先列出要覆盖的场景，并按“异常场景在前、正常场景在后”的固定顺序组织。
• 测试要点清单中的每一条都必须在场景设计阶段映射为至少一个原子场景；若某条无法落地，必须标记原因并列入“待确认项”，不得静默省略。
• 将测试要点拆成“不可再拆”的原子场景。禁止把多个异常测试点写到一个场景里；每个场景只验证一个明确行为。
• 在开始设计任何正常场景前，必须先列完全部异常场景；异常场景与正常场景不得交错排列。
• 生成测试用例前，必须先在内部完成“参数-类型-结构-值域-联动约束”覆盖矩阵；若该矩阵未完成，不得输出最终测试用例。
• 若部分行为文档未明确：

1. 对文档已能确认的非法输入、边界输入、支持输入，照常生成完整用例。
2. 对无法确认预期的行为，单列“待确认项”。
3. 不得因为局部不确定而省略其他已知应覆盖场景。

• 若待测对象属于计算函数

1. 获取函数使用说明并判断函数类型（标量函数、聚合函数、窗口函数、序列函数等）。
2. 列出测试要点，遵循以下步骤：（1）参数数量校验（2）对每一个参数逐一列出异常情况，包括NULL、数据类型错误、数据形式错误、不满足设计文档的输入（3）正确性用例，对每一个参数逐一列出正确性场景，对函数整体列出正确性场景（4）参考计算函数测试要点，列出上面三步遗漏的要点
3. 若待测对象参数涉及表，则应考虑所有内存表（包括share后的内存表）以及分布式表（包括OLAP、TSDB、PKEY、IOTDB等引擎）
4. 判断是否支持在流引擎或分布式表中使用，如果不支持则输出异常用例，否则输出正确性用例。
5. 需要测试性能，如果在其他语言中有类似函数，写出性能对比脚本；如果没有，写出DolphinDB 的性能测试脚本；要求测试数据量为100,1w,100w 。

• 若部分行为文档未明确：

1. 对文档已能确认的非法输入、边界输入、支持输入，照常生成完整用例。
2. 对无法确认预期的行为，单列“待确认项”。
3. 不得因为局部不确定而省略其他已知应覆盖场景。

• 若待测对象属于SQL

1. 对每一个参数列出异常要点
2. 对每一个参数列出正确性要点
3. 结合SQL测试要点列出其他要点
4. 若待测对象参数涉及表，则应考虑所有内存表（包括share后的内存表）以及分布式表（包括OLAP、TSDB、PKEY、IOTDB等引擎）
5. 对涉及到的分布式表参考存储引擎测试要点列出其他要点

• 若待测对象属于插件

1. 判断属于格式处理、行情、机器学习、扩展接口、数据存取、数值计算、图像、网络、消息队列、云存储中的哪一类
2. 根据插件类型，参考在 代码示例 模块中相应的测试用例
3. 列出测试要点，遵循以下步骤：（1）参数数量校验（2）对每一个参数逐一列出异常情况，包括NULL、数据类型错误、数据形式错误、不满足设计文档的输入（3）正确性用例，对每一个参数逐一列出正确性场景，对函数整体列出正确性场景（4）参考插件测试要点，列出上面三步遗漏的要点

步骤 5：生成测试场景文档

• 若用户已提供可用测试文档，跳过本步骤。
• 若用户指定了路径，就在规定路径下生成
• 若没有指定路径，默认在当前路径下生成 test_doc_xxx.txt
• 测试场景文档格式参考references/test_docs/arima_test_doc.md
• 测试场景文档中的场景输出顺序固定为：先完整列出全部异常场景，再完整列出全部正常场景；不得交错排列。
• 若用户提供的测试文档原始顺序不是“异常在前、正常在后”，生成测试用例前应先在内部重排或分组映射，并按异常优先顺序输出最终测试文档/测试用例。

步骤 6：生成测试用例

必须基于“步骤 5 已生成的测试文档”或“用户已提供的测试文档”，按场景逐项生成 @testing:case 块。

• 当用户已提供测试文档时，优先直接使用该文档生成测试用例，不要求先完成步骤 4/5。

• 当用户已提供测试文档时，测试文档中的每一个场景都必须写出至少一个对应测试用例；不得只挑选部分场景生成，也不得把多个独立场景合并成一个概括性 case。

• 若测试文档中的某个场景还能进一步拆成多个原子行为，则必须继续拆分并为每个原子行为分别写 case；但无论是否拆分，原始场景本身不得遗漏，必须在覆盖映射中能追踪到至少一个已生成用例。

• @testing:case 命名格式为 test_<测试对象>_<场景>。

• @testing:case 名称中的 <场景> 必须写成可读的测试场景描述，直接体现被验证的行为/条件/预期，不得仅使用 point_id、编号或其简单拼接作为场景名。

• 若测试文档中存在 point_id（如 MCBL_N01），该编号只用于内部覆盖映射和核对，不得作为最终 case 名主体；默认不要输出形如 test_xxx_MCBL_N01、test_xxx_SECBL_N03 的名称。

• 若确需保留编号用于追踪，必须采用“场景名优先、编号次要”的形式，且场景名不可省略；例如 test_context_by_limit_offset_olap_cross_partition_pagination，而不是 test_context_by_limit_offset_olap_MCBL_N01。

• 当用户文档存在无编号/编号不全/编号重复时，先完成内部唯一编号重建，再建立覆盖映射并生成 case。

• 生成前先建立“测试要点清单 -> case 名称”映射表；每个测试要点条目至少映射一个 case。

• 生成后做覆盖核对：已覆盖测试要点数 == 测试要点总数 才允许输出“最终完整版测试用例”。

• 输出顺序必须固定：先完整输出全部异常用例，再完整输出全部正常用例；在任一正常用例开始前，不得夹杂未输出的异常用例。

• 异常用例包括但不限于：参数个数错误、语法错误、NULL、非法数据类型、非法数据形式、非法取值、长度不匹配、类型不匹配、环境/引擎/表类型不支持、联动约束不满足。

• 只有当全部异常场景都已写完并完成覆盖核对后，才可开始编写正常路径与正确性用例。

• 需要异常校验时，添加 exception=1。

• 预期语法错误,比如参数个数少于预期，添加 syntaxError=1。

• 覆盖参数个数错误。

• 覆盖异常路径。

• 覆盖边界情况（如空向量、空表、NULL、极值、单元素输入）。

• 覆盖正常路径。

• 对接口每一个参数，必须覆盖 数据类型 中涉及的所有数据类型（包括 NULL） 和数据结构。对于不支持的类型分别输出异常用例，对 于支持的类型要测试所有支持的数据类型x数据形式的组合。

• 覆盖类型相关主要分支（如标量、向量、矩阵、表、字典）；是否全部覆盖取决于函数语义。

• 若测试方案对新增计算函数有额外要求，补充流计算支持、性能或 SQL 相关覆盖。

• 若行为依赖排序、分区、键值列、时间类型或 Decimal/Integral 精度，必须显式覆盖这些差异。

• 对每个参数，凡设计文档或参考样例中能识别出的非法类型、非法数据形式、空值形式、长度不匹配、类型不匹配、取值越界、重载差异，都应分别生成独立 case，不得用一个 case 代替一组类型。

• 对涉及表、分布式表、共享表、流表、分区表的参数，若文档未明确排除，默认分别考虑并生成对应 case；若不支持，则写异常用例。

• 默认生成完整版测试用例，不遗漏场景4或上下文中设计的任何一个测试点，不生成概括性草案。

• 只要输入中存在测试文档（测试场景文档/测试要点文档），最终输出的测试用例必须做到“文档场景全覆盖”；若有任一场景未写出用例，则不得声称已完成或已生成最终版。

• 除非用户明确要求缩减覆盖，否则禁止使用“先给一版主干用例 / 先给代表性用例 / 先给骨架后续补充”的策略。

• 若当前结果仍有任一参数未完成 NULL、类型错误、结构错误、非法取值、联动约束的独立覆盖，则不得将其作为最终测试用例输出。

• 若不清楚用法，先去参考文档 中找示例，不要直接猜测。

• 若无法生成完整版测试用例，允许的输出只能是：

1. 缺失信息列表
2. 已完成的覆盖矩阵
3. 测试要点清单及当前覆盖状态（标明未覆盖条目）
4. 待确认项 不得将不完整 case 集合作为最终结果输出。

步骤 7：结果说明

输出给用户时应明确：

• 是否提供了设计文档，以及实际采用了哪套规则。
• 是否由用户直接提供了测试文档，以及是否走了“直接生成测试用例”路径。
• 读取了哪个函数文件。
• 参考了哪些现有测试目录、文件或 PDF 文档。
• 新测试写到了哪里。
• 若输出的是最终测试用例，应明确说明其为“完整版”还是“因缺失信息未完成最终输出”。

4. 编写规范

• 用例名使用 test_<函数名>_<场景>。
• 断言写法优先与参考目录中的既有测试保持一致。
• 用例输出顺序固定为：先异常用例，后正常用例；异常区段必须一次性写完，不得与正常用例交错。- 单个用例只验证一个明确行为。
• 单个用例只验证一个明确行为。
• 数据准备保持最小化，避免无关噪声。
• 只生成与当前函数直接相关的测试，不顺带修改无关测试。
• 构造用例时使用 参考文档 中已有语法，不使用臆造语法。
• 如果搜索到相同函数的示例或用例，不要从这些示例或用例中推断行为。
• 严格按照函数说明或设计文档编写测试，目标是发现问题而不是使断言通过。
• 断言涉及元组对比时，按下标逐项对比，不要直接对比整个结果。
• 尽量使用英文注释。
• 不要在自定义函数里嵌套定义函数
• 除非用户明确要求缩减覆盖，否则不要用“代表性用例”替代参数枚举型用例。
• 本 skill 属于穷举测试生成任务，不适用常规工程任务中的“最小可用集、主干用例、骨架用例、后续补充覆盖”策略。

5. 约束与禁止项

• 严禁删除工作空间下的任何文件。
• 不要默认修改工作空间下的原始测试文件。
• 不要跳过“是否已输入设计文档”的确认步骤。
• 不要忽略默认测试方案文件 如何编写DolphinDB测试用例，除非用户明确要求不用它。
• 不要省略异常和边界场景，除非函数语义明确不需要。
• 不要臆造函数行为；不确定时先读代码再写测试。
• 不要使用 参考文档 中没有的数据类型、数据形式或函数。
• 不要输出与项目现有风格明显不一致的测试结构。
• 不要将不完整的 case 集合表述为“完整测试用例”或“最终测试用例”。
• 不要用一个异常 case 代替一组不同类型或不同数据形式的非法输入，除非用户明确要求合并。
• 不要把 point_id 直接当作 @testing:case 的场景名；禁止默认生成 test_<对象>_<point_id> 这类仅编号命名。

6. 代码示例

计算函数用例示例

函数类型	参考文件
标量函数	标量函数测试用例
序列函数	序列函数测试用例
cum 系列函数	cum 函数测试用例
m 系列函数	m 函数测试用例
tm 系列函数	tm 函数测试用例
row 系列函数	row 函数测试用例
一元聚合函数	一元聚合函数测试用例
二元聚合函数	二元聚合函数测试用例
在timeSeriesEngine中使用	流引擎测试用例
在dailyTimeSeriesEngine中使用	流引擎测试用例
在crossSectionalEngine中使用	流引擎测试用例
在reactiveEngine中使用	所有匹配 examples/streaming_test_case/test_function_createReactiveStateEngine_*.txt 的文件
流引擎snapshot	所有匹配 examples/streaming_test_case/*snapshot*.txt 的文件

SQL 语句用例示例

• SQL 作用于内存表或磁盘表：参考 内存sql测试用例
• SQL 作用于 tsdb 分布式表：参考 tsdb测试用例
• SQL 作用于 olap 分布式表：参考 olap测试用例
• SQL 作用于 pkey 分布式表：参考 pkey测试用例
• SQL 作用于 iotdb 分布式表：参考 iotdb测试用例

存储引擎用例示例

参考 存储引擎测试用例

流引擎用例示例

参考 流引擎测试用例

插件测试用例示例

参考 格式处理插件测试用例 参考 行情插件测试用例 参考 机器学习插件测试用例 参考 扩展接口插件测试用例 参考 数据存取插件测试用例 参考 数值计算插件测试用例 参考 图像插件测试用例 参考 网络插件测试用例 参考 消息队列插件测试用例 参考 云存储插件测试用例

CLASS测试用例示例

参考 CLASS测试用例

8. 生成前自检

生成测试方案或用例前，逐项检查：

• 是否明确设计文档来源和测试要点来源。
• 是否对测试要点文档中的每一条测试要点完成了逐条编号与覆盖登记（对无编号/编号不全/编号重复的文档，是否已完成内部唯一编号重建）。
• 是否存在未映射到 case 的测试要点条目（若存在则不能输出最终版）。
• 是否完成参数-类型-结构-值域四维覆盖映射。
• 是否包含异常与语法异常场景。
• 是否覆盖关键联动约束（多参数关系、排序、精度、分区等）。
• 是否避免从历史用例反向推断语义。
• 是否遵循 references/test_docs/how_to_generate_dolphindb_test_case.md。
• 是否将每一个测试要点落实为独立 case，而不是合并成概括性 case。
• 是否逐一检查了每个参数的 NULL、类型错误、结构错误、空值构造、长度不匹配、重载差异、环境差异。
• 是否覆盖了函数的所有调用形式，而不是只覆盖一个签名。
• 是否生成完整版测试要点或测试用例，而不是概括性草案。
• 是否每个参数都单独覆盖了 NULL。
• 是否每个参数都单独覆盖了非法数据类型。
• 是否每个参数都单独覆盖了非法数据形式。
• 是否每个参数都单独覆盖了文档可识别的非法取值。
• 是否每个多参数联动约束都拆成独立 case。
• 是否不存在“一个 case 代表一组非法类型”的情况。
• 是否对表参数分别考虑了内存表、共享表、分布式表。
• 若以上任一项答案为“否”，不得输出最终完整版测试用例。

9. 参考文档

• 完整文档索引：见 CATALOG.md