electrobun-kitchen-sink

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Electrobun Kitchen Sink

The Kitchen Sink is Electrobun's integration test app. It contains automated and interactive tests for every Electrobun API, plus standalone playground windows for manual exploration.

Kitchen Sink 是 Electrobun 的集成测试应用。它包含针对每个 Electrobun API 的自动化测试和交互式测试，以及用于手动探索的独立 playground 窗口。

Project Layout

项目结构

kitchen/
├── scripts/
│   ├── generate-manifest.ts   # static parser → feature-manifest.json
│   └── validate-manifest.ts   # consistency checks
├── src/
│   ├── bun/index.ts           # Electrobun bun-side entrypoint
│   ├── generated/
│   │   ├── manifest-types.ts  # TypeScript types for the manifest
│   │   └── feature-manifest.json  # generated feature index
│   ├── test-framework/        # test executor & result types
│   ├── test-runner/           # test runner UI (views://test-runner/)
│   ├── test-harness/          # webview used by automated tests
│   ├── tests/
│   │   ├── index.ts           # aggregates all suites
│   │   ├── *.test.ts          # automated test suites
│   │   └── interactive/       # interactive test suites
│   └── playgrounds/           # standalone feature demo windows
└── electrobun.config.ts

kitchen/
├── scripts/
│   ├── generate-manifest.ts   # static parser → feature-manifest.json
│   └── validate-manifest.ts   # consistency checks
├── src/
│   ├── bun/index.ts           # Electrobun bun-side entrypoint
│   ├── generated/
│   │   ├── manifest-types.ts  # TypeScript types for the manifest
│   │   └── feature-manifest.json  # generated feature index
│   ├── test-framework/        # test executor & result types
│   ├── test-runner/           # test runner UI (views://test-runner/)
│   ├── test-harness/          # webview used by automated tests
│   ├── tests/
│   │   ├── index.ts           # aggregates all suites
│   │   ├── *.test.ts          # automated test suites
│   │   └── interactive/       # interactive test suites
│   └── playgrounds/           # standalone feature demo windows
└── electrobun.config.ts

Running the Kitchen Sink

运行 Kitchen Sink

bash

cd kitchen && bun install

bash

cd kitchen && bun install

Dev mode — opens test runner window

electrobun dev

Watch mode — auto-rebuilds on file change

electrobun dev --watch

Auto-run all automated tests and exit (CI / headless)

AUTO_RUN=1 electrobun dev

Run a single test by name

AUTO_RUN_TEST_NAME="Window creation with URL" electrobun dev


Exit codes: `0` = all pass, `1` = any failure.

AUTO_RUN_TEST_NAME="Window creation with URL" electrobun dev


退出码：`0` = 全部通过，`1` = 存在任何失败。

Feature Manifest

Feature Manifest（功能清单）

Generated at

kitchen/src/generated/feature-manifest.json

. Each entry:

jsonc

{
  "id": "window-creation-with-url",         // stable slug
  "title": "Window creation with URL",      // human-readable
  "category": "BrowserWindow",              // API grouping
  "description": "Test creating a window with a URL",
  "interactive": false,                     // true = requires human input
  "testFile": "src/tests/window.test.ts",   // source location
  "playgroundRoute": null,                  // e.g. "playgrounds/clipboard/index.html"
  "apiSurface": ["BrowserWindow"],          // Electrobun APIs exercised
  "uiSelectors": [],                        // CSS selectors used in playground
  "platformCaveats": []                     // e.g. ["requires CEF renderer"]
}

生成文件位于

kitchen/src/generated/feature-manifest.json

。每个条目如下：

jsonc

{
  "id": "window-creation-with-url",         // stable slug
  "title": "Window creation with URL",      // human-readable
  "category": "BrowserWindow",              // API grouping
  "description": "Test creating a window with a URL",
  "interactive": false,                     // true = requires human input
  "testFile": "src/tests/window.test.ts",   // source location
  "playgroundRoute": null,                  // e.g. "playgrounds/clipboard/index.html"
  "apiSurface": ["BrowserWindow"],          // Electrobun APIs exercised
  "uiSelectors": [],                        // CSS selectors used in playground
  "platformCaveats": []                     // e.g. ["requires CEF renderer"]
}

Regenerate / Validate

重新生成 / 验证

bash

cd kitchen
npx tsx scripts/generate-manifest.ts   # parse defineTest() calls, write manifest
npx tsx scripts/validate-manifest.ts   # check all tests have manifest entries, no dups

Generator does static analysis only — no Electrobun runtime required.

bash

cd kitchen
npx tsx scripts/generate-manifest.ts   # parse defineTest() calls, write manifest
npx tsx scripts/validate-manifest.ts   # check all tests have manifest entries, no dups

生成器仅执行静态分析——无需 Electrobun 运行时。

Test Suites

测试套件

Automated (run unattended)

自动化（无人值守运行）

Suite	Key APIs
RPC	BrowserView.defineRPC, Electroview.defineRPC
BrowserWindow	new BrowserWindow, all lifecycle methods
Navigation	setNavigationRules, will-navigate, did-navigate
Utils	clipboard, paths, openFileDialog, showNotification
Screen	getPrimaryDisplay, getAllDisplays, getCursorScreenPoint
Session	Session.fromPartition, cookies
Events	Electrobun.events.on (all global events)
Preload	preload script injection
Updater	checkForUpdate, downloadUpdate, applyUpdate
Sandbox	sandbox: true isolation
Tray	new Tray, setMenu, tray-clicked
WGPU FFI	WGPUBridge low-level FFI
WGPU Adapter	GpuWindow, WGPUView adapter layer
Babylon Adapter	BabylonJS WebGPU integration
WGPU Adapter Extended	extended WGPU surface coverage

套件	关键 API
RPC	BrowserView.defineRPC、Electroview.defineRPC
BrowserWindow	new BrowserWindow、所有生命周期方法
Navigation	setNavigationRules、will-navigate、did-navigate
Utils	剪贴板、路径、openFileDialog、showNotification
Screen	getPrimaryDisplay、getAllDisplays、getCursorScreenPoint
Session	Session.fromPartition、cookies
Events	Electrobun.events.on（所有全局事件）
Preload	preload 脚本注入
Updater	checkForUpdate、downloadUpdate、applyUpdate
Sandbox	sandbox: true 隔离
Tray	new Tray、setMenu、tray-clicked
WGPU FFI	WGPUBridge 低层级 FFI
WGPU Adapter	GpuWindow、WGPUView 适配器层
Babylon Adapter	BabylonJS WebGPU 集成
WGPU Adapter Extended	扩展的 WGPU surface 覆盖测试

Interactive (require human)

交互式（需要人工操作）

Suite	Feature area
Dialogs	openFileDialog, showMessageBox
Tray	Tray visibility, icon, menu
Shortcuts	GlobalShortcut register/unregister
Webview Tag	`<electrobun-webview>` masks, passthrough, navigation
Clipboard	clipboardRead/WriteText/Image
Menus	ApplicationMenu, ContextMenu
Window Events	move, resize, blur, focus events
Chromeless	titleBarStyle: hidden, draggable regions
Multiwindow CEF	CEF renderer multi-window
Quit test	before-quit lifecycle
Webview settings	renderer options, sandbox
Webview cleanup	view lifecycle and removal
WGPU View	WGPUView interactive
WGPU Tag	`<wgpu-view>` HTML tag
Fullsize frame repro	window frame edge cases

套件	功能领域
Dialogs	openFileDialog、showMessageBox
Tray	Tray 可见性、图标、菜单
Shortcuts	GlobalShortcut 注册/注销
Webview Tag	`<electrobun-webview>` 遮罩、穿透、导航
Clipboard	clipboardRead/WriteText/Image
Menus	ApplicationMenu、ContextMenu
Window Events	move、resize、blur、focus 事件
Chromeless	titleBarStyle: hidden、可拖动区域
Multiwindow CEF	CEF renderer 多窗口
Quit test	before-quit 生命周期
Webview settings	renderer 选项、sandbox
Webview cleanup	view 生命周期和移除
WGPU View	WGPUView 交互测试
WGPU Tag	`<wgpu-view>` HTML 标签
Fullsize frame repro	全尺寸 frame 问题复现

Test Runner UI — CSS Selectors

Test Runner UI — CSS 选择器

Main window:

views://test-runner/index.html

主窗口：

views://test-runner/index.html

Controls

控件

Selector	Action
`#btn-run-all`	`runAllAutomated()` — runs all non-interactive tests
`#btn-run-interactive`	`runInteractiveTests()`
`.run-btn[data-test-id]`	`runTest({ testId })` — run one test
`#test-search`	Fuzzy filter by name/category/description
`#update-btn`	`applyUpdate()`
`#update-history-toggle`	Toggle update status history panel
`#update-history-clear`	`clearUpdateStatusHistory()`

选择器	操作
`#btn-run-all`	`runAllAutomated()` ——运行所有非交互式测试
`#btn-run-interactive`	`runInteractiveTests()`
`.run-btn[data-test-id]`	`runTest({ testId })` ——运行单个测试
`#test-search`	按名称、分类或描述进行模糊筛选
`#update-btn`	`applyUpdate()`
`#update-history-toggle`	切换更新状态历史面板
`#update-history-clear`	`clearUpdateStatusHistory()`

Status elements

状态元素

Selector	Shows
`#total-count`	Total test count
`#passed-count`	Passed
`#failed-count`	Failed
`#pending-count`	Pending/not-run
`#test-list`	Category groups + test cards
`#search-meta`	Total or filtered count

选择器	显示内容
`#total-count`	测试总数
`#passed-count`	已通过
`#failed-count`	失败
`#pending-count`	待运行/未运行
`#test-list`	分类组和测试卡片
`#search-meta`	总数或筛选后的数量

Interactive modal

交互式模态框

Selector	Purpose
`#interactive-modal`	Modal container
`#modal-title`	Test name
`#modal-instructions`	Instructions text
`#btn-start`	`submitReady({ testId })`
`#btn-pass`	`submitVerification({ testId, action: 'pass' })`
`#btn-fail`	`submitVerification({ testId, action: 'fail' })`
`#btn-retest`	`submitVerification({ testId, action: 'retest' })`
`#notes-input`	Optional notes

选择器	用途
`#interactive-modal`	模态框容器
`#modal-title`	测试名称
`#modal-instructions`	说明文本
`#btn-start`	`submitReady({ testId })`
`#btn-pass`	`submitVerification({ testId, action: 'pass' })`
`#btn-fail`	`submitVerification({ testId, action: 'fail' })`
`#btn-retest`	`submitVerification({ testId, action: 'retest' })`
`#notes-input`	可选备注

Bun↔UI RPC Contract

Bun↔UI RPC 契约

Requests (bun exposes to UI)

请求（bun 暴露给 UI）

```
getTests()
```
→ test list
```
runTest({ testId })
```
→ run one test
```
runAllAutomated()
```
→ run all automated
```
runInteractiveTests()
```
→ start interactive sequence

submitInteractiveResult({ testId, passed, notes })

→ submit result

```
submitReady({ testId })
```
→ signal ready for interactive step

submitVerification({ testId, action, notes })

→ pass/fail/retest

```
applyUpdate()
```
→ apply downloaded update

getUpdateStatusHistory()

clearUpdateStatusHistory()

getTestRunnerPreferences()

setTestRunnerPreferences({ searchQuery })

```
getTests()
```
→ 测试列表
```
runTest({ testId })
```
→ 运行单个测试
```
runAllAutomated()
```
→ 运行所有自动化测试
```
runInteractiveTests()
```
→ 启动交互式测试序列

submitInteractiveResult({ testId, passed, notes })

→ 提交结果

```
submitReady({ testId })
```
→ 发出交互步骤已准备就绪的信号

submitVerification({ testId, action, notes })

→ 通过/失败/重测

```
applyUpdate()
```
→ 应用已下载的更新

getUpdateStatusHistory()

clearUpdateStatusHistory()

getTestRunnerPreferences()

setTestRunnerPreferences({ searchQuery })

→ 获取/设置测试运行器首选项

Messages (bun sends to UI)

消息（bun 发送给 UI）

```
testStarted
```
— test execution began
```
testCompleted
```
— result with pass/fail/duration
```
testLog
```
— log line
```
allCompleted
```
— all tests done
```
interactiveWaiting
```
— waiting for user to click Start
```
interactiveReady
```
— user ready, perform the action
```
interactiveVerify
```
— show pass/fail/retest controls
```
buildConfig
```
— app metadata
```
updateStatus
```
/
```
updateStatusEntry
```
— updater state

```
testStarted
```
——测试执行已开始
```
testCompleted
```
——包含通过/失败状态和耗时的结果
```
testLog
```
——日志行
```
allCompleted
```
——所有测试已完成
```
interactiveWaiting
```
——等待用户点击“开始”
```
interactiveReady
```
——用户已准备就绪，请执行操作
```
interactiveVerify
```
——显示通过/失败/重测控件
```
buildConfig
```
——应用元数据
```
updateStatus
```
/
```
updateStatusEntry
```
——更新器状态

Interactive Test Flow (Two-Step)

交互式测试流程（两步）

1. User clicks Open on an interactive test
2. Runner shows modal: instructions + #btn-start
3. User reads instructions, clicks Start → submitReady()
4. A secondary playground window opens (bun-side)
5. User performs the described action in that window
6. Modal shows: #btn-pass, #btn-fail, #btn-retest
7. User marks result → submitVerification()
8. Modal closes, result recorded

1. User clicks Open on an interactive test
2. Runner shows modal: instructions + #btn-start
3. User reads instructions, clicks Start → submitReady()
4. A secondary playground window opens (bun-side)
5. User performs the described action in that window
6. Modal shows: #btn-pass, #btn-fail, #btn-retest
7. User marks result → submitVerification()
8. Modal closes, result recorded

Consuming the Manifest (agent usage)

使用 Manifest（agent 用法）

bash

undefined

bash

undefined

Read the manifest

cat kitchen/src/generated/feature-manifest.json

Filter: automated tests only

jq '[.[] | select(.interactive == false)]' feature-manifest.json

Filter: tests for a specific API

jq '[.[] | select(.apiSurface | contains(["BrowserWindow"]))]' feature-manifest.json

Map test to source file

jq '.[] | select(.id == "window-creation-with-url") | .testFile' feature-manifest.json

undefined

jq '.[] | select(.id == "window-creation-with-url") | .testFile' feature-manifest.json

undefined

Playground Windows

Playground 窗口

Each interactive suite opens a dedicated playground window. Key ones:

Playground	URL	Key Controls
File dialog	`views://playgrounds/file-dialog/`	`#openDialogBtn` , `#result` , `#history`
App menu	`views://playgrounds/application-menu/`	Sets app menu via RPC
Context menu	`views://playgrounds/context-menu/`	Shows context menu via RPC
Webview tag	`views://playgrounds/webviewtag/`	masks, passthrough, navigation
Session/partition	`views://playgrounds/session/`	Compares cross-partition localStorage
Window events	`views://playgrounds/window-events-*/`	move/resize/blur/focus detection
Clipboard	`views://playgrounds/clipboard/`	read/write text and image
Tray	`views://playgrounds/tray/`	tray icon and menu

每个交互式测试套件都会打开一个专用的 playground 窗口。主要包括：

Playground	URL	关键控件
文件对话框	`views://playgrounds/file-dialog/`	`#openDialogBtn` 、 `#result` 、 `#history`
应用菜单	`views://playgrounds/application-menu/`	通过 RPC 设置应用菜单
上下文菜单	`views://playgrounds/context-menu/`	通过 RPC 显示上下文菜单
Webview 标签	`views://playgrounds/webviewtag/`	遮罩、穿透、导航
Session/分区	`views://playgrounds/session/`	比较跨分区 localStorage
窗口事件	`views://playgrounds/window-events-*/`	检测 move/resize/blur/focus
剪贴板	`views://playgrounds/clipboard/`	读写文本和图像
托盘	`views://playgrounds/tray/`	托盘图标和菜单

Platform Caveats in Tests

测试中的平台注意事项

Zoom: exact zoom level only verified on macOS; defaults to
```
1.0
```
on other platforms
Minimize/unminimize: marked unreliable on some Linux window managers
Session cookies: some tests commented out due to ARM Windows VM crashes
Application menus: intentionally skipped on Linux in interactive tests
Context menus: marked macOS-only in interactive tests
CEF devtools: only available in
```
dev
```
builds, at
```
http://localhost:9222
```

缩放：仅在 macOS 上验证精确的缩放级别；其他平台默认为
```
1.0
```
最小化/取消最小化：在某些 Linux 窗口管理器中被标记为不可靠
Session cookie：部分测试因 ARM Windows 虚拟机崩溃而被注释掉
应用菜单：交互式测试中有意在 Linux 上跳过
上下文菜单：交互式测试中标记为仅支持 macOS
CEF devtools：仅在
```
dev
```
构建中可用，地址为
```
http://localhost:9222
```