CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

fastgpt-integration-test-case

为 FastGPT 生成、维护或合并去重按业务归档的集成测试用例 Markdown,以一个业务验收目标覆盖多个相关场景,支持接口、UI、端到端和服务集成测试及单页阅读器。不用于单独编写 Vitest 测试或系统升级迁移用例。

Quality

81%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

FastGPT 集成测试用例

生成可由测试人员或自动化执行方复现的用例,存放于仓库根目录 .agents/test/。默认交付用例文档,不执行真实业务操作,也不自动转换为测试代码。已有脚本优先复用并声明覆盖,用户同时要求执行或自动化时,沿用其授权、环境和测试范围。

需要筛选并实际执行已有用例、逐项记录临时 HTML 报告时,使用 用例执行 skill。

系统升级迁移、历史回填和升级脚本恢复不归入业务集成用例库,由迁移代码旁的 Vitest / 数据库专项测试验证,不为其新增 .agents/test/ 用例或 test:cases 脚本。正常业务接口的旧数据兼容仍按业务行为保留。

用例统一面向本地 dev 环境及其已配置服务,不要求新建独立应用实例、Mongo、Redis 或专用数据库。通过本轮新建团队、应用和记录的明确 ID 清单隔离测试数据,按清单清理,不清空共享开发库或改动无关数据。

业务与目录

先读取仓库 AGENTS.md、.agents/code/syntax.md 和 业务分类。该 JSON 登记已确认的分类名称和路径,阅读器与查询工具直接读取它;分类可随业务需求扩展。

  • 路径为 .agents/test/<业务域>/<子业务>/<可选细分>/<ID>-<业务目标>.md,业务目录最多 3 层;每级直接子业务最多 3 个。按业务规则组织最小且可维护的用例集合,不为尚无用例的分类创建空目录。
  • 应用包括 app/workflow、app/agentv2、app/agent。共享的应用管理用例可直接放 app/,使用 tags 说明适用类型;类型间行为不同时拆开。
  • 模型分管理和使用;工具分系统插件和系统工具;权限用例归 permission;数据库、存储、缓存、队列、沙箱等基础设施集成归 infra。
  • 按主要验收目标确定唯一归属。例如工作流节点调用沙箱归应用执行,沙箱资源隔离本身归 infra。其他业务用 tags、related 和 sources 关联,不复制相同用例。
  • 生成用例时先按实际业务目标判断现有分类是否合适,优先复用语义匹配的分类,不为符合现有目录而强行归类。没有合适分类时,说明原因,给出建议分类名称、路径和目录树,询问用户是否新建或调整分类。确认前暂缓受影响用例的归档,其他归属明确的用例可继续;确认后先更新 businesses.json,再创建对应目录和用例。已有明确授权的分类调整直接执行,已确认分类下新增用例无需重复确认。
  • 工具仅纳入 case_version: 1 的 Markdown。旧文件 .agents/test/workflow/connection-rules.md 已拆为 app/workflow/editor/ 下的独立用例,旧路径保留查找索引;历史执行结果不作为当前用例通过的证据。

根据业务生成用例

  1. 确定本次功能、变更或回归范围。先查询已有用例,优先更新;保留已有 ID。只在本次需求有明确理由时增加场景,不按源文件或函数数量凑用例。
  2. 建立完整的行为依据链:需求/设计 → 页面与请求构造 → API 合约及统一响应处理 → 权限与服务 → 持久化/队列/外部依赖。只追踪本次相关路径,但不能只看单个 handler 就下结论。Pro 或外部服务不可读时明确边界。
  3. 预期先依据已确认需求和业务不变量,再检查实现是否符合。代码与需求冲突时标出待确认项,不能把现有 bug 写成正确预期。sources 记录实际阅读的仓库相对路径,baseline 记录当前 commit;不臆造接口、HTTP 方法、错误码、字段、集合名或 UI 文案。
  4. 先按业务规则、前置数据和验证方法归组,再选择有区分度的代表场景:一条完整主链路,以及必要的拒绝、边界、配置切换或兼容对照。相同规则在多个入口、节点类型或参数下的变化,优先用同一用例内的场景矩阵描述差异;不枚举所有组合,也不为凑齐基础/异常/边界三类新增文件。
  5. 一个 Markdown 对应一个完整业务验收目标,可以覆盖多个相关场景。读取并填充 用例模板:公共准备和公共断言各写一次,场景表只记录输入/初态差异、操作及特有预期。相互独立的子场景明确恢复哪个基线;连续状态流转明确承接前一步,不将准备过程复制为一组新用例。
  6. 只有互不相容的环境/权限、明显不同的资源准备或验收职责、无法放入同一可复现流程等实际原因才拆分。API、UI、数据库是同一目标的验证手段,不是拆文件的理由。通用的空值、越权、自连、重复提交等边界在所属规则中集中验证,其他用例只保留能区分本业务行为的对照。
  7. 交付前再收敛一次:检查新增场景能否由已有用例扩展覆盖,删除重复的准备、步骤和边界断言;合并后保留代表用例 ID,更新关联引用与旧编号索引,退役编号不重新分配。用例数量下降不能以丢失独特业务规则、隐藏阻塞项或增加无法定位失败的长流程为代价。
  8. 做文档局部校验并在阅读器检查。生成用例不等于执行通过;缺少环境、凭证、日志或数据库读取能力时,写明阻塞条件及待补证据。不要伪造通过结果。

用例类型、测试方式与验证证据

category 为单选用例类型,所有用例必须填写:basic(基础场景)验证常规业务路径;abnormal(异常场景)验证非法操作、业务拒绝、依赖失败及恢复;boundary(边界场景)验证临界条件、作用域边界、配置切换和历史兼容。

用例类型与 scenario 相互独立。例如越过容器边界连线可以是 category: boundary、scenario: failure。两者按用例主要验收目标归类,不限制其内部子场景的类型和结果;子场景在表中分别标记,必要时通过已有 tags 补充覆盖范围。不为分类标签或凑齐三类复制同一用例。

types 表示测试方式,可多选;evidence 表示验证证据:

types适用范围
api通过真实 HTTP 入口验证入参、认证授权、响应及副作用
ui通过产品界面验证交互、状态、错误提示、保存与重载
e2e验证跨页面、API、服务及异步任务的完整用户目标
integration验证真实服务与数据库、向量库、缓存、队列、存储或第三方依赖的协作
  • API:根据实际 OpenAPI、调用方和 NextAPI/共享 HTTP 管线确定请求与响应;同时验证 HTTP 状态、业务 code/data 或流式事件,不能只检查 HTTP 200。不把导入 handler 并 mock 所有依赖称为真实接口集成测试。
  • UI:写明入口、控件定位依据、操作、可见状态、错误提示、保存后刷新结果。不能只依据元素挂在 DOM 中就判定用户可见;不臆造不存在的 selector。
  • 数据库:从对应 Schema 与写入逻辑确认库、集合和字段,给出按本次 teamId/资源 ID/run 标识限定的只读查询、操作前后快照和变化断言。失败场景按真实事务、补偿与计费语义检查副作用,不能泛化成“所有数据和费用都不变”。
  • 日志:先检查实际 logger 调用、字段、日志等级与输出配置;给出获取位置、时间窗和实际可用的关联字段。可参考 packages/service/common/logger/、packages/service/common/http/entry.ts、应用日志 API 以及模型渠道日志 API,具体用例只引用已核实的部分。
  • Trace:仅在环境已启用且有查询权限时使用。采样、保留期限及 otel: false 会影响可见性;日志/trace 缺失本身不能证明业务没有执行。用户配置错误可能记录为 info,不应要求所有失败都有 error 日志。
  • 缓存、队列、文件与对象存储:按业务需要检查键/任务/对象生命周期和关联资源;只将已核实的读取能力写成必需验证项。
  • 异步链路:写出状态变化、完成/失败判据、轮询间隔与最长等待时间,超时列为失败或阻塞;避免固定 sleep 后直接判成功。重试前检查是否已成功及是否支持幂等,不能盲目重放写操作。
  • 模型输出:尽量使用可控数据及稳定的结构、引用和路由断言;自由文本按明确语义或评分规则验收,不依赖随机输出逐字相等。

Markdown 约定

模板 frontmatter 用于查询,正文必须有「用例简介、前置准备、测试步骤、预期结果」四个二级标题。

  • 「用例简介」面向阅读者,用一小段自然语言讲清业务情境、关键操作和需要保证的结果,通常 2~3 句话。不写分类解释、合并过程或执行状态;分类放 frontmatter,合并来源和退役编号放旧编号索引,实际执行状态放测试报告。需求依据通过 sources 或相关设计关联,待确认的业务差异放前置准备的阻塞项;简介只保留影响理解的适用条件。
  • id:全库唯一、稳定,例如 FG-APP-WORKFLOW-001。新建前同时检查当前用例与合并来源/旧编号索引,已用过或退役的编号不能复用;改名和移动不改变 ID。
  • business:与文件所在的业务目录完全相同,例如 app/workflow/editor。
  • category:basic / abnormal / boundary,分别表示基础场景、异常场景、边界场景;按主要验收目标选择,与 API/UI 等测试方式分开记录。
  • scenario:success / failure / special,表示主要验证的业务场景,不表示实际执行结果;同一用例可在子场景矩阵中同时覆盖成功、拒绝和特殊行为。
  • status:draft / ready / deprecated,表示用例定义状态。只有前置准备、步骤、断言可复现且无阻塞时才设 ready;不代表测试已通过。
  • priority:P0 核心可用性/权限或数据资金正确性,P1 重要业务分支,P2 次要兼容或体验;按实际影响判断。
  • types、tags、evidence、sources、routes、related 均为数组。没有相关接口时 routes: [],不编造占位接口。
  • 每个子场景指定编号、初态/输入差异、操作和证据;预期按编号对应,给出字段值、精确差集、状态集合或 UI 表现。复位和连续操作的边界必须明确,以便单独定位、复现失败。准备中包含测试数据隔离与清理方法,凭证仅写环境变量或占位符。
  • automation 可选,按 脚本执行约定 关联实际存在的 Node 或 Playwright 脚本及完整子场景 ID。先查询已有脚本再新增,复用公共准备和操作;没有脚本不影响用例归档,由 AI 执行。只完成一部分参数变体或只做内部规则单测时,不能声明覆盖完整集成场景。
  • 经复核确认脚本无法稳定覆盖实际入口或桌面操作时,移除对应子场景的 automation 映射,在前置准备明确标注 AI 执行;保留验收断言和证据要求,不保留仅靠缺失配置返回阻塞的占位脚本。
  • 成功、失败、特殊行为可以在同一业务目标下用场景矩阵覆盖;无关或已被通用用例证明的边界不重复列入,不填无意义的三组空预期。

查询与阅读

以下命令从仓库根目录运行,需要已安装仓库依赖(复用 js-yaml,无需新增包):

# 校验用例、ID、分类与必需章节;不执行产品测试
node .agents/skills/system/fastgpt-integration-test-case/scripts/catalog.mjs validate

# 查询并输出 JSON;可组合 --business、--category、--type、--scenario、--tag、--evidence、--status、--q
node .agents/skills/system/fastgpt-integration-test-case/scripts/catalog.mjs list --business app/workflow --category boundary --type ui

# 查询多场景用例的覆盖范围;category 仅表示主类型,覆盖标签由用例按需填写
node .agents/skills/system/fastgpt-integration-test-case/scripts/catalog.mjs list --tag 覆盖异常场景

# 启动只读阅读器和查询接口,默认只监听本机
node .agents/skills/system/fastgpt-integration-test-case/scripts/catalog.mjs serve

浏览器访问 http://127.0.0.1:4317/,JSON 入口为 GET /api/cases,支持与 CLI 同名查询参数。返回用例元数据、正文、相对路径、分类及诊断信息;每次读取重新扫描,不另维护 index.json 或数据库。

唯一页面是 .agents/test/index.html,首页先展示大面积的业务目录和用例列表,点击具体用例才进入正文;返回目录保留筛选和浏览位置。默认每 5 秒重新扫描。也可直接打开 HTML,选择 .agents/test/ 目录后离线阅读;支持目录句柄时可重新扫描新增/修改文件,目录上传兼容模式下更新后需要重新选择。浏览器不能未经授权扫描任意本地目录。

维护页面解析逻辑时修改 scripts/case-format.cjs,再运行 catalog.mjs sync-reader,将共用解析器嵌回单页。HTML 已内嵌带许可声明的 Markdown/YAML/净化库,不依赖 CDN。新增用例只写 Markdown,不改 HTML。

交付前运行上述 validate;改动查询工具或阅读器时,使用临时用例目录验证过滤、解析失败诊断、重复 ID、目录扫描、Markdown 渲染和刷新,不在正式用例库留下演示数据。不运行无关或全量产品测试,不另写总结报告。

Repository

labring/FastGPT

Path

.agents/skills/system/fastgpt-integration-test-case/SKILL.md

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.