stably-cli

Stably CLI アシスタント

AI を活用した Playwright テスト管理：CLI からテストの計画、作成、実行、修正、保守を行います。

事前確認

必ず最初に stably --version を実行してください。 見つからない場合は、npm install -g stably でインストールするか、npx stably を使用してください。Node.js 20 以降、Playwright、および Stably アカウントが必要です。

警告： 引数なしで stably を実行しないでください。人間の入力が必要な対話型チャットモードが起動し、AI エージェントが停止します。

コマンドリファレンス

目的	コマンド
対話型 AI チャット（人間専用）	stably（引数なし）— AI エージェントから実行しないでください
テストカバレッジを計画	stably plan
特定の領域を計画	stably plan "focus on checkout"
プロンプトからテストを生成	stably create "description"
ブランチの差分からテストを生成	stably create（プロンプトなし）
テストを実行	stably test
カスタム名でテストを実行	stably test --suiteName="nightly"
リモート環境でテストを実行	stably --env staging test
失敗したテストを修正	stably fix [runId]
プロジェクトを初期化	stably init
ブラウザーをインストール	stably install（CI では --with-deps chromium を使用）
リモート環境を一覧表示	stably env list
環境変数を確認	stably env inspect <name>
認証	stably login / logout / whoami
アプリの動作を検証	stably verify "description"
URL を指定して検証	stably verify "description" --url http://localhost:3000
最近のテスト実行を一覧表示	stably runs list
実行の詳細を表示	stably runs view <runId>
不安定なテストの分析	stably analytics flaky
失敗の分析	stably analytics failures
CLI を更新	stably upgrade [--check]

グローバルオプション

オプション	説明
--cwd <path> / -C	作業ディレクトリを変更
--env <name>	リモートの Stably 環境から変数を読み込み
--env-file <path>	ローカルファイルから変数を読み込み（複数指定可）
--browser <type>	ブラウザーの種類：local または cloud（デフォルト：local）。環境変数 STABLY_CLOUD_BROWSER=1 でも設定できます
--verbose / -v	詳細なログを出力
--no-telemetry	テレメトリーを無効化

環境変数の優先順位（高い → 低い）：Stably の認証（STABLY_API_KEY）→ process.env → --env-file → --env

主なコマンド

stably plan [prompt...]

コードベースを探索してカバレッジの不足箇所を見つけ、優先度タグ（@p0～@p3）付きの test.fixme() スケルトンファイルを生成します。プロンプトを指定しない場合はアプリ全体を分析し、指定した場合はその領域に絞って探索します。

stably plan                                         # full autonomous discovery
stably plan "focus on checkout and auth"             # scoped plan
stably plan "plan tests for features in this PR"     # PR-scoped

リポジトリ内の既存のテストディレクトリに、グループごとに 1 つの spec ファイルを出力します。各ファイルには、test.fixme() シナリオを含む test.describe() フローが記述されます。実際の test() 実装を含む既存ファイルは変更されません。安全に再実行できます（冪等で、1 回の実行につき最大 200 フロー）。

一般的なワークフロー： stably plan → チームで優先度を確認・調整 → stably create "implement all @p0 tests" → stably test → stably fix

また、今後のエージェント実行に備えて、プロジェクトで判明した重要な情報（認証パターン、フレームワークの規約）を STABLY.md に書き込みます。

stably create [prompt...]

プロンプト（引用符は省略可能）からテストを生成します。プロンプトが指定されていない場合は、ブランチの差分から内容を推測します。

• --output <dir> — 出力ディレクトリを上書きします（playwright.config.ts の testDir、または tests/、e2e/ などの一般的なディレクトリから自動検出）
• --browser <type> — クラウドブラウザーで実行するには cloud を指定します（デフォルト：local）

stably create "test the checkout flow"
stably create                              # infer from diff
stably create "test registration" --output ./e2e
stably create "implement all @p0 tests"    # implement planned test.fixme() skeletons
stably create --browser cloud "test login" # use cloud browser

プロンプトのヒント： ユーザーフロー、UI 要素、認証要件、エラー状態を具体的に記述してください。

stably test

Playwright テストを Stably レポーターで実行します。--trace=on が自動的に有効になります。Playwright CLI のすべてのオプションを引き継ぎます。

stably test --headed --project=chromium --workers=4
stably test --grep="login" tests/login.spec.ts
stably --env staging test --headed
stably test --suiteName="nightly smoke tests"

• --suiteName <name> — ダッシュボードと Slack 通知に表示されるレポート上のスイート名を上書きします。省略した場合、実行中の Playwright プロジェクト名の一覧をアルファベット順に並べ、, で連結したものが既定値になります。環境変数 STABLY_SUITE_NAME、または Playwright の設定で stablyReporter({ suiteName: "..." }) を指定することでも設定できます。

stably fix [runId]

トレース、スクリーンショット、ログ、DOM の状態を AI で分析し、失敗したテストを修正します。

Run ID の解決順序： 明示的な引数 → CI 環境変数（CLI が GitHub の run ID を対応する Stably の run にマッピングします）→ .stably/last-run.json（24 時間より古い場合は警告します）。Git リポジトリが必要です。

stably fix          # auto-detect last run
stably fix abc123   # explicit run ID

一般的なワークフロー： stably test →（失敗？）→ stably fix → stably test

stably verify <prompt...>

テストファイルを生成せず、自然言語による説明に照らしてアプリの動作を検証します。

• -u, --url <url> — 対象 URL（指定しない場合は自動検出）
• --max-budget <dollars> — 最大予算（USD、既定値：5）
• --no-interactive — 対話型プロンプトを無効にします
• --browser <type> — クラウドでブラウザーを実行する場合は cloud を使用します（既定値：local）

終了コード：0 = PASS、1 = FAIL、2 = INCONCLUSIVE。

stably verify "users can sign up with email"
stably verify "checkout flow works" --url http://localhost:3000
stably verify "login page loads" --no-interactive

エージェント向けの注意： 既定の予算 5 ドルで、ほとんどの検証に十分です。ユーザーから明示的な承認がない限り、--max-budget を増やさないでください。

stably runs list [options]

現在のプロジェクトの最近のテスト実行を一覧表示します。

• -b, --branch <name> — Git ブランチで絞り込みます
• -n, --limit <number> — 最大結果数（既定値 20、最大 100）
• --after <runId> / --before <runId> — run ID によるカーソルベースのページネーション
• --source <source> — ソースで絞り込みます（local、ci、web）
• -s, --status <status> — ステータスで絞り込みます：queued、running、passed、failed、timedout、cancelled、interrupted
• --suite <name> — テストスイートで絞り込みます
• --trigger <trigger> — トリガーの種類で絞り込みます：manual、scheduled、ui、api、github_action、suite_run
• --json — JSON 形式で出力します（AI エージェントに推奨）

stably runs list                           # recent runs
stably runs list --status failed           # find failed runs
stably runs list --branch main --limit 5   # recent runs on main
stably runs list --json                    # machine-readable output

エージェント向けの注意： run データをプログラムで解析する場合は、機械可読な出力を得るために必ず --json を使用してください。

stably runs view <runId> [options]

特定のテスト実行の詳細を表示します。メタデータ、根本原因を含む問題、個々のテスト結果が含まれます。

• --json — JSON 形式で出力します（AI エージェントに推奨）

stably runs view abc123
stably runs view abc123 --json

stably analytics flaky [options]

設定可能な期間における不安定率に基づいて順位付けし、最も不安定なテストを表示します。

• --days <n> — 遡る期間（日数、1～90、既定値：7）
• -b, --branch <name> — ブランチ名で絞り込みます
• -n, --limit <n> — 返す行の最大数（1～100、既定値：10）
• --json — JSON 形式で出力します（AI エージェントに推奨）

stably analytics flaky                          # flaky tests, last 7 days
stably analytics flaky --days 30 --limit 20     # wider window, more results
stably analytics flaky --branch main --json     # machine-readable, main only

stably analytics failures [options]

設定可能な期間における失敗率に基づいて順位付けし、最も失敗の多いテストを表示します。

• --days <n> — 遡る期間（日数、1～90、既定値：7）
• -b, --branch <name> — ブランチ名で絞り込みます
• -n, --limit <n> — 返す行の最大数（1～100、既定値：10）
• --json — JSON 形式で出力します（AI エージェントに推奨）

stably analytics failures                       # failing tests, last 7 days
stably analytics failures --days 14             # last 2 weeks
stably analytics failures --branch main --json  # machine-readable, main only

エージェント向けの注意： 分析データをプログラムで解析する場合は、機械可読な出力を得るために必ず --json を使用してください。

リモート環境

stably env list — 現在のプロジェクトの環境を一覧表示します。 stably env inspect <name> — 変数名とメタデータを表示します（値は表示されません）。

チームで共有するダッシュボード変数には --env を、ローカルの .env ファイルには --env-file を使用します。両方を併用できます（--env が優先されます）。

長時間実行されるコマンド（AI エージェント）

stably plan、stably create、stably fix、stably verify は AI を活用しており、数分かかることがあります。

エージェント	設定
Claude Code	timeout: 600000（推奨 — コマンド出力を保持します）。または、並行作業が必要な場合は run_in_background: true
Cursor	block_until_ms: 900000（デフォルトの 30 秒では短すぎます）

stably test の実行時間はスイートの規模によって異なります。大規模なスイートでは同じタイムアウトを使用してください。それ以外のコマンドは数秒で完了します。

コマンドがタイムアウトするか失敗した場合： 診断のため、--verbose を付けて一度再試行してください。AI を活用したコマンドは冪等なので、再試行しても安全です。失敗が続く場合は、stably whoami（認証）とネットワーク接続を確認してください。

開発サーバーやウォッチャーなど、一般的な長時間実行コマンドのパターンについては、bash-commands スキルを参照してください。

設定

必須の環境変数

# NEVER hardcode real values — use .env files (gitignored) or CI secrets
STABLY_API_KEY=your_key       # from https://auth.stably.ai/org/api_keys/
STABLY_PROJECT_ID=your_id     # from dashboard

.env ファイル、--env-file、または --env（リモート）で設定します。

Playwright の設定

stably test はトレースを自動的に有効にします。npx playwright test を直接実行する場合も、設定で trace: 'on' を指定してください。

import { defineConfig, stablyReporter } from '@stablyai/playwright-test';

export default defineConfig({
  use: { trace: 'on' },
  reporter: [
    ['list'],
    stablyReporter({
      apiKey: process.env.STABLY_API_KEY,
      projectId: process.env.STABLY_PROJECT_ID,
    }),
  ],
});

CI/CD：GitHub Actions

重要な CI パターン

• テスト、修正、PR の各ステップには continue-on-error: true を使用してください。これにより、失敗後もパイプラインで修正や PR のステップを実行できます。ただし、テストが失敗した場合にワークフローを失敗させる最終ステップは必ず追加してください。修正や PR の各ステップに continue-on-error がないと、そのステップの失敗によって後続のステップが実行されません。

自己修復型テストパイプライン

name: E2E Tests with Auto-Fix
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - name: Install browsers
        run: npx stably install
        env:
          STABLY_API_KEY: ${{ secrets.STABLY_API_KEY }}
          STABLY_PROJECT_ID: ${{ secrets.STABLY_PROJECT_ID }}
      - name: Run tests
        id: test
        continue-on-error: true
        run: npx stably --env staging test
        env:
          STABLY_API_KEY: ${{ secrets.STABLY_API_KEY }}
          STABLY_PROJECT_ID: ${{ secrets.STABLY_PROJECT_ID }}
      - name: Auto-fix failures
        if: steps.test.outcome == 'failure'
        continue-on-error: true
        run: npx stably --env staging fix
        env:
          STABLY_API_KEY: ${{ secrets.STABLY_API_KEY }}
          STABLY_PROJECT_ID: ${{ secrets.STABLY_PROJECT_ID }}
      - name: Create PR with fixes
        if: steps.test.outcome == 'failure'
        continue-on-error: true
        run: |
          if [ -n "$(git status --porcelain)" ]; then
            BRANCH="stably-fix/$(date +%Y%m%d-%H%M%S)"
            git config user.name "github-actions[bot]"
            git config user.email "github-actions[bot]@users.noreply.github.com"
            git checkout -b "$BRANCH"
            git add -A
            git commit -m "fix: auto-repair failing tests"
            git push origin "$BRANCH"
            gh pr create \
              --title "fix: auto-repair failing tests" \
              --body "Automated PR from Stably Fix after test failures in run #${{ github.run_number }}." \
              --base "${{ github.ref_name }}" \
              --head "$BRANCH"
          fi
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - name: Fail if tests failed
        if: steps.test.outcome == 'failure'
        run: |
          echo "::error::Tests failed"
          exit 1

トラブルシューティング

問題	解決策
「認証されていません」	stably login
API キーが認識されない	stably whoami で確認
テストが誤ったディレクトリにある	stably create "..." --output ./tests/e2e
ブラウザーが見つからない	stably install
トレースがアップロードされない	playwright.config.ts で trace: 'on' を指定
「Run ID が見つかりません」	先に stably test を実行し、その後 stably fix を実行

リンク

ドキュメント · CLI クイックスタート · ダッシュボード · API キー