@yc_yzkj/scenario-test
v0.10.0
Published
Reusable browser and Node.js scenario testing library
Downloads
1,210
Readme
scenario-test
面向业务项目的 HTTP 场景测试工具,提供声明式 DSL、浏览器工作台和 Node.js CLI。通过全局 AI Skill 接入业务项目,根据指定的业务入口生成场景,再用工作台或 CLI 运行同一套测试。默认免 npm 接入,不修改业务项目依赖,也无需克隆本仓库。
运行要求:Node.js 18+;维护本仓库并构建时需要 Node.js 20+。
| 你想做什么 | 从哪里开始 | | --- | --- | | 首次使用:安装全局 AI Skill | 安装全局 AI Skill | | 首次接入业务项目 | 快速接入 | | 运行、导入或检查场景 | 常用操作 | | 升级已有项目 | 升级 | | 开发和发布本工具 | 维护者 |
典型流程:在业务项目根目录接入 → 提供一个业务功能及其代码或接口入口 → 检查生成的场景和环境配置 → 使用工作台或 CLI 执行。执行场景会调用实际接口,可能产生业务数据,请先确认目标环境和场景内容。
安装全局 AI Skill
在 Codex、Claude Code、Kilo Code 等支持 Agent Skills 的工具中按用户安装一次,即可在多个业务项目中使用:
官方安装:
# 用户级全局安装;按提示选择你使用的 Agent
npx skills add duyiliu/scenario-test --skill scenario-test -g国内网络加速安装(第三方 skills-cn):
npx skills-cn@latest add duyiliu/scenario-test --skill scenario-test -g -y两种方式均从本仓库安装 scenario-test Skill。skills-cn 为第三方 CLI,其自身版本不保证与官方同步;-g 表示用户级安装,-y 跳过交互确认。
该命令安装用户级 Skill,不会在业务项目中安装 npm 依赖。Windows 原生与 WSL 的用户目录各自独立,需在使用的环境分别安装。
Skill 会在当前工作区定位业务项目,读取该项目自己的规则与能力清单。首次接入需要 Node.js 18+ 和可访问的安装源;运行时保存在业务项目中,后续使用无需再次下载工具(升级时除外),执行测试仍需连接目标服务。
未接入项目会按快速接入自动初始化;设置 SCENARIO_TEST_NO_AUTO_INIT=1 或明确拒绝时,Skill 会先征询。项目不完整时不会自动修复。全局 Skill 和各项目运行时分别升级,见升级。
Skill 入口和探测脚本分别见 SKILL.md 和 detect-project.mjs。探测只检查文件是否存在;配置与运行时完整性以 doctor 结果为准。
快速接入
- 如果尚未安装全局 Skill,先完成上一节;然后在业务项目根目录打开支持 Agent Skills 的 AI 助手。
- 告诉 AI 需要测试的业务功能,并提供页面、Controller、接口或已有测试中的任一入口。例如:
为 OrderController 生成 HTTP 场景测试。 - 项目尚未接入时,Skill 会确认项目根目录和环境,使用下方固定版本脚本初始化,再执行
doctor。已接入项目不会自动升级;体检失败时先处理问题。 - AI 根据项目证据维护
scenario.config.js和scenarios/。生成阶段不会调用业务接口;需要执行时,请明确提出并确认目标环境和场景内容。
初始场景清单为空。场景准备好后,可用浏览器工作台或 CLI运行;工作台通过本地 serve 代理访问所选环境,无需后端额外放行 CORS。
Skill 使用的固定版本安装脚本
Skill 初始化时使用与本页相同的固定版本脚本,通常无需手动执行。在业务项目根目录执行时,脚本下载固定版本运行时并初始化 scenario-test/,不修改业务项目依赖;安装后会自动执行 doctor。
# Windows PowerShell
irm https://cdn.jsdelivr.net/gh/duyiliu/[email protected]/scripts/install.ps1 | iex# macOS / Linux
curl -fsSL https://cdn.jsdelivr.net/gh/duyiliu/[email protected]/scripts/install.sh | bash -s -- . scenario-test默认脚本从 npm Registry 下载固定版本 tarball,在临时目录解压后从本地 dist/ 初始化;不会执行 npm install 或访问 GitHub API。内网下载源的指定方式和文件要求见自定义下载源。
常用操作
在业务项目根目录,也可以直接向 AI 提出操作,例如:
为 OrderController 补充订单创建失败的场景测试。在 local 环境运行 order-create-success 场景,并汇总结果。检查当前项目的 scenario-test 安装状态,运行 doctor。启动当前项目的场景测试工作台。
生成场景不会自动发起 HTTP 请求;执行、批量运行和启动工作台需明确提出。执行可能修改业务数据,先确认目标环境、测试数据和清理方式。以下是需要手动操作或接入 CI 时的命令,均从业务项目根目录执行。
启动浏览器工作台
推荐双击:
scenario-test/start-scenario-test.cmd也可以手动执行:
node .\scenario-test\.scenario-test\scenario-test-cli.cjs serve `
--config .\scenario-test\scenario.config.js `
--port 4300
serve未指定--port时默认 4300;双击start-scenario-test.cmd时脚本会向系统申请随机空闲端口,多项目同时启动互不冲突。上游空闲超时默认 30 秒,慢接口/大文件联调时可调大:
--proxy-timeout 120000(毫秒,1-600000 的整数)。为便于内网联调,https 上游沿用本地开发代理的
rejectUnauthorized: false(不校验自签证书),不要将 serve 暴露到本机回环之外。
界面预览
浏览器工作台支持查看场景列表、逐步执行接口请求,并实时展示执行进度与结果。

场景执行完成后,工作台会汇总成功、失败和跳过的步骤,并展示耗时与执行详情。

AI 辅助生成场景后,也可以通过 CLI 执行并汇总结果。

执行场景
# 全部非 manual 场景(命令 run 紧跟脚本名)
node .\scenario-test\.scenario-test\scenario-test-cli.cjs run `
--config .\scenario-test\scenario.config.js --env local --all
# 指定场景
node .\scenario-test\.scenario-test\scenario-test-cli.cjs run `
--config .\scenario-test\scenario.config.js --env local --scenario health-check
# 多场景并发(默认 1 串行;并发只发生在场景之间,场景内步骤仍串行)
node .\scenario-test\.scenario-test\scenario-test-cli.cjs run `
--config .\scenario-test\scenario.config.js --env local --all --concurrency 4
# 临时覆盖变量 / 请求超时(无需修改配置)
node .\scenario-test\.scenario-test\scenario-test-cli.cjs run `
--config .\scenario-test\scenario.config.js --env local --all `
--vars clientId=temporary-client `
--vars "clientSecret={{vars.defaultSecret}}" `
--timeout 5000--vars key=value 可重复,按出现顺序叠加(同名后者覆盖),优先级高于配置 vars 与环境变量,值支持 {{ }} 模板;--timeout <ms> 覆盖配置 requestTimeoutMs。runId / runNo 为保留变量,不能用 --vars 覆盖。
--scenario 支持逗号分隔多选,并按 id/name/url 匹配;省略 --env 时使用配置的 defaultEnvKey(未配置则取第一个环境)。临时切换目标可用 --base-url <url>;认证信息优先通过 SCENARIO_AUTH 环境变量提供。
以上命令从业务项目根目录运行;local 和 health-check 分别是环境 key 和场景 ID 示例,应替换为项目中实际配置的值。macOS / Linux 可使用以下命令:
# 启动工作台
node ./scenario-test/.scenario-test/scenario-test-cli.cjs serve \
--config ./scenario-test/scenario.config.js --port 4300
# 执行指定场景
node ./scenario-test/.scenario-test/scenario-test-cli.cjs run \
--config ./scenario-test/scenario.config.js --env local --scenario health-check
# 体检
node ./scenario-test/.scenario-test/scenario-test-cli.cjs doctor \
--config ./scenario-test/scenario.config.js导入真实流量
把浏览器 Network 面板导出的 HAR 或后端给出的 curl 示例转成可编辑的场景草稿。以下命令从业务项目根目录运行,输出位置明确指定在场景测试目录中:
# HAR:过滤静态资源/OPTIONS,每个 API 请求生成一个 step
node .\scenario-test\.scenario-test\scenario-test-cli.cjs import --har session.har --output scenario-test/scenarios/imported-har.js
# 单条 curl:生成单步骤草稿,并在终端打印可直接粘贴的 step 片段
node .\scenario-test\.scenario-test\scenario-test-cli.cjs import --curl 'curl -X GET https://api.example.com/orders' --output scenario-test/scenarios/imported-orders.js
# 只要指定主机、最多导入 10 条,或自定义输出文件
node .\scenario-test\.scenario-test\scenario-test-cli.cjs import --har session.har --host api.example.com --max-entries 10 --output scenario-test/scenarios/imported-filtered.jsimport 的默认输出目录及 --output 均相对于执行命令时的当前工作目录,而不是配置文件目录。未指定输出时会生成 scenarios/imported-<时间戳>.js;显式指定已存在的输出文件会覆盖它。场景 ID 由输出文件名生成。
Authorization、Cookie、API Key 等可识别的敏感头和查询参数会替换为 {{vars.*}} 占位;二进制或 multipart 请求体会省略。请求体以及未识别的自定义敏感字段可能原样写入草稿:生成后、提交前请检查凭据、个人数据及业务数据。通过环境变量等项目已有方式提供真实凭据,避免写入配置文件或命令历史。草稿中的状态码、动态字段和业务断言也需要人工确认。
将生成的文件加入 scenario-test/scenario.config.js 的 scenarios 清单;url 相对于配置文件所在目录。以下对应上面的 curl 示例:
scenarios: [
{ id: "imported-orders", name: "导入订单请求", url: "scenarios/imported-orders.js" }
]若输出目录与配置文件目录不同,需要按配置文件位置调整 url。确认目标环境和请求内容后,再执行该场景。
体检
node .\scenario-test\.scenario-test\scenario-test-cli.cjs doctor `
--config .\scenario-test\scenario.config.js场景示例
下面演示一个只读健康检查。接口路径和响应字段仅为示例,使用前请按实际接口调整。
- 创建
scenario-test/scenarios/health-check.js:
ScenarioTest.registerScenario("health-check", ScenarioTest.defineScenario({
name: "健康检查",
steps: [
{
name: "检查服务状态",
method: "GET",
path: "health",
status: 200,
assertions: [{ path: "status", equals: "UP" }]
}
]
}));- 在
scenario-test/scenario.config.js中,按实际情况设置envs中对应环境的baseUrl,并将场景加入scenarios数组:
{ id: "health-check", name: "健康检查", url: "scenarios/health-check.js" }配置中的 id 必须与 registerScenario 的 ID 一致。之后可用上方 执行场景 中的命令运行。
自定义下载源
安装脚本的 -Source / SCENARIO_TEST_SOURCE 使用可通过 HTTP(S) 访问的 URL 前缀,需提供以下 4 个运行时文件:
scenario-test-cli.cjsscenario-test.umd.jsscenario-test.d.tsscenario-test-capabilities.json
直接调用 init 时,--library-url 也是这些文件的下载 URL 前缀;CLI 优先使用本地运行时文件,缺少时才从该地址下载。AI_SCENARIO_PROMPT.md 和 SCENARIO_PATTERNS.md 由 init 生成在 .scenario-test/,无需放在下载源。
项目目录
scenario-test/
├─ .scenario-test/ # AI 规则与固定版本运行时副本(init 生成)
├─ scenarios/ # 按业务功能组织的场景(由 AI 维护,非 init 生成)
├─ plugins/ # 可选:项目专属 Node 插件(按需创建)
├─ scenario.config.js # 环境、变量和场景清单(init 生成骨架)
├─ index.html # 浏览器工作台入口(init 生成)
└─ start-scenario-test.cmd # Windows 双击启动入口(init 生成)初始化配置使用项目内类型声明,npm 与免 npm 均可获得提示:
/// <reference path="./.scenario-test/scenario-test.d.ts" />scenario.config.js 和 scenarios/ 应随业务项目提交;.scenario-test/ 是固定版本运行时副本,团队可选择一并提交以便 CI 直接运行,或在 CI 中先执行安装脚本。无论哪种方式,都不要把真实凭据写入这些文件。
核心能力
场景编写
- 声明式 HTTP 场景 DSL,支持变量、提取、断言、条件和重试;
when可基于已提取变量(vars)、本次 run 共享变量(suite)、上一步响应体(lastResponse)或状态码(status/target: "status")跳过步骤。 retryUntil.retryOn可选assertion(默认)/error/timeout,服务刚启动时的网络错误和单次请求超时也能继续轮询;intervalFactor/maxIntervalMs支持指数退避。extract支持scope: "suite",把登录 token 等结果写入本次 run 的共享命名空间,后续场景用{{suite.<name>}}引用;每个场景以启动时的快照运行,结束时合并(并发时按完成顺序,同名键后完成者覆盖)。suite不跨 run、不建立显式依赖。from: "headers"的首段头名大小写不敏感;path支持[*]通配段,可产出数组并直接用于length/includes/each断言。
工作台与运行
- 浏览器工作台与 Node.js CLI 使用同一套场景;
serve按浏览器当前环境逐请求路由,同源代理免 CORS。 run支持--concurrency、--bail、--data、--junit、--cookie-jar、--tag、--fail-on-skip;manual: true场景默认不参与--all。run --json输出结构化结果,stdout 纯净、进度与结论走 stderr,失败时仍输出完整 JSON 并返回非零退出码。
诊断与集成
doctor校验配置、场景、运行时版本和 SHA256 指纹;capabilities --json输出机器可读能力清单。import --har/import --curl把真实流量或 curl 示例转成场景草稿;静态资源与预检会被过滤,敏感头和查询参数替换为{{vars.*}}占位,二进制/multipart 请求体会省略并注明。- 还支持
shape结构断言、always清理步骤、文件上传、响应保存和自定义 Node 插件。
完整示例见 examples/complete;DSL 能力以项目内 .scenario-test/scenario-test-capabilities.json 为准(本仓库由 src/contract.js 生成)。更多文档:适配器指南、示例索引。
安全
- 场景文件是可执行代码,只加载可信来源。
- 不要提交生产凭据、个人数据或真实 Token。
- CLI/CI 优先通过环境变量提供敏感值。
- 浏览器本地存储适合受控联调环境,不应保存生产凭据。
详细说明见 SECURITY.md。
升级
全局 Skill 和每个业务项目的运行时分别维护。更新 Skill 不会更新业务项目;普通的生成或执行请求也不会自动升级已有运行时。
更新全局 Skill
如果使用上文的 npx skills 安装,在对应的 Windows 原生或 WSL 环境执行:
npx skills update scenario-test -g该命令更新用户级 scenario-test Skill。其他安装方式按所用工具的更新流程操作;更新后建议开启新会话,再检查工具是否加载了新版 Skill。
升级业务项目运行时
在目标业务项目根目录,向 AI 明确提出:
请将当前项目的 scenario-test 运行时升级到最新发布版本,
保留现有配置和场景,并在升级后运行 doctor。Skill 会先确认当前项目、现有版本锁、目标发布版本和安装来源,再执行升级。升级前应保存或备份相关未提交改动;默认保留 scenario.config.js 和 scenarios/,并刷新 AI 规则和模式库。版本或契约不一致、运行时缺失或与锁定指纹不一致时会刷新运行时副本。不要随意传 --force,它会覆盖与初始化模板同名的已有文件,包括配置文件。
升级后检查 doctor 的版本锁、能力清单和配置结果;有 FAIL 时先排查,不能只凭安装命令退出成功认定升级完成。doctor 是静态体检,不会替代场景实际执行。各业务项目需要分别升级。
手动升级与内网备用
需要手动操作时,先核对目标发布版本和现有接入方式:package.json 包含 @yc_yzkj/scenario-test 依赖通常表示 npm 接入;两种接入方式都会生成 scenario-test/.scenario-test/,不能仅凭该目录判断。以下命令以 0.10.0 为例,实际升级时请替换为确认的目标版本。
免 npm 接入可在项目根目录重跑固定版本安装脚本;npm 接入可执行:
npm install -D @yc_yzkj/[email protected]
npx @yc_yzkj/scenario-test init --project . --dir "scenario-test"无外网时,先准备对应版本的安装脚本及内网运行时文件,例如:
.\install.ps1 -Source "https://gitlab.example.com/group/project/-/raw/v0.10.0/dist"升级完成后执行:
node .\scenario-test\.scenario-test\scenario-test-cli.cjs doctor --config .\scenario-test\scenario.config.js历史变更见 CHANGELOG.md。
维护者
要求:Node.js 20+(构建链含 Tailwind CSS 4 的 oxide;业务项目运行时消费仍为 Node.js 18+)。
npm install
npm run build
npm run test:unit # 单测/集成(tests/*.test.js)
npm run test:coverage # 仅 src/ 口径,line 90 / branch 80
npm run test:browser # Playwright 浏览器测试
npm run check:all # 构建 + unit + browser + ui-style + 行尾审计CI 在 GitHub Actions 上覆盖 Node 20/22 × Ubuntu/Windows 的构建与单测、覆盖率、浏览器测试、视觉回归和行尾审计,见 .github/workflows/ci.yml。
发布流程见 docs/RELEASING.md。
本项目采用 MIT License。
