bun-webview-test
Skill159 starsChanged 2 days agoMITView on GitHub
使用 Bun 1.4 内置的 Bun.WebView 无头浏览器对前端页面(Vue/Vite 等)做端到端冒烟与交互测试。当需要加载页面、真实点击、读取 DOM/应用状态、做断言、截图归档,或对本地开发服务器/静态站点做零依赖的浏览器级验证、可视化巡检、交互回归测试时,应使用本技能。
In this repository14 other files it gives its agents.
- AGENTS.mdAGENTS.md
- admin-management-pageSkill
- build-creatorSkill
- charbuild-dps-ablationSkill
- db-styleSkill
- dob-skill-creatorSkill
- fmodel-unpackSkill
- i18nSkill
- orchestrated-deliverySkill
- perf-hotspot-profilingSkill
- shuorenhuaSkill
- tauri-cdpSkill
- video-productionSkill
- wt-review-prSkill
The file
Files
Bun.WebView 前端测试
Overview
本技能封装 Bun 1.4 新增的 Bun.WebView 无头浏览器能力,提供一套零依赖的前端端到端测试框架。它取代了 Puppeteer / Playwright 的安装开销,用单个 bun 命令即可驱动真实浏览器(macOS 用系统 WebKit,Windows/Linux 用已安装的 Chrome/Edge 经 CDP)完成:页面加载、真实用户输入、DOM/状态读取、断言与截图。
完整 API 细节见 references/webview-api.md,不要凭记忆猜测方法签名。
When to use
- 对
pnpm dev起的开发服务器(本项目默认http://localhost:1420)做冒烟测试。 - 验证某个路由/组件是否正确挂载、渲染、无控制台报错。
- 模拟用户点击/输入/滚动,校验交互后的状态或路由变化。
- 需要截图归档供人工查看(可视化巡检、回归基线)。
- 任何"用浏览器跑一下确认没坏"的场景,且不想引入 Playwright 依赖。
Prerequisites
- Bun >= 1.4:运行
bun --version确认;低于此版本无Bun.WebView。 - 目标前端可访问:先用
pnpm dev启动本项目开发服务器(或指向任意可访问 URL)。 - Windows / Linux 需安装浏览器:
Bun.WebView在 Windows 默认走 Chrome 后端,需本机已装 Chrome/Chromium/Edge/Brave。找不到时设BUN_CHROME_PATH指向可执行文件,或装 Playwright 的chrome-headless-shell。macOS 用系统 WebKit,无需安装。
Workflow
Quick Start(复用框架跑测试)
- 确认开发服务器运行中:
pnpm dev/pnpm dd2(保持 http://localhost:1420 可访问)。 - 务必带
?hideUpdateInfo=1打开页面(见下方「启动弹窗」),否则会被数据包弹窗挡住。 - 运行内置示例冒烟测试:
bun .agents/skills/bun-webview-test/scripts/example.test.ts # 或指定地址 bun .agents/skills/bun-webview-test/scripts/example.test.ts --url http://localhost:1420 - 失败用例会自动留图(见 Guidelines 的
.tmp约定),通过screenshots/home.png查看首屏。
注意点:
- 参数必须在首次导航的 URL 上;先打开无参数地址再
router.push加参数不会生效。 - 该参数只关弹窗,不会安装数据包:依赖游戏数据的页面(如
/char/:id构筑页)依然会因为charBuild.calculateWeaponAttributes is not a function之类报错渲染失败。这类页面要在 已装数据包的浏览器里人工验证,或给WebView传dataStore: "./profile"复用已装数据包的 profile。 - 判断弹窗是否还在:
document.querySelector("dialog.modal.modal-open")非空即被挡住。
编写新的测试文件
新建一个 *.test.ts,从框架导入能力,注册用例,末尾调用 run():
import { test, expectVisible, expectEval, expectNoConsoleErrors, snapshot, run } from "./webview-test.ts"
test("标题区域可见", async ({ view }) => {
await expectVisible(view, "header h1")
})
test("无控制台错误", async () => {
await expectNoConsoleErrors()
})
run()可用断言辅助(详见 scripts/webview-test.ts):expectText、expectContains、expectVisible、expectCount、expectCountAtLeast、expectEval、expectNoConsoleErrors、snapshot、evalExpr。
直接在用例内也能调用底层 view 方法:await view.click("button.submit")、await view.evaluate("app.store.xxx")、await view.scroll(0, 400)、await view.screenshot({ format: "png" })。
运行参数
--url <地址>:覆盖基准地址(默认http://localhost:1420)。- 环境变量
FRONTEND_TEST_URL:同上,优先级低于--url。 - 退出码:
0全部通过;1有用例失败;2无法导航到目标(通常是服务器没起)。
Core Capabilities
- 零依赖无头浏览器:
new WebView({ width, height, console, dataStore }),无需 npm 安装浏览器引擎。 - 真实用户交互:
click/type/press/scroll派发原生事件(isTrusted === true),选择器方法自动等待可操作。 - 页面求值与状态读取:
evaluate(expr)在页面上下文执行 JS 字符串并返回反序列化结果;evalExpr封装了undefined安全处理。 - 声明式断言:文本 / 可见性 / 数量 / 任意表达式 / 控制台错误,断言失败即截图留证。
- 截图归档:
snapshot(ctx, name, format)保存到screenshots/(相对process.cwd(),建议以.tmp为工作目录),供人工或更严格的回归对比。
Guidelines
evaluate接收字符串表达式;多语句用(function(){ ... })()包裹,顶层const/let会抛SyntaxError。console选项必须是函数(console: (level, ...a) => {...}),传true会抛ERR_INVALID_ARG_TYPE。- 断言失败不要靠"肉眼看截图"判断;优先用
evaluate读取 DOM/状态做代码级断言,截图仅作人工辅助。 navigate会重置页面:注入到window上的钩子/状态(含localStorage之外的临时全局量)会随整页加载丢失, 所以钩子只能在最后一次navigate之后装,且每个用例内自给自足,不要跨用例依赖注入态。- 要断言「某个功能被触发」就 hook 构造函数:例如确认「开关打开后立刻启动了索引 Worker」,
可在页面里替换
window.Worker记录 URL 再触发交互(new Worker的参数是URL对象,String()后含xxx.worker)。 - 读模块内部状态:页面上下文
await import("/src/utils/xxx.ts")可直接调纯前端模块(裸包名解析不了), 用来断言「语料/索引是否已建」这类不体现在 DOM 上的状态,比翻 UI 稳。 - 无头 profile 默认深色主题且没有数据包:依赖游戏数据的异步流程会静默失败,
断言要挑不依赖数据的信号(DOM 结构、
localStorage、Worker 计数),别把「数据没装」误判成功能坏了。 - 需要登录态跨用例保留时,给
WebView传dataStore: "./profile"。 - 导航 URL 一律追加
?hideUpdateInfo=1,否则启动期的数据包弹窗会盖住页面(详见上方「启动弹窗」)。 - 截图与临时脚本放
.tmp/:框架按process.cwd()写screenshots/,所以以.tmp为工作目录运行 (workdir: <repo>/.tmp)即可让产物落在.tmp/screenshots/,不要在仓库根留下screenshots/。 - 点 reka-ui
Select只能坐标点可见项:打开后全部 option 都在 DOM(本项目等级选择器有 240 个,不做虚拟化,[role=option]可数),但当前选中项会对齐触发器,序号小于当前值的 optiongetBoundingClientRect().top为负、点不到;view.type+Enter的 typeahead 不生效。改值的做法:先evaluate取出一个可见(top > 0 && bottom < innerHeight)且innerText不等于当前值的 option,再用view.click(x, y)点它的中心。 - 每次变更前端后,建议把关键路由的冒烟测试纳入验证(配合
pnpm lint/pnpm test)。
Resources
scripts/
webview-test.ts— 测试框架:注册器test、断言辅助、截图、运行器run。测试文件应 import 它。example.test.ts— 可直接运行的冒烟示例,针对本项目http://localhost:1420。
references/
webview-api.md—Bun.WebView完整 API 精简参考(构造、方法、后端、事件、注意事项)。
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

