enbu 0.4.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 +123 -270
  2. package/dist/main.mjs +68 -68
  3. package/dist/main.mjs.map +1 -1
  4. package/package.json +4 -4
package/README.md CHANGED
@@ -1,234 +1,265 @@
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
- - **Headless/Headed両対応** - CI/CDでの自動実行も、目視でのデバッグも可能
13
- - **失敗時のデバッグ継続** - テスト失敗時にブラウザ状態を保持したままデバッグ開始可能（AIに調査を依頼することも可能）
14
- - **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
15
17
 
16
- ## 前提条件
18
+ ## Prerequisites
17
19
 
18
- agent-browserがインストールされている必要があります。
20
+ You must have agent-browser installed.
19
21
 
20
22
  ```bash
21
- # agent-browserのインストール（事前に必要）
23
+ # Install agent-browser (required)
22
24
  npm install -g agent-browser
23
25
  ```
24
26
 
25
- ## インストール
27
+ ## Installation
26
28
 
27
29
  ```bash
28
30
  npm install -g enbu
29
- # または
31
+ # or
30
32
  npx enbu
31
33
  ```
32
34
 
33
- ## クイックスタート
35
+ ## Quick Start
34
36
 
35
- ### 1. プロジェクトの初期化
37
+ ### 1. Initialize Your Project
36
38
 
37
39
  ```bash
38
40
  npx enbu init
39
41
  ```
40
42
 
41
- これにより `.enbuflow/` ディレクトリとサンプルフローが作成されます。
43
+ This creates a `.enbuflow/` directory with sample flows.
42
44
 
43
- ### 2. フローの作成
45
+ ### 2. Create a Flow
44
46
 
45
47
  `.enbuflow/login.enbu.yaml`:
46
48
 
47
49
  ```yaml
48
- # ログインフローのテスト
50
+ # Login flow test
49
51
  steps:
50
52
  - open: https://example.com/login
51
- - click: ログイン
53
+ - click: Login
52
54
  - fill:
53
- selector: メールアドレス
55
+ selector: Email
54
56
  value: user@example.com
55
57
  - fill:
56
- selector: パスワード
58
+ selector: Password
57
59
  value: password123
58
- - click: 送信
59
- - assertVisible: ダッシュボード
60
+ - click: Submit
61
+ - assertVisible: Dashboard
60
62
  ```
61
63
 
62
- ### 3. テストの実行
64
+ ### 3. Run Tests
63
65
 
64
66
  ```bash
65
- # 全フローを実行
67
+ # Run all flows
66
68
  npx enbu
67
69
 
68
- # 特定のフローを実行
70
+ # Run a specific flow
69
71
  npx enbu .enbuflow/login.enbu.yaml
70
72
  ```
71
73
 
72
- ## コマンドリファレンス
74
+ ## Command Reference
73
75
 
74
- ### ページを開く
76
+ ### Open Page
75
77
 
76
78
  ```yaml
77
79
  steps:
78
80
  - open: https://example.com
79
81
  ```
80
82
 
81
- ### クリック
83
+ ### Click
82
84
 
83
85
  ```yaml
84
86
  steps:
85
- # セマンティックセレクタ（テキスト、ラベル、ARIAロール等）
86
- - click: ログイン
87
+ # Semantic selector (text, label, ARIA role, etc.)
88
+ - click: Login
87
89
 
88
- # CSSセレクタ
90
+ # CSS selector
89
91
  - click: "#submit-button"
90
92
  - click: "[data-testid='add-to-cart']"
91
93
  ```
92
94
 
93
- ### テキスト入力
95
+ ### Text Input
94
96
 
95
97
  ```yaml
96
98
  steps:
97
- # fill: 入力欄をクリアしてから入力
99
+ # fill: Clear input field then type
98
100
  - fill:
99
- selector: ユーザー名
100
- value: 山田太郎
101
+ selector: Username
102
+ value: John Doe
101
103
 
102
- # type: 既存テキストに追記
104
+ # type: Append to existing text
103
105
  - type:
104
- selector: 検索欄
105
- value: 追加テキスト
106
+ selector: Search box
107
+ value: Additional text
106
108
  ```
107
109
 
108
- ### キー入力
110
+ ### Key Press
109
111
 
110
112
  ```yaml
111
113
  steps:
112
- # Enterキーを押す
114
+ # Press Enter key
113
115
  - press: Enter
114
116
 
115
- # Tabキーを押す
117
+ # Press Tab key
116
118
  - press: Tab
117
119
  ```
118
120
 
119
- ### アサーション
121
+ ### Assertions
120
122
 
121
123
  ```yaml
122
124
  steps:
123
- # 要素が表示されていることを確認
124
- - assertVisible: ログイン成功
125
+ # Assert element is visible
126
+ - assertVisible: Login successful
125
127
 
126
- # 要素が表示されていないことを確認
127
- - assertNotVisible: エラー
128
+ # Assert element is not visible
129
+ - assertNotVisible: Error
128
130
 
129
- # 要素が有効であることを確認
130
- - assertEnabled: 送信ボタン
131
+ # Assert element is enabled
132
+ - assertEnabled: Submit button
131
133
 
132
- # チェックボックスがチェックされていることを確認
133
- - assertChecked: 利用規約に同意
134
+ # Assert checkbox is checked
135
+ - assertChecked: Accept terms
134
136
 
135
- # チェックボックスがチェックされていないことを確認
137
+ # Assert checkbox is not checked
136
138
  - assertChecked:
137
- selector: オプション
139
+ selector: Optional feature
138
140
  checked: false
139
141
  ```
140
142
 
141
- ### スクリーンショット
143
+ ### Screenshot
142
144
 
143
145
  ```yaml
144
146
  steps:
145
- # 通常のスクリーンショット
147
+ # Regular screenshot
146
148
  - screenshot: ./screenshots/result.png
147
149
 
148
- # フルページスクリーンショット
150
+ # Full-page screenshot
149
151
  - screenshot:
150
152
  path: ./screenshots/fullpage.png
151
153
  full: true
152
154
  ```
153
155
 
154
- ### スナップショット（デバッグ用）
156
+ ### Snapshot (for debugging)
155
157
 
156
158
  ```yaml
157
159
  steps:
158
160
  - snapshot: {}
159
161
  ```
160
162
 
161
- 現在のページのアクセシビリティツリーを取得します。デバッグ時に要素の確認に使用します。
163
+ Captures the accessibility tree of the current page. Useful for debugging element selection.
162
164
 
163
- ### スクロール
165
+ ### Scroll
164
166
 
165
167
  ```yaml
166
168
  steps:
167
- # 方向を指定してスクロール
169
+ # Scroll by direction
168
170
  - scroll:
169
171
  direction: down
170
172
  amount: 500
171
173
 
172
- # 要素が見えるまでスクロール
173
- - scrollIntoView: フッター
174
+ # Scroll element into view
175
+ - scrollIntoView: Footer
174
176
  ```
175
177
 
176
- ### 待機
178
+ ### Wait
177
179
 
178
180
  ```yaml
179
181
  steps:
180
- # ミリ秒で待機
182
+ # Wait milliseconds
181
183
  - wait: 2000
182
184
 
183
- # 要素が表示されるまで待機
185
+ # Wait for element to be visible
184
186
  - wait:
185
187
  selector: "#loading-complete"
186
188
 
187
- # テキストが表示されるまで待機
189
+ # Wait for text to appear
188
190
  - wait:
189
- text: 読み込み完了
191
+ text: Loading complete
190
192
 
191
- # URLが変わるまで待機
193
+ # Wait for URL to change
192
194
  - wait:
193
195
  url: /dashboard
194
196
 
195
- # ページ読み込み状態を待機
197
+ # Wait for page load state
196
198
  - wait:
197
199
  load: networkidle
198
200
  ```
199
201
 
200
- ### JavaScript実行
202
+ ### JavaScript Execution
201
203
 
202
204
  ```yaml
203
205
  steps:
204
206
  - eval: document.title
205
207
 
206
- # 複数行
208
+ # Multi-line
207
209
  - eval: |
208
210
  const element = document.querySelector('#result');
209
211
  return element.textContent;
210
212
  ```
211
213
 
212
- ## 環境変数
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:
221
+
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
213
231
 
214
- フロー内で環境変数を使用できます：
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:
215
246
 
216
247
  ```yaml
217
248
  steps:
218
249
  - fill:
219
- selector: パスワード
250
+ selector: Password
220
251
  value: ${PASSWORD}
221
252
  ```
222
253
 
223
- ### 環境変数の指定方法
254
+ ### Ways to Specify Environment Variables
224
255
 
225
- #### CLI引数で指定
256
+ #### CLI Arguments
226
257
 
227
258
  ```bash
228
259
  npx enbu --env PASSWORD=secret123
229
260
  ```
230
261
 
231
- #### YAML内で定義
262
+ #### Define in YAML
232
263
 
233
264
  `.enbuflow/login.enbu.yaml`:
234
265
  ```yaml
@@ -238,25 +269,25 @@ steps:
238
269
  - open: ${BASE_URL}/login
239
270
  ```
240
271
 
241
- ## CLI オプション
272
+ ## CLI Options
242
273
 
243
274
  ```bash
244
275
  npx enbu [options] [flow-files...]
245
276
 
246
- オプション:
247
- --headed ブラウザを表示して実行（デフォルト: ヘッドレス）
248
- --env KEY=VALUE 環境変数を設定（複数回指定可）
249
- --timeout <ms> デフォルトタイムアウト（デフォルト: 30000）
250
- --screenshot 失敗時にスクリーンショットを保存
251
- --bail 最初の失敗時にテストを停止
252
- --session <name> agent-browserのセッション名を指定
253
- --parallel <N> N個のフローを並列実行
254
- -v, --verbose 詳細なログを出力
255
- -h, --help ヘルプを表示
256
- -V, --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
257
288
  ```
258
289
 
259
- ## ディレクトリ構成
290
+ ## Directory Structure
260
291
 
261
292
  ```
262
293
  your-project/
@@ -268,7 +299,7 @@ your-project/
268
299
  └── package.json
269
300
  ```
270
301
 
271
- ## CI/CD統合
302
+ ## CI/CD Integration
272
303
 
273
304
  ### GitHub Actions
274
305
 
@@ -300,184 +331,6 @@ jobs:
300
331
  PASSWORD: ${{ secrets.TEST_PASSWORD }}
301
332
  ```
302
333
 
303
- ## agent-browser コマンド対応表
304
-
305
- 本ツールは [agent-browser](https://github.com/vercel-labs/agent-browser) のコマンドをYAMLから利用できます。以下は対応状況です。
306
-
307
- ### Core Commands
308
-
309
- | agent-browser | 対応 | YAML記法 |
310
- |---------------|:----:|----------|
311
- | `open <url>` | ✅ | `- open: <url>` |
312
- | `click <selector>` | ✅ | `- click: <selector>` |
313
- | `dblclick <selector>` | ❌ | - |
314
- | `focus <selector>` | ❌ | - |
315
- | `type <selector> <text>` | ✅ | `- type: { selector: <selector>, value: <value> }` |
316
- | `fill <selector> <text>` | ✅ | `- fill: { selector: <selector>, value: <value> }` |
317
- | `press <key>` | ✅ | `- press: <key>` |
318
- | `keydown <key>` | ❌ | - |
319
- | `keyup <key>` | ❌ | - |
320
- | `hover <selector>` | ✅ | `- hover: <selector>` |
321
- | `select <selector> <value>` | ✅ | `- select: { selector: <selector>, value: <value> }` |
322
- | `check <selector>` | ❌ | - |
323
- | `uncheck <selector>` | ❌ | - |
324
- | `scroll <direction> [px]` | ✅ | `- scroll: { direction: up\|down\|left\|right, amount: <px> }` |
325
- | `scrollintoview <selector>` | ✅ | `- scrollIntoView: <selector>` |
326
- | `drag <source> <target>` | ❌ | - |
327
- | `upload <selector> <files>` | ❌ | - |
328
- | `screenshot [path]` | ✅ | `- screenshot: <path>` または `{ path: <path>, full: true }` |
329
- | `pdf <path>` | ❌ | - |
330
- | `snapshot` | ✅ | `- snapshot: {}` |
331
- | `eval <js>` | ✅ | `- eval: <script>` |
332
- | `close` | ❌ | - |
333
-
334
- ### Get Info
335
-
336
- | agent-browser | 対応 | YAML記法 |
337
- |---------------|:----:|----------|
338
- | `get text <selector>` | ❌ | - |
339
- | `get html <selector>` | ❌ | - |
340
- | `get value <selector>` | ❌ | - |
341
- | `get attr <selector> <attr>` | ❌ | - |
342
- | `get title` | ❌ | - |
343
- | `get url` | ❌ | - |
344
- | `get count <selector>` | ❌ | - |
345
- | `get box <selector>` | ❌ | - |
346
-
347
- ### Check State
348
-
349
- | agent-browser | 対応 | YAML記法 |
350
- |---------------|:----:|----------|
351
- | `is visible <selector>` | ✅ | `- assertVisible: <selector>` |
352
- | `is enabled <selector>` | ✅ | `- assertEnabled: <selector>` |
353
- | `is checked <selector>` | ✅ | `- assertChecked: <selector>` |
354
-
355
- ### Find Elements
356
-
357
- | agent-browser | 対応 | YAML記法 |
358
- |---------------|:----:|----------|
359
- | `find role <role> <action> [value]` | ❌ | - |
360
- | `find text <text> <action>` | ❌ | - |
361
- | `find label <label> <action> [value]` | ❌ | - |
362
- | `find placeholder <placeholder> <action> [value]` | ❌ | - |
363
- | `find alt <text> <action>` | ❌ | - |
364
- | `find title <text> <action>` | ❌ | - |
365
- | `find testid <id> <action> [value]` | ❌ | - |
366
- | `find first <selector> <action> [value]` | ❌ | - |
367
- | `find last <selector> <action> [value]` | ❌ | - |
368
- | `find nth <n> <selector> <action> [value]` | ❌ | - |
369
-
370
- ### Wait
371
-
372
- | agent-browser | 対応 | YAML記法 |
373
- |---------------|:----:|----------|
374
- | `wait <selector>` | ✅ | `- wait: "<selector>"` |
375
- | `wait <ms>` | ✅ | `- wait: <ms>` |
376
- | `wait --text <text>` | ✅ | `- wait: { text: "<text>" }` |
377
- | `wait --url <pattern>` | ✅ | `- wait: { url: "<pattern>" }` |
378
- | `wait --load <state>` | ✅ | `- wait: { load: "<state>" }` |
379
- | `wait --fn <condition>` | ✅ | `- wait: { fn: "<condition>" }` |
380
-
381
- ### Mouse Control
382
-
383
- | agent-browser | 対応 | YAML記法 |
384
- |---------------|:----:|----------|
385
- | `mouse move <x> <y>` | ❌ | - |
386
- | `mouse down [button]` | ❌ | - |
387
- | `mouse up [button]` | ❌ | - |
388
- | `mouse wheel <dy> [dx]` | ❌ | - |
389
-
390
- ### Browser Settings
391
-
392
- | agent-browser | 対応 | YAML記法 |
393
- |---------------|:----:|----------|
394
- | `set viewport <width> <height>` | ❌ | - |
395
- | `set device <name>` | ❌ | - |
396
- | `set geo <lat> <lng>` | ❌ | - |
397
- | `set offline [on\|off]` | ❌ | - |
398
- | `set headers <json>` | ❌ | - |
399
- | `set credentials <user> <pass>` | ❌ | - |
400
- | `set media [dark\|light]` | ❌ | - |
401
-
402
- ### Cookies & Storage
403
-
404
- | agent-browser | 対応 | YAML記法 |
405
- |---------------|:----:|----------|
406
- | `cookies` | ❌ | - |
407
- | `cookies set <name> <value>` | ❌ | - |
408
- | `cookies clear` | ❌ | - |
409
- | `storage local` | ❌ | - |
410
- | `storage local <key>` | ❌ | - |
411
- | `storage local set <key> <value>` | ❌ | - |
412
- | `storage local clear` | ❌ | - |
413
- | `storage session` | ❌ | - |
414
- | `storage session <key>` | ❌ | - |
415
- | `storage session set <key> <value>` | ❌ | - |
416
- | `storage session clear` | ❌ | - |
417
-
418
- ### Network
419
-
420
- | agent-browser | 対応 | YAML記法 |
421
- |---------------|:----:|----------|
422
- | `network route <url>` | ❌ | - |
423
- | `network route <url> --abort` | ❌ | - |
424
- | `network route <url> --body <json>` | ❌ | - |
425
- | `network unroute [url]` | ❌ | - |
426
- | `network requests` | ❌ | - |
427
- | `network requests --filter <pattern>` | ❌ | - |
428
-
429
- ### Tabs & Windows
430
-
431
- | agent-browser | 対応 | YAML記法 |
432
- |---------------|:----:|----------|
433
- | `tab` | ❌ | - |
434
- | `tab new [url]` | ❌ | - |
435
- | `tab <n>` | ❌ | - |
436
- | `tab close [n]` | ❌ | - |
437
- | `window new` | ❌ | - |
438
-
439
- ### Frames
440
-
441
- | agent-browser | 対応 | YAML記法 |
442
- |---------------|:----:|----------|
443
- | `frame <selector>` | ❌ | - |
444
- | `frame main` | ❌ | - |
445
-
446
- ### Dialogs
447
-
448
- | agent-browser | 対応 | YAML記法 |
449
- |---------------|:----:|----------|
450
- | `dialog accept [text]` | ❌ | - |
451
- | `dialog dismiss` | ❌ | - |
452
-
453
- ### Debug
454
-
455
- | agent-browser | 対応 | YAML記法 |
456
- |---------------|:----:|----------|
457
- | `trace start [path]` | ❌ | - |
458
- | `trace stop [path]` | ❌ | - |
459
- | `console` | ❌ | - |
460
- | `console --clear` | ❌ | - |
461
- | `errors` | ❌ | - |
462
- | `errors --clear` | ❌ | - |
463
- | `highlight <selector>` | ❌ | - |
464
- | `state save <path>` | ❌ | - |
465
- | `state load <path>` | ❌ | - |
466
-
467
- ### Navigation
468
-
469
- | agent-browser | 対応 | YAML記法 |
470
- |---------------|:----:|----------|
471
- | `back` | ❌ | - |
472
- | `forward` | ❌ | - |
473
- | `reload` | ❌ | - |
474
-
475
- ### enbu 独自コマンド
476
-
477
- | コマンド | YAML記法 |
478
- |----------|----------|
479
- | assertNotVisible | `- assertNotVisible: <selector>` |
480
-
481
- ## ライセンス
334
+ ## License
482
335
 
483
336
  MIT