qa-use

Name: qa-use
Author: desplega-ai

github.com/desplega-aiテスト・品質29295 回インストール22 週間前に更新

リポジトリ

qa-use について

qa-useは、AIを活用した開発ワークフロー向けのブラウザー自動化・E2Eテストスキルです。CLIとプラグイン用ショートカットを備え、ブラウザー操作の記録やテストの実行、編集、クラウド同期を行えます。

主な機能

01ブラウザーセッションの作成と管理
02Webページの移動と操作
03操作を再利用可能なブロックとして記録
04テストの実行、検証、編集
05テストのクラウド同期

活用シーン

01Webアプリを探索してユーザーフローを記録
02開発中のE2Eテスト実行
03テスト定義の保守と同期

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/desplega-ai/qa-use --skill qa-use

インストール後、Claude Code で/qa-useを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/

browser-commands.md

checks.md

ci.md

failure-debugging.md

localhost-testing.md

test-format.md

templates/

auth-flow.yaml

basic-test.yaml

form-test.yaml

詳細

qa-use

AI 駆動の開発ワークフロー向けの E2E テストおよびブラウザ自動化。

重要な洞察: ショートカットとしてのプラグインコマンド

AI ハーネス（codex、opencode など）向け:

プラグインコマンド（/qa-use:verify のようなスラッシュコマンド）は、CLI ワークフローをラップする便利なショートカットです。Bash ツールのみを持つハーネスでも、以下に記載する CLI コマンドを通じてすべての機能にアクセスできます。

このドキュメント全体を通じたパターン:

CLI ワークフロー: ステップバイステップの CLI コマンド（すべてのハーネスで動作します）
プラグインショートカット: オプションのスラッシュコマンド（利便性のため）

セットアップと構成

qa-use のコマンドを使用する前に、構成が整っていることを確認してください:

# Check current configuration (no-op if already configured)
qa-use setup

# Configure with API key (validates against server)
qa-use setup --api-key <key>

# View full configuration details
qa-use info

環境変数（構成ファイルの代替）:

変数	説明
`QA_USE_API_KEY`	認証用の API キー
`QA_USE_REGION`	リージョン: `us`（デフォルト）または `auto`
`QA_USE_API_URL`	API ベース URL を上書き

構成ファイル: プロジェクトディレクトリ内の .qa-use.json、またはホームディレクトリ内の ~/.qa-use.json。優先順位: 環境変数 > プロジェクトの .qa-use.json > ~/.qa-use.json。

「API key not configured」、401、または認証エラーが発生した場合: qa-use setup を実行して構成状態を確認してください。API キーを決して捏造したり推測したりしないでください。

コアワークフロー

1. ブラウザ制御とセッションライフサイクル

CLI ワークフロー:

# Create browser session (returns immediately — runs detached in the background)
qa-use browser create --viewport desktop

# For localhost testing — auto-tunnels when base URL is localhost and API is remote.
# No flag needed for the common case:
qa-use browser create --no-headless http://localhost:3000

# Force a tunnel even in dev mode:
qa-use browser create --tunnel on --no-headless

# Opt out of auto-tunnel (e.g. backend is also local):
qa-use browser create --no-tunnel

# Navigate
qa-use browser goto https://example.com

# Snapshot to get element refs (ALWAYS do this before interacting)
qa-use browser snapshot

# Interact by ref
qa-use browser click e3
qa-use browser fill e5 "text"

# Close
qa-use browser close

バックグラウンドセッション管理:

qa-use browser create はすぐに戻ります — 実際のブラウザ + トンネルは切り離された子プロセスで実行されるため、ターミナルは自由なままです。セッションは次のように管理します:

qa-use browser status --list   # Show all active sessions across processes
qa-use browser status           # Details for the auto-resolved session
qa-use browser close <id>       # Close a specific session
qa-use doctor                   # Reap stale sessions/tunnels (dead PIDs)
qa-use doctor --dry-run         # Preview what would be cleaned

トンネルコマンド:

プロセス間トンネルレジストリ — 複数のコマンドがターゲットごとに単一のトンネルを共有します:

qa-use tunnel start <url>         # Acquire a tunnel (released immediately unless --hold)
qa-use tunnel start <url> --hold  # Keep the tunnel up until Ctrl+C
qa-use tunnel ls                  # List active tunnels (target, public URL, refcount)
qa-use tunnel status <target>     # Detail for a single tunnel
qa-use tunnel close <target>      # Force-release a tunnel (kills detached holders)

プラグインショートカット:

/qa-use:explore https://example.com

（自律的な探索とともに create + goto + snapshot をラップします）

重要: ページでの最初の操作の前に、必ず snapshot を実行してください。要素の参照を決して推測しないでください。

スナップショット差分機能（不要なスナップショットを避けるために活用してください）: 各アクション（goto、click、fill など）の後、ブラウザは DOM の変更を自動的に表示します:

サマリー: 「5 個の要素が追加、1 個の要素が変更」
追加された要素: + [e54] generic "Thanks for agreeing!"（緑）
変更された要素: ~ [e18] checkbox "I agree..." と +attrs: checked, active（黄）
削除された要素: - [e99] button "Submit"（赤）

完全な snapshot を省略できる場合: 直前のアクションの差分出力に、次に操作する必要がある要素の参照がすでに表示されている場合は、それを直接使用してください — 中間の snapshot は必要ありません。たとえば、ボタンをクリックしたときに差分に + [e54] button "Submit" が表示されれば、すぐに click e54 を実行できます。

それでも完全な snapshot が必要な場合: 差分に含まれていなかった要素（たとえば、まだ操作していない既存の要素）を見つける必要がある場合、または差分が切り詰められている場合（「... and N more changes」と表示される）は、snapshot を実行してください。

2. ブロックの理解

ブロックとは何ですか？

ブロックは、ブラウザセッションから記録されたアトミックな操作です。これらは:

あらゆるブラウザ操作（click、fill、goto、scroll など）の間に自動的にキャプチャされます
セッションとともにサーバー側に保存されます
qa-use browser get-blocks で取得されます
テスト生成の基盤となります

ブロックが重要な理由:

一度記録すれば何度でも再生: インタラクティブな記録が自動テストになります
AI フレンドリー: エージェントはブロックを分析してユーザーの意図を理解できます
バージョン管理: セッションとともに保存されたブロックにより、テストの反復が可能になります
CLI → テストの橋渡し: 探索から自動化への自然なワークフロー

ブロックの仕組み:

# 1. Create session and interact (auto-tunnels localhost)
qa-use browser create --no-headless
qa-use browser goto https://example.com
qa-use browser snapshot        # Returns: [ref=e1] button
qa-use browser click e1        # Records as block
qa-use browser fill e5 "text"  # Records as block

# 2. Retrieve blocks (JSON array)
qa-use browser get-blocks
# Returns:
# [
#   {"type": "goto", "url": "...", "timestamp": "..."},
#   {"type": "click", "ref": "e1", "timestamp": "..."},
#   {"type": "fill", "ref": "e5", "value": "text", "timestamp": "..."}
# ]

# 3. Generate test YAML from blocks
qa-use browser generate-test -n "my_test" -o qa-tests/my_test.yaml

# 4. Run generated test
qa-use test run my_test

プラグインショートカット:

/qa-use:record start my_test
# ... perform interactions ...
/qa-use:record stop

（AI を活用したテスト生成とともにインタラクティブなワークフローをラップします）

3. テスト管理

CLI ワークフロー:

# Run test by name
qa-use test run login

# Run and save the (non-synced) local test to cloud
qa-use test run login --persist

# Validate syntax
qa-use test validate login

# Show test details
qa-use test info login

# List test runs
qa-use test runs --status failed

プラグインショートカット:

/qa-use:test-run login

（一般的なテスト実行のための便利なショートカット）

4. テスト変数 (命令型編集)

単一のテスト上の型付き variables: ブロックに対する簡易な set/unset — 完全な YAML をやり取りしたくない場合に便利です。

CLI ワークフロー:

# Local YAML file — Document API preserves comments + key order
qa-use test vars list  qa-tests/login.yaml
qa-use test vars list  qa-tests/login.yaml --json
qa-use test vars set   qa-tests/login.yaml --key user --value alice
qa-use test vars set   qa-tests/login.yaml --key url --value https://x \
                                          --type url --lifetime all
qa-use test vars set   qa-tests/login.yaml --key password --value hunter2 --sensitive
qa-use test vars set   qa-tests/login.yaml --key password --sensitive  # preserves stored value
qa-use test vars unset qa-tests/login.yaml --key user

# Remote --id fallback — exports YAML, mutates, re-imports (best-effort RMW)
qa-use test vars list  --id <uuid>
qa-use test vars set   --id <uuid> --key user --value alice
qa-use test vars unset --id <uuid> --key user

ルール:

相互排他: <file> または --id のいずれかを渡してください。両方は不可です。どちらも指定しない場合は終了コード 1 になります。
--id には完全な UUID が必要です (qa-use test list --query <name> を使って取得してください)。
形式のアップグレード: --key/--value のみを渡すと簡易形式 (key: value) が書き込まれます。 --type/--lifetime/--context/--sensitive のいずれかを指定すると完全形式 ({ value, type, lifetime, context, is_sensitive }) にアップグレードされます。
機密値の保持: 既存の機密変数に対して、--value なしで --sensitive を指定すると、保存済みの値が保持されます。新しいキーに対してこの組み合わせを指定するとエラーになります。
--json の秘匿化: 機密エントリでは value キーが完全に省略されます。is_sensitive: true フラグが秘匿化のシグナルです。
リモートのラウンドトリップに関する注意: コメントやキーの順序の保持はローカルファイルの経路にのみ適用されます。サーバーはインポート時にフォーマットを正規化します。

プラグインによるショートカットはありません - CLI コマンドを直接使用してください。

5. テスト同期ライフサイクル

CLI ワークフロー:

# Pull tests from cloud
qa-use test sync pull

# Push all local tests to cloud
qa-use test sync push --all

# Push specific test
qa-use test sync push --id <uuid>

# Force push (overwrite conflicts)
qa-use test sync push --force

# Compare local vs cloud
qa-use test diff login.yaml

永続化 vs 同期:

ローカルのテストは、その YAML に id: と version_hash: の両方が含まれている場合に同期済みとなります (これらは test sync push/pull によって書き戻されます)。test run の --persist と qa-use test sync は関連していますが同じものではありません:

ローカルファイルの状態	`persist`	実行時に起こること
未同期	`false` (デフォルト)	ローカルで実行され、クラウドには何も保存されません。永続化するには `--persist` を付けて再実行するか、`test sync push` を使用してください。
未同期	`true`	実行後にテストが新規のクラウドエントリとしてアップロードされます。この方法で再実行すると重複が作成されます — ファイルがクラウドの id を追跡するようになったら、`test sync push` を一度だけ使用することを推奨します。
同期済み	`false`	クラウドで追跡されている定義に対して実行され、追加の書き込みはありません。
同期済み	`true`	クラウドの定義がアップサートされます (より新しいクラウド側の編集を上書きする可能性があります)。明示的なバージョン管理には `test sync push`/`pull` を使用してください。

経験則: test sync push/pull が意図的な経路です。--persist (または .qa-use.json の defaults.persist: true) は、まったく新しいローカルテストを一度だけアップロードするために取っておいてください。

プラグインによるショートカットはありません - CLI コマンドを直接使用してください

必須コマンド

ブラウザセッション管理

コマンド	説明
`qa-use browser create`	リモートブラウザセッションを作成
`qa-use browser create <url>`	セッションを作成して URL に移動
`qa-use browser create --tunnel [auto\|on\|off]`	トンネルモード — デフォルトは `auto` (localhost + リモート API)。`--no-tunnel` は `off` の糖衣構文です。
`qa-use browser create --no-headless`	ブラウザウィンドウを表示 (ローカル/トンネルブラウザと組み合わせて使用)
`qa-use browser create --viewport <size>`	ビューポートを設定: `desktop`、`tablet`、`mobile`
`qa-use browser create --ws-url <url>`	既存の WebSocket ブラウザに接続
`qa-use browser create --after-test-id <uuid>`	先にテストを実行してから、インタラクティブモードになります
`qa-use browser create --var <key=value>`	アプリ設定の変数を上書き (繰り返し指定可能)
`qa-use browser list`	アクティブなセッションを一覧表示
`qa-use browser status`	現在のセッションの詳細 (app_url、recording_url など) を表示
`qa-use browser status --list`	プロセスをまたいでアクティブなすべてのセッションを表示
`qa-use browser close`	アクティブなセッションを閉じる
`qa-use browser close <id>`	特定のセッションを id で閉じる
`qa-use doctor`	古いセッション/トンネル (停止した PID) を回収
`qa-use tunnel ls`	レジストリ内のアクティブなトンネルを一覧表示
`qa-use tunnel start <url> --hold`	外部の利用者向けにパブリックトンネルを保持

セッションは ~/.qa-use.json に自動的に永続化されます。アクティブなセッションが 1 つであれば -s フラグは不要です。browser create はすぐに戻ります — ブラウザとトンネルはデタッチされた子プロセスで実行されます。古い状態が蓄積される場合は qa-use doctor を使用してください。

要素の操作

コマンド	説明
`qa-use browser click <ref>`	ref で要素をクリックする
`qa-use browser click --text "Button"`	意味的な説明でクリックする
`qa-use browser fill <ref> "value"`	入力フィールドに入力する
`qa-use browser type <ref> "text"`	遅延を伴って入力する（オートコンプリート向け）
`qa-use browser press <key>`	キーを押す（例：`Enter`、`Tab`）
`qa-use browser check <ref>`	チェックボックスをオンにする
`qa-use browser uncheck <ref>`	チェックボックスをオフにする
`qa-use browser select <ref> "option"`	ドロップダウンの項目を選択する
`qa-use browser hover <ref>`	要素にホバーする
`qa-use browser scroll down 500`	ピクセル単位でスクロールする
`qa-use browser scroll-into-view <ref>`	要素を表示領域内までスクロールする
`qa-use browser drag <ref> --target <ref>`	要素をターゲットまでドラッグする
`qa-use browser mfa-totp [ref] <secret>`	TOTP コードを生成する（任意で入力も行う）
`qa-use browser upload <ref> <file>...`	ファイルを input にアップロードする（base64 エンコード、リモートとトンネルの両方で動作）

検査とスナップショット差分

コマンド	説明
`qa-use browser snapshot`	要素の ref を含む完全な ARIA ツリーを取得する（差分出力が不十分な場合にのみ使用してください）
`qa-use browser url`	現在の URL を取得する
`qa-use browser screenshot`	screenshot.png を保存する
`qa-use browser screenshot file.png`	カスタムパスに保存する
`qa-use browser screenshot --base64`	base64 を標準出力に出力する
`qa-use browser evaluate <expression>`	ブラウザのコンテキストで JavaScript を実行する

スナップショット差分機能は、各ブラウザ操作の後に DOM の変更を自動的に表示します。

追加された要素：+ プレフィックスと緑色で表示されます。これらの ref はすぐに使用できます
変更された要素：~ プレフィックスと黄色で表示され、属性の変更（+attrs: checked）も含まれます
削除された要素：- プレフィックスと赤色で表示されます。これらの ref は使用しないでください

ダウンロード： 操作によってファイルのダウンロードが発生した場合（例：ダウンロードリンクのクリック）、レスポンスにはダウンロード情報（ファイル名、サイズ、署名付き URL）が含まれます。すべてのダウンロードを一覧表示するには qa-use browser downloads を、ローカルに保存するには --save <dir> を使用してください。

最初に完全な snapshot を実行することなく、差分出力を使用して新しく表示された要素を直接操作してください。

テスト操作

コマンド	説明
`qa-use test run <name>`	名前でテストを実行する
`qa-use test run --all`	すべてのテストを実行する
`qa-use test run <name> --tunnel [mode]`	トンネルモードを上書きする（`auto`、`on`、`off`）。`--no-tunnel` は `off` の糖衣構文です。引数なしの `--tunnel` は `on` の糖衣構文です。
`qa-use test run <name> --download`	アセットを `/tmp/qa-use/downloads/` にダウンロードする
`qa-use test run <name> --var key=value`	変数を上書きする
`qa-use test validate <name>`	テストの構文を検証する
`qa-use test list`	利用可能なテストを一覧表示する
`qa-use test info <name>`	テストの詳細（ステップ、タグ、説明）を表示する
`qa-use test info --id <uuid>`	ID でクラウドテストの詳細を表示する
`qa-use test runs [name]`	テスト実行履歴を一覧表示する
`qa-use test runs --id <uuid>`	テスト ID で実行を絞り込む
`qa-use test runs --status failed`	ステータスで実行を絞り込む
`qa-use test init`	テストディレクトリを初期化する
`qa-use test sync pull`	クラウドからテストをプルする
`qa-use test sync push --all`	すべてのローカルテストをクラウドにプッシュする
`qa-use test sync push --id <uuid>`	特定のテストをプッシュする
`qa-use test sync push --force`	競合を上書きしてテストをプッシュする
`qa-use test diff <file>`	ローカルとクラウドのテストを比較する
`qa-use test schema [path]`	テスト定義スキーマを表示する

API 操作 (動的 OpenAPI)

qa-use api は /api/v1/openapi.json から操作を動的に検出し、オフラインフォールバック用にメタデータをローカルにキャッシュします。

コマンド	説明
`qa-use api`	ヘルプと利用可能なサブコマンドを表示します
`qa-use api ls`	OpenAPI から利用可能な `/api/v1/*` ルートを一覧表示します
`qa-use api ls --refresh`	OpenAPI キャッシュを強制的に更新します
`qa-use api ls --offline`	キャッシュされた OpenAPI メタデータのみを使用します
`qa-use api info /api/v1/<route>`	ルートの詳細 (パラメータ、リクエストボディ、レスポンス) を表示します
`qa-use api info /api/v1/<route> -X POST`	特定の HTTP メソッドの情報を表示します
`qa-use api info /api/v1/<route> --json`	ルート情報を JSON で表示します
`qa-use api examples`	使用例を表示します
`qa-use api openapi`	OpenAPI 仕様の URL を出力します
`qa-use api openapi --raw`	OpenAPI 仕様全体を JSON としてダンプします
`qa-use api /api/v1/tests`	エンドポイントを呼び出します (可能な場合はメソッドが推測されます)
`qa-use api -X GET /api/v1/test-runs -f limit=5`	クエリフィールドを指定して GET します
`qa-use api -X POST /api/v1/tests-actions/run --input body.json`	JSON ボディファイルを指定して POST します
`qa-use api -X GET /api/v1/test-runs/<id>`	ID で詳細エンドポイントを取得します

プラグインによるショートカットはありません - CLI コマンドを直接使用してください。

API チェックとチェックスケジュール

リモート API チェックは一級コマンドで管理されます。これらは desplega.ai API を直接呼び出します。チェックをローカルで実行したり、ブラウザセッションを作成したりはしません。

コマンド	説明
`qa-use check list --app-config <id>`	リモート API チェックを一覧表示します
`qa-use check info <check-id>`	依存関係やキャプチャを含む 1 つのチェックを検査します
`qa-use check create --name <name> --app-config <id> --config check.json`	チェックを作成します
`qa-use check update <check-id> --depends-on <id> --alias <name>`	依存関係チェーンのメタデータを更新します
`qa-use check delete <check-id> --force`	チェックを削除します
`qa-use check-schedule list --app-config <id>`	リモートのチェックスケジュールを一覧表示します
`qa-use check-schedule create --name <name> --app-config <id> --cron "/15 * * *" --check <id>`	順序付けられたスケジュールを作成します
`qa-use check-schedule run <schedule-id> --var env=staging`	リモートの変数受け渡しチェーンとしてスケジュールを実行します

一般的なフロー:

qa-use check create \
  --name "Auth token" \
  --app-config <app-config-id> \
  --config auth-check.json \
  --alias auth \
  --capture token=$.access_token

qa-use check update <claim-check-id> \
  --depends-on <auth-check-id> \
  --alias claim

qa-use check-schedule create \
  --name "Claims chain" \
  --app-config <app-config-id> \
  --cron "*/15 * * * *" \
  --check <auth-check-id> \
  --check <claim-check-id>

qa-use check-schedule run <schedule-id> --var env=staging --var claim_id=123

公開 API は現在、個々のチェック実行アクションではなくスケジュール実行をドキュメント化しているため、単独の qa-use check run <check-id> コマンドはまだ存在しません。現在のチェックペイロード契約については qa-use api info /api/v1/checks -X POST を使用し、例については references/checks.md を参照してください。

プラグインによるショートカットはありません - CLI コマンドを直接使用してください。

ログとデバッグ

コマンド	説明
`qa-use browser logs console`	セッションのコンソールログを表示します
`qa-use browser logs console -s <id>`	特定の/閉じられたセッションのログを表示します
`qa-use browser logs network`	ネットワークリクエストログを表示します
`qa-use browser logs network -s <id>`	特定のセッションのネットワークログを表示します
`qa-use browser downloads`	セッションのダウンロード済みファイルを一覧表示します
`qa-use browser downloads --save <dir>`	ダウンロード済みファイルをローカルディレクトリに保存します
`qa-use browser downloads --json`	ダウンロード情報を JSON で出力します

テスト生成

コマンド	説明
`qa-use browser generate-test`	記録されたセッションからテスト YAML を生成します
`qa-use browser generate-test -s <id>`	特定のセッションから生成します
`qa-use browser generate-test -n <name>`	テスト名を指定します
`qa-use browser generate-test -o <path>`	出力パスを指定します
`qa-use browser get-blocks`	記録されたインタラクションブロック (JSON) を取得します

待機

コマンド	説明
`qa-use browser wait <ms>`	固定時間の待機
`qa-use browser wait-for-selector ".class"`	セレクタを待機します
`qa-use browser wait-for-load`	ページの読み込みを待機します

変数のオーバーライド

--var を使用すると、実行時にアプリの設定変数をオーバーライドできます。一般的な変数:

変数	説明
`base_url`	アプリのベース URL (例: プレビューデプロイの URL)
`login_url`	ログインページの URL
`login_username`	認証用のユーザー名/メールアドレス
`login_password`	認証用のパスワード

一時的なプレビュー URL を使用する例:

qa-use browser create --after-test-id <login-test-uuid> \
  --var base_url=https://preview-123.example.com \
  --var login_url=https://preview-123.example.com/auth/login

一般的なパターン

パターン 1: 機能の検証

CLI ワークフロー:

# 1. Search for existing test
qa-use test list | grep "login"

# 2. Run test
qa-use test run login

# 3. Debug failures
qa-use browser logs console

プラグインのショートカット:

/qa-use:verify "login works with valid credentials"

(上記の CLI ワークフローを、AI によるテストの検出と分析でラップします)

パターン 2: テストの記録と生成

CLI ワークフロー:

# 1. Create session (auto-tunnels localhost targets)
qa-use browser create --no-headless

# 2. Navigate and interact
qa-use browser goto https://example.com
qa-use browser snapshot
qa-use browser click e1
qa-use browser fill e5 "test"

# 3. Generate test from blocks
qa-use browser get-blocks
qa-use browser generate-test -n "my_test"

# 4. Run test
qa-use test run my_test

プラグインのショートカット:

/qa-use:record start my_test
# ... perform interactions ...
/qa-use:record stop

パターン 3: 認証付きの探索

CLI ワークフロー:

# Create session that runs login test first
qa-use browser create --after-test-id <login-test-uuid>

# Session now authenticated, explore
qa-use browser goto /dashboard
qa-use browser snapshot

プラグインのショートカット:

/qa-use:explore /dashboard

(認証の検出とセッションの作成を自動的に処理します)

パターン 4: 既存テストの編集

CLI ワークフロー:

# 1. Open test file in editor
vim qa-tests/login.yaml

# 2. Validate syntax
qa-use test validate login

# 3. Run to verify
qa-use test run login

プラグインのショートカット:

/qa-use:record edit login

(検証付きの AI 支援による編集)

パターン 5: スナップショットの差分を使用して不要なスナップショットを避ける

CLI ワークフロー:

# Create session and navigate
qa-use browser create --no-headless
qa-use browser goto https://evals.desplega.ai/checkboxes

# goto shows diff — initial page load shows all elements:
# Changes: 45 elements added
# + [e18] checkbox "I agree to the terms and conditions"
# + [e19] generic "I agree to the terms and conditions"

# ✅ Use ref from diff directly — no snapshot needed!
qa-use browser click e18

# Diff shows what changed:
# Changes: 5 elements added, 1 element modified
# + [e54] generic "Thanks for agreeing!"
# + [e55] link "Terms and Conditions"
# ~ [e18] checkbox "I agree to the terms and conditions"
#     +attrs: active, checked

# ✅ Can click e55 directly from diff output — no snapshot needed!
qa-use browser click e55

# ❌ Need to find an element NOT in the diff? Now run snapshot:
qa-use browser snapshot

重要な原則: アクション後の要素参照の主要なソースとして、差分の出力を使用します。差分に含まれていなかった要素を探す必要がある場合にのみ、snapshot にフォールバックします。

メリット:

API 呼び出しの削減 = 自動化の高速化
差分の参照は常に最新 (サーバーから返されたばかり)
何が変更されたかを即座に確認 (新しい要素、属性の変更、削除)

プラグインのショートカットなし - すべてのブラウザーコマンドで自動的に使用できる機能

CI/CD 統合

CI でのテスト実行

環境変数:

export QA_USE_API_KEY="your-api-key"
export QA_USE_REGION="us"  # Optional: "us" or "auto"

基本的なテストの実行:

# Run all tests
qa-use test run --all

# Run specific tag
qa-use test run --tag smoke

# Exit codes: 0 = pass, 1 = fail

GitHub Actions の例

name: QA Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - name: Install qa-use
        run: npm install -g @desplega.ai/qa-use
      - name: Run tests
        run: qa-use test run --all
        env:
          QA_USE_API_KEY: ${{ secrets.QA_USE_API_KEY }}

テスト成果物

スクリーンショット:

失敗時に自動保存
保存場所: /tmp/qa-use/downloads/ (ローカル) またはクラウド (リモート)

ログ:

コンソールログ: qa-use browser logs console -s <session-id>
ネットワークログ: qa-use browser logs network -s <session-id>

高度なトピック

ローカルホストのテスト (自動トンネル)

API がリモートの場合、qa-use はローカルホストのターゲットを自動的にトンネルします。 一般的なケースではフラグは不要です:

qa-use browser create --no-headless http://localhost:3000
qa-use test run my_test   # auto-tunnels if base_url is localhost

3 つの状態を持つ --tunnel フラグ:

値	動作
`auto` (デフォルト)	ベース URL がローカルホストかつ API URL がリモートの場合にのみトンネルする
`on` (または `--tunnel` のみ)	開発モードでも強制的にトンネルする
`off` (または `--no-tunnel`)	トンネルしない

Testing localhost (http://localhost:3000)?
  ├─ API remote (default)  → auto-tunnels. No flag needed.
  ├─ API also local (dev)  → no tunnel by default. Use --tunnel on to force.
  └─ Public URL target     → no tunnel (remote cloud browser)

プラグインのショートカットはトンネルの検出を自動的に処理します:

/qa-use:explore http://localhost:3000
/qa-use:record start local_test

トラブルシューティングについては references/localhost-testing.md を参照してください。

セッションの永続化

セッションは ~/.qa-use.json に保存され、以下を持ちます:

TTL: 30 分 (デフォルト)
自動解決: アクティブなセッションが 1 つ = -s フラグは不要
クリーンアップ: タイムアウトまたは明示的な browser close で自動的に実行

ブロックの制限

キャプチャされるもの:

goto、click、fill、type、check、uncheck、select、hover
scroll、scroll-into-view、drag、upload、press

キャプチャされないもの:

アサーション (手動で追加する必要があります)
待機 (タイミングから推測されるため、調整が必要な場合があります)
複雑なインタラクション (マルチドラッグ、ホバーシーケンス)

手動編集: 生成された YAML を編集して、アサーションを追加し、セレクターを調整します。

WebSocket セッション

プロセス間でのセッションの共有:

# Process 1: Create session (auto-tunnels if target is localhost + API remote)
qa-use browser create http://localhost:3000
# Output: ws://localhost:12345/browser/abc123

# Process 2: Connect to session
qa-use browser goto https://example.com --ws-url ws://localhost:12345/browser/abc123

詳細リファレンス

CLI を使用して、実行時に任意のリファレンスへアクセスできます: qa-use docs <topic>

トピック	CLI コマンド	説明
browser-commands.md	`qa-use docs browser-commands`	すべてのフラグを含むブラウザ CLI の完全なリファレンス
checks.md	`qa-use docs checks`	API チェックとチェックスケジュールのワークフロー
test-format.md	`qa-use docs test-format`	テスト YAML の完全な仕様
localhost-testing.md	`qa-use docs localhost-testing`	ローカル開発向けのトンネル設定
failure-debugging.md	`qa-use docs failure-debugging`	失敗の分類と診断
ci.md	`qa-use docs ci`	CI/CD 連携のパターンと例

qa-use docs --list を使用すると、利用可能なすべてのトピックとテンプレートを確認できます。

テンプレート

テンプレート	説明
basic-test.yaml	シンプルなナビゲーションとアサーション
auth-flow.yaml	認証情報を使用したログインフロー
form-test.yaml	バリデーション付きのフォーム送信

テスト形式の概要

name: Login Test
description: Validates login functionality with valid credentials
tags:
  - smoke
  - auth
app_config: <app-config-id>
variables:
  email: [email protected]
  password: secret123
depends_on: setup-test  # Optional
steps:
  - action: goto
    url: /login
  - action: fill
    target: email input
    value: $email
  - action: click
    target: login button
  - action: to_be_visible
    target: dashboard

完全な仕様については references/test-format.md を参照してください。

よくある間違い

❌ 誤り	✅ 正しい
`browser navigate <url>`	`browser goto <url>`
`browser destroy`	`browser close`
`browser close <session-id>`	`browser close`
要素の参照を推測する	diff 出力または `snapshot` からの参照を使用する
すべてのアクションの後に `snapshot` を実行する	diff 出力を使用する。`snapshot` は必要なときだけ実行する
開発環境で `--tunnel` を強制する（両方ともローカル）	自動モードに任せるか、明示的に `--tunnel on` を使用する
`test sync --pull`	`test sync pull`（フラグではなくサブコマンド）
`test sync --push`	`test sync push`（フラグではなくサブコマンド）

トラブルシューティング

行き詰まったり、予期しないエラーが発生した場合は、組み込みのドキュメントを使用してください:

# Check configuration state
qa-use setup

# Browse main documentation
qa-use docs

# List all available topics
qa-use docs --list

# Access specific topic
qa-use docs <topic>

状況	コマンド
認証 / API キーのエラー	`qa-use setup` の後に `qa-use docs`
不明なブラウザコマンド	`qa-use docs browser-commands`
テストの失敗	`qa-use docs failure-debugging`
localhost / トンネルの問題	`qa-use docs localhost-testing`
テスト YAML の構文	`qa-use docs test-format`
API チェック / スケジュール	`qa-use docs checks`
CI/CD のセットアップ	`qa-use docs ci`

重要なルール:

回避策を即興で考える前に、必ず qa-use docs を参照してください
API キー、トークン、URL、認証情報を決して捏造しないでください
qa-use setup に設定が表示されない場合は、推測せずに報告してください

npx による代替方法

すべてのコマンドは、グローバルインストールを前提として qa-use を使用しています。一時的な使用の場合:

npx @desplega.ai/qa-use browser <command>

Markdown 対応

ログインしてコメント

基本情報

作者: desplega-ai
リポジトリ: desplega-ai/qa-use
カテゴリ: テスト・品質
インストール数: 295
GitHub スター: 29

問題を報告

コマンド	説明
`qa-use browser goto <url>`	URL に移動する
`qa-use browser back`	戻る
`qa-use browser forward`	進む
`qa-use browser reload`	ページを再読み込みする

qa-use

qa-use について

主な機能

活用シーン

インストール

同梱ファイル

詳細

qa-use

重要な洞察: ショートカットとしてのプラグインコマンド

セットアップと構成

コアワークフロー

1. ブラウザ制御とセッションライフサイクル

2. ブロックの理解

3. テスト管理

4. テスト変数 (命令型編集)

5. テスト同期ライフサイクル

必須コマンド

ブラウザセッション管理

ナビゲーション

要素の操作

検査とスナップショット差分

テスト操作

API 操作 (動的 OpenAPI)

API チェックとチェックスケジュール

ログとデバッグ

テスト生成

待機

変数のオーバーライド

一般的なパターン

パターン 1: 機能の検証

パターン 2: テストの記録と生成

パターン 3: 認証付きの探索

パターン 4: 既存テストの編集

パターン 5: スナップショットの差分を使用して不要なスナップショットを避ける

CI/CD 統合

CI でのテスト実行

GitHub Actions の例

テスト成果物

高度なトピック

ローカルホストのテスト (自動トンネル)

セッションの永続化

ブロックの制限

WebSocket セッション

詳細リファレンス

テンプレート

テスト形式の概要

よくある間違い

トラブルシューティング

npx による代替方法

コメント