Vibium ブラウザ自動化 — CLIリファレンス

vibium CLI は、コマンドラインから Chrome を自動化します。ブラウザは初回使用時に自動起動され、デーモンモードでコマンド間の実行が継続されます。

vibium go <url> && vibium map && vibium click @e1 && vibium map

コアワークフロー

すべてのブラウザ自動化は、以下のパターンに従います:

1. ナビゲート: vibium go <url>
2. マップ: vibium map (@e1, @e2 のような要素参照を取得)
3. インタラクト: 参照を使ってクリック、入力、選択など — 例: vibium click @e1
4. 再マップ: ナビゲーション後または DOM 変更後、vibium map で新しい参照を取得

バイナリ解決

コマンドを実行する前に、vibium バイナリのパスを一度解決します:

1. vibium を直接試す (グローバルに npm install -g vibium でインストールされている場合に機能)
2. ./clicker/bin/vibium にフォールバック (開発環境、プロジェクトルート内)
3. ./node_modules/.bin/vibium にフォールバック (ローカル npm インストール)

vibium --help (または解決されたパス) を実行して確認します。その後のすべてのコマンドで解決されたパスを使用します。

Windows での注意: パスにはスラッシュを使用し (例: ./clicker/bin/vibium.exe)、スペースを含むパスは引用符で囲みます。

コマンドチェーン

&& でコマンドを連結して、順序に実行します。最初のエラーでチェーンは停止します:

vibium go https://example.com && vibium map && vibium click @e3 && vibium diff map

チェーンするとき: && を使用してバックツーバックで実行すべきシーケンス (ナビゲート → インタラクト → 検証) に使用します。ステップ間で出力を検査する必要がある場合は、コマンドを個別に実行します。

チェーンしないとき: 前のコマンドの出力の解析に依存するコマンドをチェーンしないでください (例: マップ出力を読んで何をクリックするかを決定する)。先に結果を分析できるように、個別に実行します。

コマンド

発見

• vibium map — @refs で対話的要素をマップ (インタラクト前に推奨)
• vibium map --selector "nav" — マップを CSS 部分木内の要素にスコープ
• vibium diff map — 現在のマップと前回のマップを比較 (変更内容を確認)

ナビゲーション

• vibium go <url> — ページに移動
• vibium back — 履歴をさかのぼる
• vibium forward — 履歴を進める
• vibium reload — 現在のページをリロード
• vibium url — 現在の URL を表示
• vibium title — ページタイトルを表示

コンテンツ読み取り

• vibium text — すべてのページテキストを取得
• vibium text "<selector>" — 特定の要素のテキストを取得
• vibium html — ページ HTML を取得 (--outer で outerHTML を使用)
• vibium find "<selector>" — 要素を検索、@e1 参照を返す (vibium click @e1 でクリック可能)
• vibium find "<selector>" --all — すべてのマッチングする要素を検索 → @e1, @e2, ... (--limit N)
• vibium find text "Sign In" — テキストコンテンツで要素を検索 → @e1
• vibium find label "Email" — ラベルで入力を検索 → @e1
• vibium find placeholder "Search" — プレースホルダーで検索 → @e1
• vibium find testid "submit-btn" — data-testid で検索 → @e1
• vibium find xpath "//div[@class]" — XPath で検索 → @e1
• vibium find alt "Logo" — alt 属性で検索 → @e1
• vibium find title "Settings" — title 属性で検索 → @e1
• vibium find role <role> — ARIA ロールで要素を検索 → @e1 (--name でアクセス可能名フィルター)
• vibium eval "<js>" — JavaScript を実行して結果を表示 (--stdin で stdin から読み取り)
• vibium count "<selector>" — マッチングする要素を数える
• vibium screenshot -o file.png — スクリーンショットをキャプチャ (--full-page, --annotate)
• vibium a11y-tree — アクセシビリティツリー (--everything ですべてのノード)

インタラクション

• vibium click "<selector>" — 要素をクリック (マップからの @ref も受け入れる)
• vibium dblclick "<selector>" — 要素をダブルクリック
• vibium type "<selector>" "<text>" — 入力に入力 (既存の値に追加)
• vibium fill "<selector>" "<text>" — フィールドをクリアして新しいテキストを入力 (値を置換)
• vibium press <key> [selector] — 要素またはフォーカスされた要素でキーを押す
• vibium focus "<selector>" — 要素にフォーカス
• vibium hover "<selector>" — 要素の上にホバー
• vibium scroll [direction] — ページをスクロール (--amount N, --selector)
• vibium scroll into-view "<selector>" — 要素をビューにスクロール (中央揃え)
• vibium keys "<combo>" — キーを押す (Enter, Control+a, Shift+Tab)
• vibium select "<selector>" "<value>" — ドロップダウンオプションを選択
• vibium check "<selector>" — チェックボックス/ラジオをチェック (冪等)
• vibium uncheck "<selector>" — チェックボックスをチェック解除 (冪等)

マウスプリミティブ

• vibium mouse click [x] [y] — 座標または現在の位置をクリック (--button 0|1|2)
• vibium mouse move <x> <y> — マウスを座標に移動
• vibium mouse down — マウスボタンを押す (--button 0|1|2)
• vibium mouse up — マウスボタンを解放 (--button 0|1|2)
• vibium drag "<source>" "<target>" — ある要素から別の要素にドラッグ

要素の状態

• vibium value "<selector>" — input/textarea/select の値を取得
• vibium attr "<selector>" "<attribute>" — HTML 属性値を取得
• vibium is visible "<selector>" — 要素が表示されているかを確認 (true/false)
• vibium is enabled "<selector>" — 要素が有効かを確認 (true/false)
• vibium is checked "<selector>" — チェックボックス/ラジオがチェックされているかを確認 (true/false)
• vibium is actionable "<selector>" — 要素がアクション可能かを確認 (true/false)

待機

• vibium wait "<selector>" — 要素を待機 (--state visible|hidden|attached, --timeout ms)
• vibium wait url "<pattern>" — URL が部分文字列を含むまで待機 (--timeout ms)
• vibium wait load — ページが完全に読み込まれるまで待機 (--timeout ms)
• vibium wait text "<text>" — テキストがページに表示されるまで待機 (--timeout ms)
• vibium wait fn "<expression>" — JS 式が真を返すまで待機 (--timeout ms)
• vibium sleep <ms> — 実行を一時停止 (最大 30000ms)

キャプチャ

• vibium screenshot -o file.png — スクリーンショットをキャプチャ (--full-page, --annotate)
• vibium pdf -o file.pdf — ページを PDF として保存

ダイアログ

• vibium dialog accept [text] — ダイアログを受け入れ (オプションでプロンプトテキスト付き)
• vibium dialog dismiss — ダイアログを閉じる

エミュレーション

• vibium viewport — 現在のビューポート寸法を取得
• vibium viewport <width> <height> — ビューポートサイズを設定 (--dpr でデバイスピクセル比)
• vibium window — OS ブラウザウィンドウの寸法と状態を取得
• vibium window <width> <height> [x] [y] — ウィンドウサイズと位置を設定 (--state)
• vibium media — CSS メディア機能をオーバーライド (--color-scheme, --reduced-motion, --forced-colors, --contrast, --media)
• vibium geolocation <lat> <lng> — 地理的位置情報をオーバーライド (--accuracy)
• vibium content "<html>" — ページ HTML を置換 (--stdin で stdin から読み取り)

フレーム

• vibium frames — ページ上のすべての iframe をリスト
• vibium frame "<nameOrUrl>" — 名前または URL 部分文字列でフレームを検索

ファイルアップロード

• vibium upload "<selector>" <files...> — input[type=file] でファイルを設定

記録

• vibium record start — 記録を開始 (--screenshots, --snapshots, --name)
• vibium record stop — 記録を停止して ZIP を保存 (-o path)

クッキー

• vibium cookies — すべてのクッキーをリスト
• vibium cookies <name> <value> — クッキーを設定
• vibium cookies clear — すべてのクッキーをクリア

ストレージ状態

• vibium storage — クッキー + localStorage + sessionStorage をエクスポート (-o state.json)
• vibium storage restore <path> — JSON ファイルから状態を復元

ダウンロード

• vibium download dir <path> — ダウンロードディレクトリを設定

ページ

• vibium pages — 開いているページをリスト
• vibium page new [url] — 新しいページを開く
• vibium page switch <index|url> — ページを切り替え
• vibium page close [index] — ページを閉じる

デバッグ

• vibium highlight "<selector>" — 要素を視覚的に強調表示 (3秒)

セッション

• vibium start — ローカルブラウザセッションを開始
• vibium start <url> — リモートブラウザに接続して開始
• vibium stop — ブラウザセッションを停止
• vibium daemon start — バックグラウンドブラウザを開始
• vibium daemon status — 実行中かどうかを確認
• vibium daemon stop — デーモンを停止

一般的なパターン

参照ベースのワークフロー (AI 向け推奨)

vibium go https://example.com
vibium map
vibium click @e1
vibium map  # インタラクション後に再マップ

アクションが機能したことを確認

vibium map
vibium click @e3
vibium diff map  # 変更内容を確認

ページを読み取る

vibium go https://example.com && vibium text

フォームを入力 (エンドツーエンド)

vibium go https://example.com/login
vibium map
# マップ出力を確認してフォームフィールドを特定
vibium fill @e1 "user@example.com"
vibium fill @e2 "secret"
vibium click @e3
vibium wait url "/dashboard"
vibium screenshot -o after-login.png

スコープ付きマップ (大規模ページ向け)

vibium map --selector "nav"        # <nav> 内の要素のみマップ
vibium map --selector "#sidebar"   # #sidebar 内の要素のみマップ
vibium map --selector "form"       # フォームコントロールのみマップ

セマンティック検索 (CSS セレクターは不要)

vibium find text "Sign In"             # → @e1 [button] "Sign In"
vibium find label "Email"              # → @e1 [input] placeholder="Email"
vibium click @e1                       # 見つかった要素をクリック
vibium find placeholder "Search..."    # → @e1 [input] placeholder="Search..."
vibium find testid "submit-btn"        # → @e1 [button] "Submit"
vibium find alt "Company logo"         # → @e1 [img] alt="Company logo"
vibium find title "Close"              # → @e1 [button] title="Close"
vibium find xpath "//a[@href='/about']"  # → @e1 [a] "About"

状態永続化を使用した認証

# 一度ログインして状態を保存
vibium go https://app.example.com/login
vibium fill "input[name=email]" "user@example.com"
vibium fill "input[name=password]" "secret"
vibium click "button[type=submit]"
vibium wait url "/dashboard"
vibium storage -o auth.json

# 後のセッションで復元 (ログインをスキップ)
vibium storage restore auth.json
vibium go https://app.example.com/dashboard

構造化データを抽出

vibium go https://example.com
vibium eval "JSON.stringify([...document.querySelectorAll('a')].map(a => ({text: a.textContent.trim(), href: a.href})))"

レンダリングなしでページ構造を確認

vibium go https://example.com && vibium a11y-tree

リモートブラウザ

vibium start ws://remote-host:9515/session
vibium go https://example.com
vibium map
vibium stop

マルチページワークフロー

vibium page new https://docs.example.com
vibium text "h1"
vibium page switch 0

注釈付きスクリーンショット

vibium screenshot -o annotated.png --annotate

要素を検査

vibium attr "a" "href"
vibium value "input[name=email]"
vibium is visible ".modal"

PDF として保存

vibium go https://example.com && vibium pdf -o page.pdf

Eval / JavaScript

vibium eval は、CLI が直接カバーしていない DOM クエリまたは変更のためのエスケープハッチです。

単純な式 — 単一引用符を使用:

vibium eval 'document.title'
vibium eval 'document.querySelectorAll("li").length'

複雑なスクリプト — --stdin をヒアドキュメントで使用:

vibium eval --stdin <<'EOF'
const rows = [...document.querySelectorAll('table tbody tr')];
JSON.stringify(rows.map(r => {
  const cells = r.querySelectorAll('td');
  return { name: cells[0].textContent.trim(), price: cells[1].textContent.trim() };
}));
EOF

JSON 出力 — --json を使用して機械可読出力を取得:

vibium eval --json 'JSON.stringify({url: location.href, title: document.title})'

重要: eval は式の結果を返します。スクリプトが値を返さない場合は、null が表示されます。必ず最後の式が必要なデータに評価されることを確認します。

タイムアウトと待機

すべてのインタラクションコマンド (click, fill, type など) は、ターゲット要素がアクション可能になるまで自動的に待機します。通常は明示的な待機は必要ありません。

以下の場合に明示的な待機を使用します:

• ナビゲーション待機: vibium wait url "/dashboard" — ナビゲートするリンクをクリック後
• コンテンツ待機: vibium wait text "Success" — フォーム送信後、確認を待機
• 要素待機: vibium wait ".modal" — モーダルが表示されるまで待機
• ページロード待機: vibium wait load — スロページへのナビゲーション後
• JS 条件待機: vibium wait fn "window.appReady === true" — アプリ初期化を待機
• 固定遅延 (最後の手段): vibium sleep 2000 — より良いシグナルがない場合のみ (最大 30秒)

すべての wait コマンドは --timeout <ms> を受け入れます (デフォルトはコマンドによって異なります)。

参照ライフサイクル

参照 (@e1, @e2) はページが変更されるときに無効化されます。常に以下の後に再マップします:

• リンクやボタンをクリックしてナビゲート
• フォーム送信
• 動的コンテンツロード (ドロップダウン、モーダル)

グローバルフラグ

フラグ	説明
--headless	ブラウザウィンドウを非表示
--json	JSON として出力
-v, --verbose	デバッグロギング

ヒント

• すべてのクリック/タイプ/ホバー/フィル操作は、要素がアクション可能になるまで自動的に待機
• すべてのセレクター引数は vibium map からの @ref も受け入れ
• インタラクト前に vibium map を使用して対話的要素を発見
• 大規模ページのノイズを減らすために vibium map --selector を使用
• フィールドの値を置換するには vibium fill を、値に追加するには vibium type を使用
• セマンティック要素検索には vibium find text / find label / find testid を使用 (CSS セレクターより信頼性が高い)
• ARIA ロールベースの検索には vibium find role を使用
• ビジュアルレンダリングなしでページ構造を理解するには vibium a11y-tree を使用
• 特定のセクションを読むには vibium text "<selector>" を使用
• インタラクション後の変更を確認するには vibium diff map を使用
• vibium eval は複雑な DOM クエリのためのエスケープハッチ
• vibium check/vibium uncheck は冪等 — 先に状態を確認せずに呼び出しても安全
• スクリーンショットはデフォルトで現在のディレクトリに保存 (-o で変更)
• vibium storage / vibium storage restore を使用してセッション間で認証を永続化