FastGPT 单元测试开发指南测试目录规范、覆盖率要求与 Vitest 实战【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT导读本文档基于 FastGPT 开源仓库中.agents/skills/system/test-case/SKILL.mdAgent 技能定义展开系统讲解在该仓库中为packages与projects两个代码域编写单元测试的完整规范包括测试文件放置规则、fastgpt别名导入方式、全局 mock 与第三方依赖的使用边界、必须覆盖的场景清单以及从编写到验证的完整流程。读完本文你将掌握 FastGPT 仓库的测试约定能按照仓库既有规范独立为任意源码文件编写覆盖率达标、可稳定运行的 Vitest 单元测试并借助仓库内置的命令体系完成结果验证。测试文件的位置约定与源码目录一一镜像FastGPT 仓库采用 monorepo 结构代码主要分布在packages/与projects/两个目录下。仓库对测试文件的位置有严格的镜像约定目的是让开发者通过路径即可快速在源码与测试之间跳转。packages 域测试落在 packages 对应的 test 目录packages/下的测试统一放在对应包的test目录中且子路径与 packages 内部的目录结构一一对应。例如源码文件packages/global/common/error/s3.ts其测例文件路径应为packages/global/test/common/error/s3.test.ts——即把common/error/s3这段子路径原样搬到packages/global/test之下源码的common目录对应测试的test目录两者平行。仓库中确实存在这一对应关系例如 s3.ts 源码 与 s3.test.ts 测例 同时存在可以直接对照阅读。此外packages 内的文件可以通过fastgpt别名导入无需写长长的相对路径。fastgpt在 vitest.config.mts 中被解析为仓库根目录下的packages因此可以这样写import { s3 } from fastgpt/global/common/error/s3;projects 域测试落在 projects/app/test 目录projects/下的测试放在projects/app/test目录中子路径同样镜像projects/app/src的目录结构。例如 API 源码projects/app/src/pages/api/core/dataset/collection/create.ts对应的测例文件路径为projects/app/test/api/core/dataset/collection/create.test.ts。同时vitest.config.mts 中还配置了别名指向projects/app/src方便在测试中导入应用层源码。测试文件编写规则通用规则一个源码文件对应一个测试文件每个函数使用独立的describe块组织用例。覆盖率要求需要覆盖 100% 的行数与分支。在最终验证阶段仓库技能文档要求通过运行测试确认每个文件的覆盖率在 90% 以上详见下文结果验证一节。尽量少引入第三方依赖测试应使用较为原生的方式进行断言检查。如果确实需要第三方依赖库例如类型声明应从被测试的源文件里显式导出再在测试中使用。仓库中的实际案例是 geo/index.ts它从next重新导出了NextApiRequest类型专供 geo/index.test.ts 使用// FastGPT/packages/service/common/geo/index.ts import type { NextApiRequest } from next; // 同时导出一个依赖给 FastGPT/packages/service/test/common/geo/index.test.ts 使用 export type { NextApiRequest } from next;尽量少 mock系统上原生可运行的函数无需 mock只 mock 那些无法在本地直接运行的依赖例如需要远程服务、API 密钥的模块。跳过静态文件type.ts、constants.ts、schema.ts、*.schema.ts文件以及静态数据直接跳过忽略不为其编写测试。遵循配置排除规则根据 vitest.config.mts 中的coverage.exclude配置跳过不需要测试的文件。从该配置可以看到仓库在统计覆盖率时已经排除了**/test/**、**/*.test.ts、各类*const.ts、type.ts、schema.ts等文件以及packages/global/openapi/**/*与packages/global/core/workflow/template/**/*两个目录。不要重复 mock 全局内容test/mocks/index.ts 中已包含全局 mock包括 request、mongo、redis、bullmq、s3、system、vector、tracks、log、response、audit 工具以及 AI 的 embedding/llm 等模块理论上一行import ./mocks通过 test/setup.ts 自动加载即可让各类 infra 在测试中可运行编写测试时请勿重复 mock。基础函数文件测试对于纯逻辑的基础函数尽量不要 mock而是完整运行其逻辑进行测试这样能真实反映函数的输入输出行为。例如 s3.test.ts 直接对parseS3UploadError传入各种形态的 error 对象字符串错误、axios response 结构、代理 JSON 结构等用真实的vi.fn构造翻译函数并断言翻译 key 与参数全程未 mock 被测函数本身。带 API 请求的函数对于包含 API 请求的函数则mock 对应的 API 请求进行测试避免真实发起网络调用。编写流程技能文档给出了一套标准化的三阶段流程一、任务准备获取所需要编写的测试文件清单创建任务清单逐个完成每个文件的测例编写。二、测例编写不同测例文件可以并行编写检查对应的.test.ts测试文件是否存在不存在则创建阅读并分析源码后编写测试样例检查 TS 错误确保无 TS 报错完成所有测试文件的编写。三、结果验证调用pnpm test file-path test-name运行测试并检查覆盖率确保每个文件的覆盖率达到 90% 以上如果测试不通过根据错误信息检查代码逻辑或测试用例如需二次修改回到二、测例编写环节。单元测试需要覆盖的场景技能文档明确要求单测至少覆盖以下五类场景基础场景函数正常输入下的主路径行为复杂场景参数组合复杂、存在多分支逻辑的调用边界值空值、0、极大/极小值、临界长度等安全边界情况死循环、系统崩溃、超大数据等极端输入异常场景非法输入、依赖报错、超时等异常路径。以 s3.test.ts 为例其对parseS3UploadError覆盖了字符串错误、axios response、代理 JSON、文件类型不匹配、鉴权失败、Bucket 不存在、网络错误、超时、超大文件等十几种分支——这正是基础 复杂 边界 异常场景要求的落地体现。常用命令与运行机制技能文档给出的常用命令如下# 运行所有测试 pnpm test # 运行指定测试文件(file-path 填完整文件路径) pnpm test file-path # 运行指定测试文件的指定测试 pnpm test file-path test-name根目录 test 命令的解析逻辑根目录 package.json 中test脚本为node ./scripts/test/run.mjs其行为由 scripts/test/run.mjs 决定当传入了文件路径参数时会走scripts/test/light.mjs轻量执行器先对每个测试路径从所在目录向仓库根向上查找最近的 Vitest 配置默认依次匹配vitest.config.ts/vitest.config.mts/vitest.config.js/vitest.config.mjs再按配置分组、顺序执行各 workspace 的局部测试并强制--coverage.enabledfalse、--maxWorkers1、--no-fileParallelism避免多个 Vitest/Mongo 实例同时抢占资源见 scripts/test/light.mjs。传入的test-name会作为 vitest 参数透传给对应用例过滤。未传路径时会读取FASTGPT_TEST_MODE与FASTGPT_TEST_SCOPE环境变量组织 workspace 单测unit默认与 service 集成测试integration/sandbox/all的执行计划。测试运行环境仓库为测试注入了完善的环境设施vitest.config.mts 为测试环境预设了FILE_TOKEN_KEY、AES256_SECRET_KEY、INVOKE_TOKEN_SECRET、FE_DOMAIN等密钥类环境变量带默认值便于本地直接运行并启用 HTML/JSON 覆盖率报告test/globalSetup.ts 通过mongodb-memory-server启动内存版 MongoDB ReplicaSet可通过FASTGPT_TEST_MONGODB_URI复用外部实例并按 workspace 名隔离数据库test/setup.ts 在每个测试文件的beforeAll中连接 Mongo、初始化全局变量与模型并在每个用例结束后清理集合数据保证用例间隔离。结语FastGPT 仓库的单元测试体系可以概括为三条主线目录镜像测试文件与源码一一对应、就近放置、最少 mock优先真实运行逻辑、全局 mock 兜底 infra、覆盖率驱动行/分支 100% 的目标与 90% 以上的验收底线。这套规范既适用于本仓库内部的功能模块如全局错误处理、服务层工具函数也可以作为其他 TypeScript monorepo 项目搭建 Vitest 测试体系的直接参考。动手实践时建议从packages下的纯函数入手例如packages/global/common/error/s3.ts对应的 s3.test.ts先跑通pnpm test命令链路再逐步扩展到带 API 请求的复杂函数。【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考