vibe-check

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

vibium CLI は、コマンドラインから Chrome（および --engine firefox を指定した場合は Firefox）を自動化します。ブラウザーは初回の使用時に自動で起動し、デーモンモードではコマンド間も実行状態を維持します。

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 を取得します（外側の HTML には --outer を使います）
• 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 を使います）
• vibium count "<selector>" — 条件に一致する要素の数を数えます
• vibium screenshot -o file.png — スクリーンショットを撮影します（--full-page、--annotate）
• vibium a11y-tree — アクセシビリティツリーを取得します（すべてのノードを対象にするには --everything を使います）

操作

• vibium click "<selector>" — 要素をクリックします（map の @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 式が truthy を返すまで待機します（--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）

フレーム

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

ファイルのアップロード

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

録画

• vibium record start — 録画を開始します（--screenshots、--snapshots、--name、-o path — デフォルトではタイムスタンプ付きの record-<date>.zip になるため、再実行しても上書きされません）
• vibium record stop — 録画を停止して ZIP を保存します（-o path は開始時のパスを上書きします。出力に保存されたファイル名が示されます）

録画にはセッションのビデオトラックを含めることができます（Firefox 154 以降、ローカル ブラウザー）。デフォルトでは、エンジンが対応していればビデオが録画され、そうでなければ スキップされます — どちらになったかは停止時の結果に示されます。必須にするには --video を 渡し（Chrome では説明的なエラーで失敗します）、無効にするには --video=false、ビューポートの デフォルトを上書きするには --video-size 1280x720 / --video-fps 30 を渡します。ビデオは 録画 ZIP 内のトレースの隣（video/<context>.webm）に保存されます。これは開始時にアクティブ だったページを撮影するもので、タブの切り替えには追従しません。リモートブラウザー接続では ビデオ以外のすべてのトラックが録画されます。--video-remote keep を指定するとそれでも録画され、 ファイルはリモートホスト上に残ります（停止時の出力にそのホスト上のパスが示されます）。

vibium record start --video -o run.zip
# ... actions ...
vibium record stop
# Saved run.zip (23 steps, 14s video)

Cookies

• vibium cookies — すべての Cookie を一覧表示します
• vibium cookies <name> <value> — Cookie を設定します
• vibium cookies clear — すべての Cookie をクリアします

ストレージ状態

• vibium storage — Cookie + localStorage + sessionStorage をエクスポートします（-o state.json）
• vibium storage restore <path> — JSON ファイルから状態を復元します

ダウンロード

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

ページ

• vibium pages — 開いているページを一覧表示します
• vibium page new [url] — 新しいページを開きます
• vibium page new --isolated [url] — 独自の Cookie／ストレージを持つページを開きます
• vibium page switch <index|url> — ページを切り替えます
• vibium page close [index|page id] — ページを閉じます

デバッグ

• vibium highlight "<selector>" — 要素を視覚的にハイライトします（3 秒間）

セッション

• vibium start — ローカルブラウザーセッションを開始します
• vibium start <url> — リモートブラウザーに接続して開始します
• vibium stop — ブラウザーセッションを停止します
• vibium daemon start — バックグラウンドブラウザーを起動します
• vibium daemon status — 実行中かどうかを確認します
• vibium daemon stop — デーモンを停止します
• vibium --session <name> <command> — 分離されたデーモンとブラウザーに対して実行します

一般的なパターン

Ref ベースのワークフロー（AI に推奨）

vibium go https://example.com
vibium map
vibium click @e1
vibium map  # re-map after interaction

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

vibium map
vibium click @e3
vibium diff map  # see what changed

ページを読み取る

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

フォームに入力する（エンドツーエンド）

vibium go https://example.com/login
vibium map
# Look at map output to identify form fields
vibium fill @e1 "[email protected]"
vibium fill @e2 "secret"
vibium click @e3
vibium wait url "/dashboard"
vibium screenshot -o after-login.png

スコープ付きマップ（大きなページ）

vibium map --selector "nav"        # Only map elements in <nav>
vibium map --selector "#sidebar"   # Only map elements in #sidebar
vibium map --selector "form"       # Only map form controls

セマンティック検索（CSS セレクター不要）

vibium find text "Sign In"             # → @e1 [button] "Sign In"
vibium find label "Email"              # → @e1 [input] placeholder="Email"
vibium click @e1                       # Click the found element
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"

状態を保持した認証

# Log in once and save state
vibium go https://app.example.com/login
vibium fill "input[name=email]" "[email protected]"
vibium fill "input[name=password]" "secret"
vibium click "button[type=submit]"
vibium wait url "/dashboard"
vibium storage -o auth.json

# Restore in a later session (skips login)
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

同時セッション（分離されたブラウザー）

# Two scripts on one host, each with its own daemon and browser
export VIBIUM_SESSION=checkout-tests
vibium go https://example.com/checkout
vibium daemon stop

# Or per command, to drive two browsers from one script
vibium --session buyer go https://shop.example.com
vibium --session seller go https://shop.example.com/admin

分離されたページ（1 つのブラウザー、別々の Cookie／ストレージ）

# Lighter than a session: two logins in one browser, no second launch
vibium page new --isolated https://shop.example.com   # prints (page: <id>)
vibium page new --isolated https://shop.example.com
vibium page close <id>   # also removes the page's isolated context

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

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 — 他に適切なシグナルがない場合のみ使用します（最大 30s）

すべての待機コマンドで --timeout <ms> を指定できます（デフォルト値はコマンドによって異なります）。

Ref のライフサイクル

ページが変わると、Ref（@e1、@e2）は無効になります。次の場合は、必ず再マッピングしてください。

• 遷移するリンクまたはボタンをクリックした後
• フォームを送信した後
• 動的コンテンツ（ドロップダウン、モーダルなど）の読み込み後

グローバルフラグ

フラグ	説明
--engine <name>	ブラウザーエンジン：chrome（デフォルト）または firefox（env: VIBIUM_ENGINE）
--channel <ch>	エンジンのリリースチャネル — Firefox：release（デフォルト）または beta、Chrome：stable（デフォルト）、beta、dev、または canary（env: VIBIUM_ENGINE_CHANNEL）
--headless	ブラウザーウィンドウを非表示にします
--json	JSON として出力します
-v, --verbose	デバッグログを有効にします
--session <name>	並行利用のための分離されたデーモンとブラウザー（env: VIBIUM_SESSION）

ヒント

• すべてのクリック／入力／ホバー／入力操作は、要素が操作可能になるまで自動的に待機します
• すべてのセレクター引数には、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 を使ってください
• --session を指定しない場合、同じホスト上のすべてのコマンドで 1 つのデーモンと 1 つのブラウザーを共有します — 並行実行する場合は VIBIUM_SESSION を設定してください