enbu 0.2.0 → 0.4.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +182 -253
  2. package/dist/main.mjs +6310 -3951
  3. package/dist/main.mjs.map +1 -1
  4. package/package.json +5 -5
package/README.md CHANGED
@@ -1,163 +1,267 @@
1
1
  # enbu
2
2
 
3
+ [日本語版 README](./README-ja.md)
4
+
3
5
  > In martial arts, Enbu (演武) is a choreographed demonstration where practitioners perform predefined sequences of techniques. Similarly, Enbu lets you define test sequences in YAML and performs them in the browser — a rehearsal before production.
4
6
 
5
- Webブラウザ向けのシンプルなE2Eテストフレームワーク。YAMLベースのフロー定義で、[agent-browser](https://github.com/vercel-labs/agent-browser)のパワフルなブラウザ自動化を活用できます。
7
+ A simple E2E testing framework for web browsers. Define test flows in YAML format and leverage the powerful browser automation capabilities of [agent-browser](https://github.com/vercel-labs/agent-browser).
6
8
 
7
- ## 特徴
9
+ ## Features
8
10
 
9
- - **YAMLベースのフロー定義** - 人間が読みやすいシンプルな形式でテストを記述
10
- - **セマンティックな要素指定** - テキスト、ARIAロール、ラベル等で要素を特定
11
- - **自動待機** - 要素が現れるまで自動的に待機（明示的なsleep不要）
12
- - **agent-browser統合** - Rust製の高速ブラウザ自動化エンジンを利用
11
+ - **Readable YAML step definitions** - Write tests in a simple, human-readable format
12
+ - **Semantic element selection** - Locate elements by text, ARIA roles, labels, etc.
13
+ - **Auto-wait** - Automatically waits for elements to appear (no explicit sleeps needed)
14
+ - **Headless/Headed support** - Run tests in CI/CD or debug visually
15
+ - **Debug on failure** - Keep browser state open after test failures for debugging (you can even ask AI to investigate)
16
+ - **agent-browser integration** - Powered by a fast, Rust-based browser automation engine
13
17
 
14
- ## 前提条件
18
+ ## Prerequisites
15
19
 
16
- agent-browserがインストールされている必要があります。
20
+ You must have agent-browser installed.
17
21
 
18
22
  ```bash
19
- # agent-browserのインストール（事前に必要）
23
+ # Install agent-browser (required)
20
24
  npm install -g agent-browser
21
25
  ```
22
26
 
23
- ## インストール
27
+ ## Installation
24
28
 
25
29
  ```bash
26
30
  npm install -g enbu
27
- # または
31
+ # or
28
32
  npx enbu
29
33
  ```
30
34
 
31
- ## クイックスタート
35
+ ## Quick Start
32
36
 
33
- ### 1. プロジェクトの初期化
37
+ ### 1. Initialize Your Project
34
38
 
35
39
  ```bash
36
40
  npx enbu init
37
41
  ```
38
42
 
39
- これにより `.abflow/` ディレクトリとサンプルフローが作成されます。
43
+ This creates a `.enbuflow/` directory with sample flows.
40
44
 
41
- ### 2. フローの作成
45
+ ### 2. Create a Flow
42
46
 
43
- `.abflow/login.enbu.yaml`:
47
+ `.enbuflow/login.enbu.yaml`:
44
48
 
45
49
  ```yaml
46
- # ログインフローのテスト
50
+ # Login flow test
47
51
  steps:
48
52
  - open: https://example.com/login
49
- - click: "ログイン"
50
- - type:
51
- selector: "メールアドレス"
52
- text: "user@example.com"
53
- - type:
54
- selector: "パスワード"
55
- text: "password123"
56
- - click: "送信"
57
- - assertVisible: "ダッシュボード"
53
+ - click: Login
54
+ - fill:
55
+ selector: Email
56
+ value: user@example.com
57
+ - fill:
58
+ selector: Password
59
+ value: password123
60
+ - click: Submit
61
+ - assertVisible: Dashboard
58
62
  ```
59
63
 
60
- ### 3. テストの実行
64
+ ### 3. Run Tests
61
65
 
62
66
  ```bash
63
- # 全フローを実行
67
+ # Run all flows
64
68
  npx enbu
65
69
 
66
- # 特定のフローを実行
67
- npx enbu .abflow/login.enbu.yaml
70
+ # Run a specific flow
71
+ npx enbu .enbuflow/login.enbu.yaml
68
72
  ```
69
73
 
70
- ## コマンドリファレンス
74
+ ## Command Reference
71
75
 
72
- ### ページを開く
76
+ ### Open Page
73
77
 
74
78
  ```yaml
75
79
  steps:
76
80
  - open: https://example.com
77
81
  ```
78
82
 
79
- ### クリック
83
+ ### Click
80
84
 
81
85
  ```yaml
82
86
  steps:
83
- # セマンティックセレクタ（テキスト、ラベル、ARIAロール等）
84
- - click: "ログイン"
87
+ # Semantic selector (text, label, ARIA role, etc.)
88
+ - click: Login
85
89
 
86
- # CSSセレクタ
87
- - click:
88
- selector: "#submit-button"
90
+ # CSS selector
91
+ - click: "#submit-button"
92
+ - click: "[data-testid='add-to-cart']"
89
93
  ```
90
94
 
91
- ### テキスト入力
95
+ ### Text Input
92
96
 
93
97
  ```yaml
94
98
  steps:
99
+ # fill: Clear input field then type
100
+ - fill:
101
+ selector: Username
102
+ value: John Doe
103
+
104
+ # type: Append to existing text
95
105
  - type:
96
- selector: "ユーザー名"
97
- text: "山田太郎"
106
+ selector: Search box
107
+ value: Additional text
98
108
  ```
99
109
 
100
- ### アサーション
110
+ ### Key Press
101
111
 
102
112
  ```yaml
103
113
  steps:
104
- # 要素が表示されていることを確認
105
- - assertVisible: "ログイン成功"
114
+ # Press Enter key
115
+ - press: Enter
116
+
117
+ # Press Tab key
118
+ - press: Tab
119
+ ```
120
+
121
+ ### Assertions
122
+
123
+ ```yaml
124
+ steps:
125
+ # Assert element is visible
126
+ - assertVisible: Login successful
127
+
128
+ # Assert element is not visible
129
+ - assertNotVisible: Error
106
130
 
107
- # 要素が表示されていないことを確認
108
- - assertNotVisible: "エラー"
131
+ # Assert element is enabled
132
+ - assertEnabled: Submit button
133
+
134
+ # Assert checkbox is checked
135
+ - assertChecked: Accept terms
136
+
137
+ # Assert checkbox is not checked
138
+ - assertChecked:
139
+ selector: Optional feature
140
+ checked: false
109
141
  ```
110
142
 
111
- ### スクリーンショット
143
+ ### Screenshot
112
144
 
113
145
  ```yaml
114
146
  steps:
147
+ # Regular screenshot
115
148
  - screenshot: ./screenshots/result.png
149
+
150
+ # Full-page screenshot
151
+ - screenshot:
152
+ path: ./screenshots/fullpage.png
153
+ full: true
116
154
  ```
117
155
 
118
- ### スナップショット（デバッグ用）
156
+ ### Snapshot (for debugging)
119
157
 
120
158
  ```yaml
121
159
  steps:
122
- - snapshot
160
+ - snapshot: {}
123
161
  ```
124
162
 
125
- 現在のページのアクセシビリティツリーを取得します。デバッグ時に要素の確認に使用します。
163
+ Captures the accessibility tree of the current page. Useful for debugging element selection.
126
164
 
127
- ### JavaScript実行
165
+ ### Scroll
128
166
 
129
167
  ```yaml
130
168
  steps:
131
- - eval: "document.title"
169
+ # Scroll by direction
170
+ - scroll:
171
+ direction: down
172
+ amount: 500
173
+
174
+ # Scroll element into view
175
+ - scrollIntoView: Footer
176
+ ```
177
+
178
+ ### Wait
179
+
180
+ ```yaml
181
+ steps:
182
+ # Wait milliseconds
183
+ - wait: 2000
184
+
185
+ # Wait for element to be visible
186
+ - wait:
187
+ selector: "#loading-complete"
132
188
 
133
- # 複数行
189
+ # Wait for text to appear
190
+ - wait:
191
+ text: Loading complete
192
+
193
+ # Wait for URL to change
194
+ - wait:
195
+ url: /dashboard
196
+
197
+ # Wait for page load state
198
+ - wait:
199
+ load: networkidle
200
+ ```
201
+
202
+ ### JavaScript Execution
203
+
204
+ ```yaml
205
+ steps:
206
+ - eval: document.title
207
+
208
+ # Multi-line
134
209
  - eval: |
135
210
  const element = document.querySelector('#result');
136
211
  return element.textContent;
137
212
  ```
138
213
 
139
- ## 環境変数
214
+ ## Documentation
215
+
216
+ ### Command Reference
217
+
218
+ For a complete reference of all available commands and their options, see [docs/reference.md](./docs/REFERENCE.md).
219
+
220
+ This auto-generated document includes detailed usage examples for all 17+ supported commands across categories:
140
221
 
141
- フロー内で環境変数を使用できます：
222
+ - **Navigation**: `open`, `scroll`, `scrollIntoView`
223
+ - **Interaction**: `click`, `hover`, `press`
224
+ - **Input**: `type`, `fill`, `select`
225
+ - **Wait**: `wait` (with multiple strategies)
226
+ - **Capture**: `screenshot`
227
+ - **Assertion**: `assertVisible`, `assertNotVisible`, `assertEnabled`, `assertChecked`
228
+ - **Other**: `eval`
229
+
230
+ ### Examples
231
+
232
+ The [`example/`](./example/) directory contains working examples demonstrating all enbu commands organized by category:
233
+
234
+ - **[simple](./example/simple/)** (port 3000) - Basic navigation and assertions
235
+ - **[navigation](./example/navigation/)** (port 3010) - Page navigation, clicks, and hover
236
+ - **[form-input](./example/form-input/)** (port 3020) - Text input, key presses, and select boxes
237
+ - **[scroll](./example/scroll/)** (port 3030) - Scrolling and scroll-into-view
238
+ - **[utility](./example/utility/)** (port 3040) - Wait, screenshot, snapshot, and JavaScript execution
239
+ - **[assertions](./example/assertions/)** (port 3050) - All assertion commands
240
+
241
+ Each example includes a working Express server and `.enbuflow/` test files. See [example/README.md](./example/README.md) for how to run them.
242
+
243
+ ## Environment Variables
244
+
245
+ You can use environment variables in your flows:
142
246
 
143
247
  ```yaml
144
248
  steps:
145
- - type:
146
- selector: "パスワード"
147
- text: ${PASSWORD}
249
+ - fill:
250
+ selector: Password
251
+ value: ${PASSWORD}
148
252
  ```
149
253
 
150
- ### 環境変数の指定方法
254
+ ### Ways to Specify Environment Variables
151
255
 
152
- #### CLI引数で指定
256
+ #### CLI Arguments
153
257
 
154
258
  ```bash
155
259
  npx enbu --env PASSWORD=secret123
156
260
  ```
157
261
 
158
- #### YAML内で定義
262
+ #### Define in YAML
159
263
 
160
- `.abflow/login.enbu.yaml`:
264
+ `.enbuflow/login.enbu.yaml`:
161
265
  ```yaml
162
266
  env:
163
267
  BASE_URL: https://staging.example.com
@@ -165,26 +269,29 @@ steps:
165
269
  - open: ${BASE_URL}/login
166
270
  ```
167
271
 
168
- ## CLI オプション
272
+ ## CLI Options
169
273
 
170
274
  ```bash
171
275
  npx enbu [options] [flow-files...]
172
276
 
173
- オプション:
174
- --headed ブラウザを表示して実行（デフォルト: ヘッドレス）
175
- --env KEY=VALUE 環境変数を設定
176
- --timeout <ms> デフォルトタイムアウト（デフォルト: 30000）
177
- --screenshot 失敗時にスクリーンショットを保存
178
- -v, --verbose 詳細なログを出力
179
- -h, --help ヘルプを表示
180
- --version バージョンを表示
277
+ Options:
278
+ --headed Show browser while running (default: headless)
279
+ --env KEY=VALUE Set environment variable (can be used multiple times)
280
+ --timeout <ms> Default timeout (default: 30000)
281
+ --screenshot Save screenshot on failure
282
+ --bail Stop on first failure
283
+ --session <name> Specify agent-browser session name
284
+ --parallel <N> Run N flows in parallel
285
+ -v, --verbose Output detailed logs
286
+ -h, --help Show help
287
+ -V, --version Show version
181
288
  ```
182
289
 
183
- ## ディレクトリ構成
290
+ ## Directory Structure
184
291
 
185
292
  ```
186
293
  your-project/
187
- ├── .abflow/
294
+ ├── .enbuflow/
188
295
  │ ├── login.enbu.yaml
189
296
  │ ├── checkout.enbu.yaml
190
297
  │ └── shared/
@@ -192,7 +299,7 @@ your-project/
192
299
  └── package.json
193
300
  ```
194
301
 
195
- ## CI/CD統合
302
+ ## CI/CD Integration
196
303
 
197
304
  ### GitHub Actions
198
305
 
@@ -224,184 +331,6 @@ jobs:
224
331
  PASSWORD: ${{ secrets.TEST_PASSWORD }}
225
332
  ```
226
333
 
227
- ## agent-browser コマンド対応表
228
-
229
- 本ツールは [agent-browser](https://github.com/vercel-labs/agent-browser) のコマンドをYAMLから利用できます。以下は対応状況です。
230
-
231
- ### Core Commands
232
-
233
- | agent-browser | 対応 | YAML記法 |
234
- |---------------|:----:|----------|
235
- | `open <url>` | ✅ | `- open: <url>` |
236
- | `click <selector>` | ✅ | `- click: <selector>` |
237
- | `dblclick <selector>` | ❌ | - |
238
- | `focus <selector>` | ❌ | - |
239
- | `type <selector> <text>` | ✅ | `- type: { selector: <selector>, value: <text> }` |
240
- | `fill <selector> <text>` | ✅ | `- fill: { selector: <selector>, value: <text> }` |
241
- | `press <key>` | ✅ | `- press: <key>` |
242
- | `keydown <key>` | ❌ | - |
243
- | `keyup <key>` | ❌ | - |
244
- | `hover <selector>` | ✅ | `- hover: <selector>` |
245
- | `select <selector> <value>` | ✅ | `- select: { selector: <selector>, value: <value> }` |
246
- | `check <selector>` | ❌ | - |
247
- | `uncheck <selector>` | ❌ | - |
248
- | `scroll <direction> [px]` | ✅ | `- scroll: { direction: up\|down\|left\|right, amount: <px> }` |
249
- | `scrollintoview <selector>` | ✅ | `- scrollIntoView: <selector>` |
250
- | `drag <source> <target>` | ❌ | - |
251
- | `upload <selector> <files>` | ❌ | - |
252
- | `screenshot [path]` | ✅ | `- screenshot: <path>` |
253
- | `pdf <path>` | ❌ | - |
254
- | `snapshot` | ✅ | `- snapshot` |
255
- | `eval <js>` | ✅ | `- eval: <script>` |
256
- | `close` | ❌ | - |
257
-
258
- ### Get Info
259
-
260
- | agent-browser | 対応 | YAML記法 |
261
- |---------------|:----:|----------|
262
- | `get text <selector>` | ❌ | - |
263
- | `get html <selector>` | ❌ | - |
264
- | `get value <selector>` | ❌ | - |
265
- | `get attr <selector> <attr>` | ❌ | - |
266
- | `get title` | ❌ | - |
267
- | `get url` | ❌ | - |
268
- | `get count <selector>` | ❌ | - |
269
- | `get box <selector>` | ❌ | - |
270
-
271
- ### Check State
272
-
273
- | agent-browser | 対応 | YAML記法 |
274
- |---------------|:----:|----------|
275
- | `is visible <selector>` | ✅ | `- assertVisible: <selector>` |
276
- | `is enabled <selector>` | ✅ | `- assertEnabled: <selector>` |
277
- | `is checked <selector>` | ✅ | `- assertChecked: <selector>` |
278
-
279
- ### Find Elements
280
-
281
- | agent-browser | 対応 | YAML記法 |
282
- |---------------|:----:|----------|
283
- | `find role <role> <action> [value]` | ❌ | - |
284
- | `find text <text> <action>` | ❌ | - |
285
- | `find label <label> <action> [value]` | ❌ | - |
286
- | `find placeholder <placeholder> <action> [value]` | ❌ | - |
287
- | `find alt <text> <action>` | ❌ | - |
288
- | `find title <text> <action>` | ❌ | - |
289
- | `find testid <id> <action> [value]` | ❌ | - |
290
- | `find first <selector> <action> [value]` | ❌ | - |
291
- | `find last <selector> <action> [value]` | ❌ | - |
292
- | `find nth <n> <selector> <action> [value]` | ❌ | - |
293
-
294
- ### Wait
295
-
296
- | agent-browser | 対応 | YAML記法 |
297
- |---------------|:----:|----------|
298
- | `wait <selector>` | ✅ | `- wait: "<selector>"` |
299
- | `wait <ms>` | ✅ | `- wait: <ms>` |
300
- | `wait --text <text>` | ✅ | `- wait: { text: "<text>" }` |
301
- | `wait --url <pattern>` | ✅ | `- wait: { url: "<pattern>" }` |
302
- | `wait --load <state>` | ✅ | `- wait: { load: "<state>" }` |
303
- | `wait --fn <condition>` | ✅ | `- wait: { fn: "<condition>" }` |
304
-
305
- ### Mouse Control
306
-
307
- | agent-browser | 対応 | YAML記法 |
308
- |---------------|:----:|----------|
309
- | `mouse move <x> <y>` | ❌ | - |
310
- | `mouse down [button]` | ❌ | - |
311
- | `mouse up [button]` | ❌ | - |
312
- | `mouse wheel <dy> [dx]` | ❌ | - |
313
-
314
- ### Browser Settings
315
-
316
- | agent-browser | 対応 | YAML記法 |
317
- |---------------|:----:|----------|
318
- | `set viewport <width> <height>` | ❌ | - |
319
- | `set device <name>` | ❌ | - |
320
- | `set geo <lat> <lng>` | ❌ | - |
321
- | `set offline [on\|off]` | ❌ | - |
322
- | `set headers <json>` | ❌ | - |
323
- | `set credentials <user> <pass>` | ❌ | - |
324
- | `set media [dark\|light]` | ❌ | - |
325
-
326
- ### Cookies & Storage
327
-
328
- | agent-browser | 対応 | YAML記法 |
329
- |---------------|:----:|----------|
330
- | `cookies` | ❌ | - |
331
- | `cookies set <name> <value>` | ❌ | - |
332
- | `cookies clear` | ❌ | - |
333
- | `storage local` | ❌ | - |
334
- | `storage local <key>` | ❌ | - |
335
- | `storage local set <key> <value>` | ❌ | - |
336
- | `storage local clear` | ❌ | - |
337
- | `storage session` | ❌ | - |
338
- | `storage session <key>` | ❌ | - |
339
- | `storage session set <key> <value>` | ❌ | - |
340
- | `storage session clear` | ❌ | - |
341
-
342
- ### Network
343
-
344
- | agent-browser | 対応 | YAML記法 |
345
- |---------------|:----:|----------|
346
- | `network route <url>` | ❌ | - |
347
- | `network route <url> --abort` | ❌ | - |
348
- | `network route <url> --body <json>` | ❌ | - |
349
- | `network unroute [url]` | ❌ | - |
350
- | `network requests` | ❌ | - |
351
- | `network requests --filter <pattern>` | ❌ | - |
352
-
353
- ### Tabs & Windows
354
-
355
- | agent-browser | 対応 | YAML記法 |
356
- |---------------|:----:|----------|
357
- | `tab` | ❌ | - |
358
- | `tab new [url]` | ❌ | - |
359
- | `tab <n>` | ❌ | - |
360
- | `tab close [n]` | ❌ | - |
361
- | `window new` | ❌ | - |
362
-
363
- ### Frames
364
-
365
- | agent-browser | 対応 | YAML記法 |
366
- |---------------|:----:|----------|
367
- | `frame <selector>` | ❌ | - |
368
- | `frame main` | ❌ | - |
369
-
370
- ### Dialogs
371
-
372
- | agent-browser | 対応 | YAML記法 |
373
- |---------------|:----:|----------|
374
- | `dialog accept [text]` | ❌ | - |
375
- | `dialog dismiss` | ❌ | - |
376
-
377
- ### Debug
378
-
379
- | agent-browser | 対応 | YAML記法 |
380
- |---------------|:----:|----------|
381
- | `trace start [path]` | ❌ | - |
382
- | `trace stop [path]` | ❌ | - |
383
- | `console` | ❌ | - |
384
- | `console --clear` | ❌ | - |
385
- | `errors` | ❌ | - |
386
- | `errors --clear` | ❌ | - |
387
- | `highlight <selector>` | ❌ | - |
388
- | `state save <path>` | ❌ | - |
389
- | `state load <path>` | ❌ | - |
390
-
391
- ### Navigation
392
-
393
- | agent-browser | 対応 | YAML記法 |
394
- |---------------|:----:|----------|
395
- | `back` | ❌ | - |
396
- | `forward` | ❌ | - |
397
- | `reload` | ❌ | - |
398
-
399
- ### enbu 独自コマンド
400
-
401
- | コマンド | YAML記法 |
402
- |----------|----------|
403
- | assertNotVisible | `- assertNotVisible: <selector>` |
404
-
405
- ## ライセンス
334
+ ## License
406
335
 
407
336
  MIT