enbu 0.4.0 → 0.5.0-beta.1

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 +130 -280
  2. package/dist/main.mjs +209 -135
  3. package/dist/main.mjs.map +1 -1
  4. package/package.json +4 -4
package/README.md CHANGED
@@ -1,262 +1,290 @@
1
1
  # enbu
2
2
 
3
+ [日本語版 README](https://github.com/9wick/enbu/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
+ text: Email
54
56
  value: user@example.com
55
57
  - fill:
56
- selector: パスワード
58
+ text: 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
+ # Text selector
88
+ - click: Login
87
89
 
88
- # CSSセレクタ
89
- - click: "#submit-button"
90
- - click: "[data-testid='add-to-cart']"
90
+ # CSS selector
91
+ - click:
92
+ css: "#submit-button"
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
+ text: Username
102
+ value: John Doe
101
103
 
102
- # type: 既存テキストに追記
104
+ # type: Append to existing text
103
105
  - type:
104
- selector: 検索欄
105
- value: 追加テキスト
106
+ text: 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
+ text: 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
- ### スナップショット（デバッグ用）
155
-
156
- ```yaml
157
- steps:
158
- - snapshot: {}
159
- ```
160
-
161
- 現在のページのアクセシビリティツリーを取得します。デバッグ時に要素の確認に使用します。
162
-
163
- ### スクロール
156
+ ### Scroll
164
157
 
165
158
  ```yaml
166
159
  steps:
167
- # 方向を指定してスクロール
160
+ # Scroll by direction
168
161
  - scroll:
169
162
  direction: down
170
163
  amount: 500
171
164
 
172
- # 要素が見えるまでスクロール
173
- - scrollIntoView: フッター
165
+ # Scroll element into view
166
+ - scrollIntoView: Footer
174
167
  ```
175
168
 
176
- ### 待機
169
+ ### Wait
177
170
 
178
171
  ```yaml
179
172
  steps:
180
- # ミリ秒で待機
173
+ # Wait milliseconds
181
174
  - wait: 2000
182
175
 
183
- # 要素が表示されるまで待機
176
+ # Wait for element to be visible
184
177
  - wait:
185
- selector: "#loading-complete"
178
+ css: "#loading-complete"
186
179
 
187
- # テキストが表示されるまで待機
180
+ # Wait for text to appear
188
181
  - wait:
189
- text: 読み込み完了
182
+ text: Loading complete
190
183
 
191
- # URLが変わるまで待機
184
+ # Wait for URL to change
192
185
  - wait:
193
186
  url: /dashboard
194
187
 
195
- # ページ読み込み状態を待機
188
+ # Wait for page load state
196
189
  - wait:
197
190
  load: networkidle
198
191
  ```
199
192
 
200
- ### JavaScript実行
193
+ ### JavaScript Execution
201
194
 
202
195
  ```yaml
203
196
  steps:
204
197
  - eval: document.title
205
198
 
206
- # 複数行
199
+ # Multi-line
207
200
  - eval: |
208
201
  const element = document.querySelector('#result');
209
202
  return element.textContent;
210
203
  ```
211
204
 
212
- ## 環境変数
205
+ ## Documentation
206
+
207
+ ### Command Reference
208
+
209
+ For a complete reference of all available commands and their options, see [docs/reference.md](./docs/REFERENCE.md).
210
+
211
+ This auto-generated document includes detailed usage examples for all 17+ supported commands across categories:
212
+
213
+ - **Navigation**: `open`, `scroll`, `scrollIntoView`
214
+ - **Interaction**: `click`, `hover`, `press`
215
+ - **Input**: `type`, `fill`, `select`
216
+ - **Wait**: `wait` (with multiple strategies)
217
+ - **Capture**: `screenshot`
218
+ - **Assertion**: `assertVisible`, `assertNotVisible`, `assertEnabled`, `assertChecked`
219
+ - **Other**: `eval`
213
220
 
214
- フロー内で環境変数を使用できます：
221
+ ### Examples
222
+
223
+ The [`example/`](./example/) directory contains working examples demonstrating all enbu commands organized by category:
224
+
225
+ - **[simple](./example/simple/)** (port 3000) - Basic navigation and assertions
226
+ - **[navigation](./example/navigation/)** (port 3010) - Page navigation, clicks, and hover
227
+ - **[form-input](./example/form-input/)** (port 3020) - Text input, key presses, and select boxes
228
+ - **[scroll](./example/scroll/)** (port 3030) - Scrolling and scroll-into-view
229
+ - **[utility](./example/utility/)** (port 3040) - Wait, screenshot, snapshot, and JavaScript execution
230
+ - **[assertions](./example/assertions/)** (port 3050) - All assertion commands
231
+
232
+ Each example includes a working Express server and `.enbuflow/` test files. See [example/README.md](./example/README.md) for how to run them.
233
+
234
+ ## Environment Variables
235
+
236
+ You can use environment variables in your flows:
215
237
 
216
238
  ```yaml
239
+ env:
240
+ PASSWORD: secret123
217
241
  steps:
218
242
  - fill:
219
- selector: パスワード
243
+ text: Password
220
244
  value: ${PASSWORD}
221
245
  ```
222
246
 
223
- ### 環境変数の指定方法
247
+ ### Ways to Specify Environment Variables
224
248
 
225
- #### CLI引数で指定
249
+ #### CLI Arguments
226
250
 
227
251
  ```bash
228
252
  npx enbu --env PASSWORD=secret123
229
253
  ```
230
254
 
231
- #### YAML内で定義
255
+ #### Define in YAML
232
256
 
233
257
  `.enbuflow/login.enbu.yaml`:
234
258
  ```yaml
235
259
  env:
236
260
  BASE_URL: https://staging.example.com
261
+ PASSWORD: secret123
237
262
  steps:
238
263
  - open: ${BASE_URL}/login
264
+ - fill:
265
+ text: Password
266
+ value: ${PASSWORD}
239
267
  ```
240
268
 
241
- ## CLI オプション
269
+ ## CLI Options
242
270
 
243
271
  ```bash
244
272
  npx enbu [options] [flow-files...]
245
273
 
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 バージョンを表示
274
+ Options:
275
+ --headed Show browser while running (default: headless)
276
+ --env KEY=VALUE Set environment variable (can be used multiple times)
277
+ --timeout <ms> Default timeout (default: 30000)
278
+ --screenshot Save screenshot on failure
279
+ --bail Stop on first failure
280
+ --session <name> Specify agent-browser session name
281
+ --parallel <N> Run N flows in parallel
282
+ -v, --verbose Output detailed logs
283
+ -h, --help Show help
284
+ -V, --version Show version
257
285
  ```
258
286
 
259
- ## ディレクトリ構成
287
+ ## Directory Structure
260
288
 
261
289
  ```
262
290
  your-project/
@@ -268,7 +296,7 @@ your-project/
268
296
  └── package.json
269
297
  ```
270
298
 
271
- ## CI/CD統合
299
+ ## CI/CD Integration
272
300
 
273
301
  ### GitHub Actions
274
302
 
@@ -300,184 +328,6 @@ jobs:
300
328
  PASSWORD: ${{ secrets.TEST_PASSWORD }}
301
329
  ```
302
330
 
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
- ## ライセンス
331
+ ## License
482
332
 
483
333
  MIT