enbu 0.1.0 → 0.4.0

package/README.md

@@ -6,9 +6,11 @@ Webブラウザ向けのシンプルなE2Eテストフレームワーク。YAML
 
 ## 特徴
 
-- **YAMLベースのフロー定義** - 人間が読みやすいシンプルな形式でテストを記述
+- **YAMLで読みやすいステップ定義** - 人間が読みやすいシンプルな形式でテストを記述
 - **セマンティックな要素指定** - テキスト、ARIAロール、ラベル等で要素を特定
 - **自動待機** - 要素が現れるまで自動的に待機（明示的なsleep不要）
+- **Headless/Headed両対応** - CI/CDでの自動実行も、目視でのデバッグも可能
+- **失敗時のデバッグ継続** - テスト失敗時にブラウザ状態を保持したままデバッグ開始可能（AIに調査を依頼することも可能）
 - **agent-browser統合** - Rust製の高速ブラウザ自動化エンジンを利用
 
 ## 前提条件
@@ -36,25 +38,25 @@ npx enbu
 npx enbu init
 ```
 
-これにより `.abflow/` ディレクトリとサンプルフローが作成されます。
+これにより `.enbuflow/` ディレクトリとサンプルフローが作成されます。
 
 ### 2. フローの作成
 
-`.abflow/login.enbu.yaml`:
+`.enbuflow/login.enbu.yaml`:
 
 ```yaml
 # ログインフローのテスト
 steps:
   - open: https://example.com/login
-  - click: "ログイン"
-  - type:
-      selector: "メールアドレス"
-      text: "user@example.com"
-  - type:
-      selector: "パスワード"
-      text: "password123"
-  - click: "送信"
-  - assertVisible: "ダッシュボード"
+  - click: ログイン
+  - fill:
+      selector: メールアドレス
+      value: user@example.com
+  - fill:
+      selector: パスワード
+      value: password123
+  - click: 送信
+  - assertVisible: ダッシュボード
 ```
 
 ### 3. テストの実行
@@ -64,7 +66,238 @@ steps:
 npx enbu
 
 # 特定のフローを実行
-npx enbu .abflow/login.enbu.yaml
+npx enbu .enbuflow/login.enbu.yaml
+```
+
+## コマンドリファレンス
+
+### ページを開く
+
+```yaml
+steps:
+  - open: https://example.com
+```
+
+### クリック
+
+```yaml
+steps:
+  # セマンティックセレクタ（テキスト、ラベル、ARIAロール等）
+  - click: ログイン
+
+  # CSSセレクタ
+  - click: "#submit-button"
+  - click: "[data-testid='add-to-cart']"
+```
+
+### テキスト入力
+
+```yaml
+steps:
+  # fill: 入力欄をクリアしてから入力
+  - fill:
+      selector: ユーザー名
+      value: 山田太郎
+
+  # type: 既存テキストに追記
+  - type:
+      selector: 検索欄
+      value: 追加テキスト
+```
+
+### キー入力
+
+```yaml
+steps:
+  # Enterキーを押す
+  - press: Enter
+
+  # Tabキーを押す
+  - press: Tab
+```
+
+### アサーション
+
+```yaml
+steps:
+  # 要素が表示されていることを確認
+  - assertVisible: ログイン成功
+
+  # 要素が表示されていないことを確認
+  - assertNotVisible: エラー
+
+  # 要素が有効であることを確認
+  - assertEnabled: 送信ボタン
+
+  # チェックボックスがチェックされていることを確認
+  - assertChecked: 利用規約に同意
+
+  # チェックボックスがチェックされていないことを確認
+  - assertChecked:
+      selector: オプション
+      checked: false
+```
+
+### スクリーンショット
+
+```yaml
+steps:
+  # 通常のスクリーンショット
+  - screenshot: ./screenshots/result.png
+
+  # フルページスクリーンショット
+  - screenshot:
+      path: ./screenshots/fullpage.png
+      full: true
+```
+
+### スナップショット（デバッグ用）
+
+```yaml
+steps:
+  - snapshot: {}
+```
+
+現在のページのアクセシビリティツリーを取得します。デバッグ時に要素の確認に使用します。
+
+### スクロール
+
+```yaml
+steps:
+  # 方向を指定してスクロール
+  - scroll:
+      direction: down
+      amount: 500
+
+  # 要素が見えるまでスクロール
+  - scrollIntoView: フッター
+```
+
+### 待機
+
+```yaml
+steps:
+  # ミリ秒で待機
+  - wait: 2000
+
+  # 要素が表示されるまで待機
+  - wait:
+      selector: "#loading-complete"
+
+  # テキストが表示されるまで待機
+  - wait:
+      text: 読み込み完了
+
+  # URLが変わるまで待機
+  - wait:
+      url: /dashboard
+
+  # ページ読み込み状態を待機
+  - wait:
+      load: networkidle
+```
+
+### JavaScript実行
+
+```yaml
+steps:
+  - eval: document.title
+
+  # 複数行
+  - eval: |
+      const element = document.querySelector('#result');
+      return element.textContent;
+```
+
+## 環境変数
+
+フロー内で環境変数を使用できます：
+
+```yaml
+steps:
+  - fill:
+      selector: パスワード
+      value: ${PASSWORD}
+```
+
+### 環境変数の指定方法
+
+#### CLI引数で指定
+
+```bash
+npx enbu --env PASSWORD=secret123
+```
+
+#### YAML内で定義
+
+`.enbuflow/login.enbu.yaml`:
+```yaml
+env:
+  BASE_URL: https://staging.example.com
+steps:
+  - open: ${BASE_URL}/login
+```
+
+## CLI オプション
+
+```bash
+npx enbu [options] [flow-files...]
+
+オプション:
+  --headed          ブラウザを表示して実行（デフォルト: ヘッドレス）
+  --env KEY=VALUE   環境変数を設定（複数回指定可）
+  --timeout <ms>    デフォルトタイムアウト（デフォルト: 30000）
+  --screenshot      失敗時にスクリーンショットを保存
+  --bail            最初の失敗時にテストを停止
+  --session <name>  agent-browserのセッション名を指定
+  --parallel <N>    N個のフローを並列実行
+  -v, --verbose     詳細なログを出力
+  -h, --help        ヘルプを表示
+  -V, --version     バージョンを表示
+```
+
+## ディレクトリ構成
+
+```
+your-project/
+├── .enbuflow/
+│   ├── login.enbu.yaml
+│   ├── checkout.enbu.yaml
+│   └── shared/
+│       └── auth.enbu.yaml
+└── package.json
+```
+
+## CI/CD統合
+
+### GitHub Actions
+
+```yaml
+name: E2E Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install agent-browser
+        run: npm install -g agent-browser
+
+      - name: Install browsers
+        run: agent-browser install --with-deps
+
+      - name: Run E2E tests
+        run: npx enbu
+        env:
+          PASSWORD: ${{ secrets.TEST_PASSWORD }}
 ```
 
 ## agent-browser コマンド対応表
@@ -79,8 +312,8 @@ npx enbu .abflow/login.enbu.yaml
 | `click <selector>` | ✅ | `- click: <selector>` |
 | `dblclick <selector>` | ❌ | - |
 | `focus <selector>` | ❌ | - |
-| `type <selector> <text>` | ✅ | `- type: { selector: <selector>, value: <text> }` |
-| `fill <selector> <text>` | ✅ | `- fill: { selector: <selector>, value: <text> }` |
+| `type <selector> <text>` | ✅ | `- type: { selector: <selector>, value: <value> }` |
+| `fill <selector> <text>` | ✅ | `- fill: { selector: <selector>, value: <value> }` |
 | `press <key>` | ✅ | `- press: <key>` |
 | `keydown <key>` | ❌ | - |
 | `keyup <key>` | ❌ | - |
@@ -92,9 +325,9 @@ npx enbu .abflow/login.enbu.yaml
 | `scrollintoview <selector>` | ✅ | `- scrollIntoView: <selector>` |
 | `drag <source> <target>` | ❌ | - |
 | `upload <selector> <files>` | ❌ | - |
-| `screenshot [path]` | ✅ | `- screenshot: <path>` |
+| `screenshot [path]` | ✅ | `- screenshot: <path>` または `{ path: <path>, full: true }` |
 | `pdf <path>` | ❌ | - |
-| `snapshot` | ✅ | `- snapshot` |
+| `snapshot` | ✅ | `- snapshot: {}` |
 | `eval <js>` | ✅ | `- eval: <script>` |
 | `close` | ❌ | - |
 
@@ -123,13 +356,13 @@ npx enbu .abflow/login.enbu.yaml
 
 | agent-browser | 対応 | YAML記法 |
 |---------------|:----:|----------|
-| `find role <role> <action> [value]` | ✅ | セレクタ文字列として利用可能 |
-| `find text <text> <action>` | ✅ | セレクタ文字列として利用可能 |
-| `find label <label> <action> [value]` | ✅ | セレクタ文字列として利用可能 |
-| `find placeholder <placeholder> <action> [value]` | ✅ | セレクタ文字列として利用可能 |
-| `find alt <text> <action>` | ✅ | セレクタ文字列として利用可能 |
-| `find title <text> <action>` | ✅ | セレクタ文字列として利用可能 |
-| `find testid <id> <action> [value]` | ✅ | セレクタ文字列として利用可能 |
+| `find role <role> <action> [value]` | ❌ | - |
+| `find text <text> <action>` | ❌ | - |
+| `find label <label> <action> [value]` | ❌ | - |
+| `find placeholder <placeholder> <action> [value]` | ❌ | - |
+| `find alt <text> <action>` | ❌ | - |
+| `find title <text> <action>` | ❌ | - |
+| `find testid <id> <action> [value]` | ❌ | - |
 | `find first <selector> <action> [value]` | ❌ | - |
 | `find last <selector> <action> [value]` | ❌ | - |
 | `find nth <n> <selector> <action> [value]` | ❌ | - |
@@ -245,157 +478,6 @@ npx enbu .abflow/login.enbu.yaml
 |----------|----------|
 | assertNotVisible | `- assertNotVisible: <selector>` |
 
-## コマンドリファレンス
-
-### ページを開く
-
-```yaml
-steps:
-  - open: https://example.com
-```
-
-### クリック
-
-```yaml
-steps:
-  # セマンティックセレクタ（テキスト、ラベル、ARIAロール等）
-  - click: "ログイン"
-
-  # CSSセレクタ
-  - click:
-      selector: "#submit-button"
-```
-
-### テキスト入力
-
-```yaml
-steps:
-  - type:
-      selector: "ユーザー名"
-      text: "山田太郎"
-```
-
-### アサーション
-
-```yaml
-steps:
-  # 要素が表示されていることを確認
-  - assertVisible: "ログイン成功"
-
-  # 要素が表示されていないことを確認
-  - assertNotVisible: "エラー"
-```
-
-### スクリーンショット
-
-```yaml
-steps:
-  - screenshot: ./screenshots/result.png
-```
-
-### スナップショット（デバッグ用）
-
-```yaml
-steps:
-  - snapshot
-```
-
-現在のページのアクセシビリティツリーを取得します。デバッグ時に要素の確認に使用します。
-
-### JavaScript実行
-
-```yaml
-steps:
-  - eval: "document.title"
-
-  # 複数行
-  - eval: |
-      const element = document.querySelector('#result');
-      return element.textContent;
-```
-
-## 環境変数
-
-フロー内で環境変数を使用できます：
-
-```yaml
-steps:
-  - type:
-      selector: "パスワード"
-      text: ${PASSWORD}
-```
-
-### 環境変数の指定方法
-
-#### CLI引数で指定
-
-```bash
-npx enbu --env PASSWORD=secret123
-```
-
-#### YAML内で定義
-
-`.abflow/login.enbu.yaml`:
-```yaml
-env:
-  BASE_URL: https://staging.example.com
-steps:
-  - open: ${BASE_URL}/login
-```
-
-## CLI オプション
-
-```bash
-npx enbu [options] [flow-files...]
-
-オプション:
-  --headed          ブラウザを表示して実行（デフォルト: ヘッドレス）
-  --env KEY=VALUE   環境変数を設定
-  --timeout <ms>    デフォルトタイムアウト（デフォルト: 30000）
-  --screenshot      失敗時にスクリーンショットを保存
-  -v, --verbose     詳細なログを出力
-  -h, --help        ヘルプを表示
-  --version         バージョンを表示
-```
-
-## ディレクトリ構成
-
-```
-your-project/
-├── .abflow/
-│   ├── login.enbu.yaml
-│   ├── checkout.enbu.yaml
-│   └── shared/
-│       └── auth.enbu.yaml
-└── package.json
-```
-
-## CI/CD統合
-
-### GitHub Actions
-
-```yaml
-name: E2E Tests
-
-on: [push, pull_request]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-
-      - name: Run E2E tests
-        run: npx enbu
-        env:
-          PASSWORD: ${{ secrets.TEST_PASSWORD }}
-```
-
 ## ライセンス
 
 MIT