stably-cli

Stably CLI 助手

AI 辅助的 Playwright 测试管理：通过命令行规划、创建、运行、修复和维护测试。

运行前检查

请务必先运行 stably --version。 如果未找到，请使用 npm install -g stably 安装，或使用 npx stably。需要 Node.js 20+、Playwright 和 Stably 账号。

**警告：**请勿在没有参数的情况下运行 stably——这会启动交互式聊天模式，需要人工输入，并会导致 AI Agent 卡住。

命令参考

意图	命令
交互式 AI 聊天（仅供人工使用）	stably（无参数）——请勿从 AI Agent 调用
规划测试覆盖范围	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

在仓库现有的测试目录中，每组输出一个规格文件。每个文件都包含带有 test.fixme() 场景的 test.describe() 流程。不会修改包含实际 test() 实现的现有文件。可安全重复运行（幂等，每次调用最多生成 200 个流程）。

典型工作流： stably plan → 团队审查并调整优先级 → stably create "implement all @p0 tests" → stably test → stably fix

此外，还会将关键项目发现（身份验证模式、框架惯例）写入 STABLY.md，供后续 Agent 运行时参考。

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

使用 Stably reporter 运行 Playwright 测试。自动启用 --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]

使用 AI 分析 trace、截图、日志和 DOM 状态，修复失败的测试。

Run ID 解析顺序： 显式参数 → CI 环境变量（CLI 会将 GitHub 的 run ID 映射到对应的 Stably 运行）→ .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

Agent 注意： 默认的 $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 Agent 首选）

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

Agent 注意： 以编程方式解析运行数据时，始终使用 --json 获取机器可读的输出。

stably runs view <runId> [options]

显示特定测试运行的详细信息，包括元数据、含根本原因的问题以及各项测试结果。

• --json — 以 JSON 格式输出（AI Agent 首选）

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 Agent 首选）

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 Agent 首选）

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

Agent 注意： 以编程方式解析分析数据时，始终使用 --json 获取机器可读的输出。

远程环境

stably env list — 列出当前项目中的环境。 stably env inspect <name> — 显示变量名称和元数据（不会打印变量值）。

使用 --env 指定团队共享的仪表板变量；使用 --env-file 指定本地 .env 文件。两者可组合使用（--env 优先）。

长时间运行的命令（AI Agent）

stably plan、stably create、stably fix 和 stably verify 由 AI 驱动，可能需要几分钟才能完成。

Agent	配置
Claude Code	timeout: 600000（首选——保留命令输出），或在需要并行工作时使用 run_in_background: true
Cursor	block_until_ms: 900000（默认的 30s 太短）

stably test 的运行时长取决于测试套件的规模——大型测试套件请使用相同的超时时间。所有其他命令都能在几秒内完成。

**如果命令超时或失败：**使用 --verbose 重试一次以进行诊断。由 AI 驱动的命令具有幂等性，可以安全重试。如果仍然失败，请检查 stably whoami（身份验证）和网络连接。

有关长时间运行命令的一般模式（开发服务器、监视器），请参阅 bash-commands skill。

配置

必需的环境变量

# 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

故障排除

问题	解决方案
"Not authenticated"	stably login
API 密钥无法识别	使用 stably whoami 进行验证
测试位于错误目录	stably create "..." --output ./tests/e2e
缺少浏览器	stably install
跟踪未上传	在 playwright.config.ts 中设置 trace: 'on'
"Run ID not found"	先运行 stably test，然后再运行 stably fix

链接

文档 · CLI 快速入门 · 仪表板 · API 密钥