Qa Use

qa-use

ブラウザテストと E2E テスト管理のための QA 自動化 CLI です。

クイックスタート

# Install globally
npm install -g @desplega.ai/qa-use

# Or use with npx
npx @desplega.ai/qa-use setup

はじめに

1. セットアップ

qa-use setup                    # Configure your API key
qa-use test init                # Initialize test directory with example

2. 最初のテストを作成する

qa-tests/login.yaml を作成します:

name: Login Test
app_config: your-app-config-id
steps:
  - action: goto
    url: /login
  - action: fill
    target: email input
    value: [email protected]
  - action: click
    target: login button
  - action: to_be_visible
    target: dashboard

3. テストを実行する

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

CLI リファレンス

テストコマンド

コマンド	説明
qa-use test init	サンプル付きでテストディレクトリを初期化します
qa-use test run <name>	名前を指定してテストを実行します
qa-use test run --all	qa-tests/ 内のすべてのテストを実行します
qa-use test list	ローカルテストを一覧表示します
qa-use test list --cloud	クラウドテストを一覧表示します
qa-use test validate <name>	テストの構文を検証します
qa-use test sync --push	ローカルテストをクラウドにプッシュします
qa-use test sync --pull	クラウドテストをローカルにプルします
qa-use test export <id>	クラウドテストをローカルファイルにエクスポートします

すべてのオプションについては qa-use test --help を実行してください。

ファイル名のサフィックス (≥ 2.17)。 pull はクラウドテストごとに 1 ファイルを ${safe-name}-${short-id}.yaml として書き出します。ここで ${short-id} はテスト UUID の先頭 8 桁の 16 進文字です。テスト名は仕様上、組織内で衝突する可能性があるため、このサフィックスによってクラウド上の各行に対して 1 つのローカルファイルが保証されます。以前のバージョンからアップグレードした場合、次回の pull では、以前のサフィックスなしファイルと並んで新しいサフィックス付きファイルが書き出されます。qa-use は孤立ファイルごとに 1 行の Legacy file: … 通知を出力し、自動削除は決して行いません。以前のファイルの id: フィールドを確認し、不要であることを確認したうえで手動で削除してください。

ブラウザコマンド

テスト開発とデバッグのための対話的なブラウザ操作:

qa-use browser create                  # Start browser session
qa-use browser goto https://example.com
qa-use browser snapshot                # Get element refs like [ref=e3]
qa-use browser click e3                # Click by element ref
qa-use browser fill e5 "hello"         # Fill input field
qa-use browser run                     # Interactive REPL mode

コマンド	説明
qa-use browser create	ブラウザセッションを開始します
qa-use browser goto <url>	URL に移動します
qa-use browser snapshot	ページ要素の参照を取得します
qa-use browser click <ref>	参照を指定して要素をクリックします
qa-use browser fill <ref> <value>	入力フィールドに入力します
qa-use browser screenshot <path>	スクリーンショットを保存します
qa-use browser run	対話的な REPL モードです
qa-use browser close	ブラウザセッションを閉じます
qa-use browser status --list	プロセス間のアクティブセッションを一覧表示します

29 個のブラウザコマンドの完全なリストについては qa-use browser --help を実行してください。

トンネルとメンテナンスのコマンド

対象が localhost で API がリモートの場合、browser create は自動的にトンネルを張ります。単独のトンネル(またはプロセス間のレジストリ確認)には qa-use tunnel を使用します:

qa-use tunnel start http://localhost:3000 --hold   # Hold a public tunnel
qa-use tunnel ls                                   # List active tunnels
qa-use tunnel status <target|hash>                 # Detail for one entry
qa-use tunnel close <target|hash>                  # Force-release a tunnel
qa-use doctor                                      # Reap stale sessions/tunnels
qa-use doctor --dry-run                            # Preview what would be reaped

コマンド	説明
qa-use tunnel ls	レジストリ内のアクティブなトンネルを一覧表示します
qa-use tunnel status <target>	単一のトンネルの詳細を表示します
qa-use tunnel close <target>	トンネルを強制解放します(デタッチされた保持プロセスを終了します)
qa-use doctor	古いセッション/トンネル(死んだ PID)を回収します

Note: qa-use tunnel * は CLI 側のプロセス間トンネルレジストリであり、MCP モードの永続トンネルラッパーである qa-use mcp tunnel(下記参照)とは異なります。

API コマンド

ライブ OpenAPI(/api/v1/openapi.json)とローカルキャッシュへのフォールバックによる動的な API アクセスです。

qa-use api ls                             # List endpoints from live/cached OpenAPI
qa-use api /api/v1/tests                  # Call endpoint (method inferred)
qa-use api -X POST /api/v1/tests-actions/run --input body.json
qa-use api ls --refresh                   # Force refresh OpenAPI cache
qa-use api ls --offline                   # Use cached OpenAPI only

コマンド	説明
qa-use api ls	OpenAPI から /api/v1/* エンドポイントを一覧表示します
qa-use api <path>	エンドポイントに API リクエストを送信します
qa-use api ... --refresh	OpenAPI 仕様の更新を強制します
qa-use api ... --offline	ネットワークを使用せずにキャッシュされた仕様を使用します

ライブ仕様の取得に失敗した場合、qa-use は最後にキャッシュされた仕様にフォールバックし、古いキャッシュに関する警告を出力します。

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

リモート API チェックとスケジュールは、一級の CLI リソースです。これらは desplega.ai API を直接呼び出します。スケジュール実行は完全にリモートで行われ、ブラウザセッションは作成されません。

qa-use check list --app-config <app-config-id> --q login
qa-use check info <check-id>

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-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
qa-use check-schedule delete <schedule-id> --force
qa-use check delete <check-id> --force

公開 API は現在、個々のチェック実行アクションではなくスケジュール実行を公開しているため、単独の qa-use check run <check-id> コマンドはまだありません。完全なワークフローについては qa-use docs checks を、現在のチェックペイロードの契約については qa-use api info /api/v1/checks -X POST を使用してください。

セットアップコマンド

コマンド	説明
qa-use setup	対話形式の設定（API キー、ベース URL など）
qa-use info	現在の設定を表示
qa-use install-deps	Playwright ブラウザをインストール

テスト定義形式

テストは、ユーザーの操作を記述したステップを含む YAML ファイルです。

name: Checkout Flow
app_config: your-app-id
variables:
  email: [email protected]
depends_on: login-test          # Optional dependency
steps:
  - action: goto
    url: /cart
  - action: click
    target: checkout button
  - action: fill
    target: email input
    value: $email
  - action: to_be_visible
    target: order confirmation

サポートされているアクション:

カテゴリ	アクション
ナビゲーション	goto、go_back、go_forward、reload
入力	fill、type、click、hover、press、check、uncheck、select_option
待機	wait_for_selector、wait_for_timeout、wait_for_load_state
アサーション	to_be_visible、to_have_text、to_have_url、to_contain_text、to_be_checked
高度な操作	ai_action、ai_assertion、extract_structured_data

完全なテスト定義ガイドについては SETUP.md を参照してください。

設定

環境変数

QA_USE_API_KEY=xxx              # Required: Your desplega.ai API key
QA_USE_REGION=us                # Optional: "us" or "auto" (default)

設定ファイル

あるいは、プロジェクトルートに .qa-use.json を作成するか、ホームディレクトリに ~/.qa-use.json を作成します。

{
  "$schema": "https://qa-use.dev/cli-schema.json",
  "api_key": "your-api-key-here",
  "region": "us"
}

優先順位（最初のものが優先）:

1. 環境変数
2. カレントディレクトリの .qa-use.json
3. ホームディレクトリの ~/.qa-use.json

変数	説明	デフォルト
QA_USE_API_KEY	認証用の API キー	(必須)
QA_USE_API_URL	API エンドポイント	https://api.desplega.ai
QA_USE_APP_URL	アプリ URL	https://app.desplega.ai
QA_USE_REGION	リージョン (us または auto)	auto
QA_USE_DEFAULT_APP_CONFIG_ID	デフォルトのアプリ設定	(API キーから)
QA_USE_FORCE_HEADLESS	真値 (1/true/yes/on) の場合、すべてのブラウザ起動で headless=true を強制し、明示的なヘッドフル要求 (--no-headless、--headful、defaults.headless: false) ではエラーになります。	(未設定)

CI/CD 統合

基本的な GitHub Actions

# .github/workflows/e2e.yml
name: E2E Tests

on: [push, pull_request]

jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Run E2E Tests
        env:
          QA_USE_API_KEY: ${{ secrets.QA_USE_API_KEY }}
        run: |
          npm install -g @desplega.ai/qa-use
          qa-use test run --all --download

      - name: Upload Results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: e2e-results
          path: /tmp/qa-use/downloads/

Claude Code による PR 検証

Claude Code で qa-use プラグインを使用して、PR を自動的に検証します。

# Add from the marketplace
claude plugin marketplace add desplega-ai/qa-use

# Then install the plugin
claude plugin install [email protected]

# Verify a feature works
/qa-use:verify "the login form accepts valid credentials"

# Verify PR changes
/qa-use:verify-pr

AI 支援によるテスト生成を含む高度な CI ワークフローについては SETUP.md を参照してください。

Claude Code プラグイン

qa-use には、AI 支援テストワークフロー用の Claude Code プラグインが含まれています。

# Add from the marketplace
claude plugin marketplace add desplega-ai/qa-use

# Then install the plugin
claude plugin install [email protected]

# Install the skill
npx skills add https://github.com/desplega-ai/qa-use --skill qa-use

利用可能なスキル:

スキル	説明
/qa-use:verify <description>	ブラウザ自動化を通じて機能が動作することを検証
/qa-use:verify-pr	自動ブラウザテストで PR の変更を検証
/qa-use:explore	Web ページを対話的に探索
/qa-use:record	ブラウザ操作をテスト定義に記録
/qa-use:test-run	E2E テストを実行
/qa-use:test-validate	テスト構文を検証

MCP サーバー

AI アシスタントとの統合（Claude Desktop、VS Code Copilot、Cursor など）のために、qa-use には完全なブラウザ自動化機能を備えた MCP サーバーが含まれています。

qa-use mcp                      # Start stdio server (default)
qa-use mcp --http               # Start HTTP/SSE server
qa-use mcp tunnel               # Start persistent tunnel mode

以下を含む完全な MCP サーバードキュメントについては MCP.md を参照してください:

• すべての主要な AI アシスタント向けのクライアント設定
• Web 統合向けの HTTP トランスポートモード
• バックエンド主導のテスト向けのトンネルモード
• 完全な MCP ツールリファレンス

開発

git clone https://github.com/desplega-ai/qa-use.git
cd qa-use
bun install
bun run build
bun run dev

Note: このプロジェクトではパッケージマネージャーとして bun を使用しています。

開発ガイドラインについては CONTRIBUTING.md を参照してください。

ドキュメント

• SETUP.md - 完全な E2E テストセットアップガイド
• MCP.md - MCP サーバードキュメント
• CONTRIBUTING.md - 開発ガイド
• CLAUDE.md - AI アシスタントのオンボーディング

ライセンス

MIT