enbu

日本語版 README

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.

A simple E2E testing framework for web browsers. Define test flows in YAML format and leverage the powerful browser automation capabilities of agent-browser.

Features

• Readable YAML step definitions - Write tests in a simple, human-readable format
• Semantic element selection - Locate elements by text, ARIA roles, labels, etc.
• Auto-wait - Automatically waits for elements to appear (no explicit sleeps needed)
• Headless/Headed support - Run tests in CI/CD or debug visually
• Debug on failure - Keep browser state open after test failures for debugging (you can even ask AI to investigate)
• agent-browser integration - Powered by a fast, Rust-based browser automation engine

Prerequisites

You must have agent-browser installed.

# Install agent-browser (required)
npm install -g agent-browser

Installation

npm install -g enbu
# or
npx enbu

Quick Start

1. Initialize Your Project

npx enbu init

This creates a .enbuflow/ directory with sample flows.

2. Create a Flow

.enbuflow/login.enbu.yaml:

# Login flow test
steps:
  - open: https://example.com/login
  - click: Login
  - fill:
      selector: Email
      value: [email protected]
  - fill:
      selector: Password
      value: password123
  - click: Submit
  - assertVisible: Dashboard

3. Run Tests

# Run all flows
npx enbu

# Run a specific flow
npx enbu .enbuflow/login.enbu.yaml

Command Reference

Open Page

steps:
  - open: https://example.com

Click

steps:
  # Semantic selector (text, label, ARIA role, etc.)
  - click: Login

  # CSS selector
  - click: "#submit-button"
  - click: "[data-testid='add-to-cart']"

Text Input

steps:
  # fill: Clear input field then type
  - fill:
      selector: Username
      value: John Doe

  # type: Append to existing text
  - type:
      selector: Search box
      value: Additional text

Key Press

steps:
  # Press Enter key
  - press: Enter

  # Press Tab key
  - press: Tab

Assertions

steps:
  # Assert element is visible
  - assertVisible: Login successful

  # Assert element is not visible
  - assertNotVisible: Error

  # Assert element is enabled
  - assertEnabled: Submit button

  # Assert checkbox is checked
  - assertChecked: Accept terms

  # Assert checkbox is not checked
  - assertChecked:
      selector: Optional feature
      checked: false

Screenshot

steps:
  # Regular screenshot
  - screenshot: ./screenshots/result.png

  # Full-page screenshot
  - screenshot:
      path: ./screenshots/fullpage.png
      full: true

Snapshot (for debugging)

steps:
  - snapshot: {}

Captures the accessibility tree of the current page. Useful for debugging element selection.

Scroll

steps:
  # Scroll by direction
  - scroll:
      direction: down
      amount: 500

  # Scroll element into view
  - scrollIntoView: Footer

Wait

steps:
  # Wait milliseconds
  - wait: 2000

  # Wait for element to be visible
  - wait:
      selector: "#loading-complete"

  # Wait for text to appear
  - wait:
      text: Loading complete

  # Wait for URL to change
  - wait:
      url: /dashboard

  # Wait for page load state
  - wait:
      load: networkidle

JavaScript Execution

steps:
  - eval: document.title

  # Multi-line
  - eval: |
      const element = document.querySelector('#result');
      return element.textContent;

Documentation

Command Reference

For a complete reference of all available commands and their options, see docs/reference.md.

This auto-generated document includes detailed usage examples for all 17+ supported commands across categories:

• Navigation: open, scroll, scrollIntoView
• Interaction: click, hover, press
• Input: type, fill, select
• Wait: wait (with multiple strategies)
• Capture: screenshot
• Assertion: assertVisible, assertNotVisible, assertEnabled, assertChecked
• Other: eval

Examples

The example/ directory contains working examples demonstrating all enbu commands organized by category:

• simple (port 3000) - Basic navigation and assertions
• navigation (port 3010) - Page navigation, clicks, and hover
• form-input (port 3020) - Text input, key presses, and select boxes
• scroll (port 3030) - Scrolling and scroll-into-view
• utility (port 3040) - Wait, screenshot, snapshot, and JavaScript execution
• assertions (port 3050) - All assertion commands

Each example includes a working Express server and .enbuflow/ test files. See example/README.md for how to run them.

Environment Variables

You can use environment variables in your flows:

steps:
  - fill:
      selector: Password
      value: ${PASSWORD}

Ways to Specify Environment Variables

CLI Arguments

npx enbu --env PASSWORD=secret123

Define in YAML

.enbuflow/login.enbu.yaml:

env:
  BASE_URL: https://staging.example.com
steps:
  - open: ${BASE_URL}/login

CLI Options

npx enbu [options] [flow-files...]

Options:
  --headed          Show browser while running (default: headless)
  --env KEY=VALUE   Set environment variable (can be used multiple times)
  --timeout <ms>    Default timeout (default: 30000)
  --screenshot      Save screenshot on failure
  --bail            Stop on first failure
  --session <name>  Specify agent-browser session name
  --parallel <N>    Run N flows in parallel
  -v, --verbose     Output detailed logs
  -h, --help        Show help
  -V, --version     Show version

Directory Structure

your-project/
├── .enbuflow/
│   ├── login.enbu.yaml
│   ├── checkout.enbu.yaml
│   └── shared/
│       └── auth.enbu.yaml
└── package.json

CI/CD Integration

GitHub Actions

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 }}

License

MIT