runhuman-testing

Runhuman CLI

Runhuman 将 AI 编码工具连接到按需提供服务的专业人工测试人员。你用自然语言描述要测试的内容，由真人执行测试，然后获取结构化反馈。

何时使用 Runhuman

适用于： 用户流程（注册、结账）、视觉／布局测试、移动端适配、UX 反馈、探索性测试、跨浏览器检查。

不适用于： 单元测试、性能基准测试、安全审计或高频自动化测试套件。

快速开始

# 1. Install (or use npx runhuman for any command without installing)
npm install -g runhuman

# 2. Authenticate (opens browser for GitHub OAuth)
runhuman login

# 3. Set up a project
#    List existing projects:
runhuman projects list
#    Or create a new one:
runhuman projects create "My App" --organization <orgId> --default-url https://staging.myapp.com --set-default
#    Switch to an existing project:
runhuman projects switch <projectId>

# 4. Create a test
runhuman job create https://staging.myapp.com \
  -d "Test the signup flow: click Sign Up, fill the form, verify confirmation page"

决定使用新项目还是现有项目： 询问用户是想创建新项目还是使用现有项目。使用 runhuman projects list 显示现有项目，然后使用 projects create 和 --set-default 创建项目，或使用 projects switch 设置当前项目。默认情况下，projects switch 会全局设置默认项目（位于 ~/.config/runhuman/config.json）；传入 --global false 可仅为当前目录设置默认项目。

设置默认值： 使用 runhuman config set <key> <value> 设置 project、color 或 apiUrl 等默认值。使用 runhuman config list 查看完整的配置层级。

本地仓库配置： 运行 runhuman init，在当前目录创建 .runhumanrc，其中包含项目名称、默认时长／设备类别以及一个或多个关联的 GitHub 仓库。传入 --yes 跳过提示，或使用 --name、--github-repo <owner/repo> 或 --github-repos <a/b,c/d> 以非交互方式填写值。

Job 命令命名空间

所有 job 命令均位于 runhuman job 下：

runhuman job create   # create a new test
runhuman job status   # check a job's status
runhuman job wait     # block until a job completes
runhuman job results  # view detailed results
runhuman job list     # list jobs (with filters)
runhuman job watch    # tail a live job
runhuman job artifact # download a raw session artifact
runhuman job share    # toggle public sharing on
runhuman job unshare  # toggle public sharing off
runhuman job create-issue  # file an extracted finding as a GitHub issue

已弃用的扁平命令别名。 较旧的扁平形式（runhuman create、runhuman status、runhuman wait、runhuman results、runhuman list、runhuman watch）仍可解析，但会输出一行弃用警告，并计划移除。新脚本中始终使用 runhuman job <subcommand>——不要引入扁平命令别名调用。

截断 ID

所有命令都接受截断的 ID 前缀，类似于 git 短哈希。CLI 会自动解析最佳匹配项：

runhuman job status 712e          # resolves to full job ID
runhuman projects switch proj     # resolves to matching project

如果多个 ID 匹配，CLI 会要求输入更多字符。破坏性操作（projects delete、keys delete、projects transfer --to-org）要求提供完整 ID。

等待结果

# Block until the test completes (useful in CI/CD)
runhuman job create https://staging.myapp.com \
  -d "Test checkout flow end-to-end" \
  --sync

# Check status of an existing job
runhuman job status <jobId>

# Wait for a previously-created job to finish
runhuman job wait <jobId>

# View detailed results
runhuman job results <jobId>

创建测试

job create 命令是提交测试的主要方式。至少需要提供 URL，以及描述或模板之一。

使用描述

runhuman job create https://staging.myapp.com \
  -d "Test the signup flow: click Sign Up, fill the form, verify confirmation page"

使用输出架构

使用 --schema 或 --schema-inline 获取结构化 JSON 结果：

# Schema from a file
runhuman job create https://staging.myapp.com \
  -d "Test the search feature" \
  --schema ./search-schema.json \
  --sync --json

# Inline schema
runhuman job create https://staging.myapp.com \
  -d "Test signup and login" \
  --schema-inline '{"signupWorks":{"type":"boolean"},"loginWorks":{"type":"boolean"},"issues":{"type":"array","items":{"type":"string"}}}' \
  --sync --json

架构文件示例（search-schema.json）：

{
  "searchWorks": {
    "type": "boolean",
    "description": "Does the search return results?"
  },
  "resultCount": {
    "type": "number",
    "description": "Number of results shown"
  },
  "issues": {
    "type": "array",
    "description": "List of any bugs or issues found"
  }
}

当带有架构的 job 完成后，runhuman job results <jobId> --json 会在标准封装结构的 data.result.data 中返回提取的数据：

{
  "success": true,
  "data": {
    "jobId": "job_abc123",
    "status": "completed",
    "result": {
      "passed": true,
      "explanation": "All tests passed successfully",
      "data": {
        "searchWorks": true,
        "resultCount": 10,
        "issues": []
      }
    },
    "costUsd": 0.18,
    "testDurationSeconds": 120
  }
}

使用 --schema-only 仅获取提取的架构数据：runhuman job results <jobId> --schema-only。

使用模板

模板是可重复使用的测试配置。使用 --template 按名称引用模板，或使用 --template-file 指定本地 .md 文件：

# By name (resolved from repo .runhuman/templates/ → project templates → built-ins)
runhuman job create https://staging.myapp.com --template "Find Bugs"

# By local file path
runhuman job create --template-file .runhuman/templates/smoke-test.md

使用模板时，URL 和描述均为可选项——模板本身可以提供这些内容。

设备类别

指定 --device-class desktop 或 --device-class mobile，以控制测试人员使用的设备：

runhuman job create https://staging.myapp.com -d "Test mobile layout" --device-class mobile

测试者池要求

筛选符合任务条件的测试者。仅限 Max / Enterprise / Enterprise Pro 计划——低级别计划创建任务时，服务器会拒绝请求并提供升级链接。除非用户已说明其使用符合条件的计划，或明确要求筛选测试者池，否则不要添加这些标志。

标志	值	匹配方式
--required-devices	逗号分隔：ios、android、pc、mac	任一——测试者至少需要符合一项
--required-languages	逗号分隔：english、spanish	全部——测试者必须会说列出的每种语言
--require-social-videos	布尔值	—
--require-sideload	布尔值	与 --required-devices ios 或 android 配合使用

因此，--required-languages english,spanish 要求测试者会说两种语言，而不是任选其一。--require-sideload 要求测试者能够侧载移动应用（Android APK 或 iOS IPA）。

runhuman job create https://staging.myapp.com \
  -d "Test the checkout flow on Android" \
  --required-devices android

多仓库上下文

一个任务可以关联一个或多个 GitHub 仓库，以便将 AI 提取的发现作为问题提交回仓库。可通过以下三种方式之一提供仓库：

# Single repo (back-compat flag)
runhuman job create https://staging.myapp.com -d "Test checkout" \
  --github-repo owner/repo

# Multiple repos, comma-separated
runhuman job create https://staging.myapp.com -d "Test checkout" \
  --github-repos "owner/frontend,owner/backend"

# Or inherit from the project / template / .runhumanrc default
runhuman job create https://staging.myapp.com -d "Test checkout"

添加 --auto-create-github-issues，即可在任务完成后，让服务器自动将每项 AI 提取的发现提交为 GitHub 问题。此功能至少需要一个关联的仓库（通过上述标志、模板或项目默认设置关联）。

自动将发现作为问题提交

任务完成后，服务器可以将 AI 提取的发现直接提交到你的跟踪工具。每个跟踪工具都有自己的启用标志，且可以组合使用：

标志	效果
--auto-create-github-issues	将发现提交为 GitHub 问题（需要关联的仓库）
--auto-create-github-issues-repo <owner/repo>	指定关联仓库中的某个仓库
--auto-create-github-feedback	也将 AI 反馈分类中的内容提交为问题（不只是错误）
--auto-create-jira-issues	将发现提交为 Jira 问题
--auto-create-jira-feedback	也将反馈分类中的内容提交为 Jira 问题
--auto-create-linear-issues	将发现提交为 Linear 问题
--auto-only-tester-surfaced	仅提交测试者明确提出的发现（跳过仅来自遥测数据的发现）
--reopen-on-duplicate	如果重复发现对应的问题已关闭，则重新打开该问题（默认：保持关闭）
--comment-on-duplicate	如果发现与现有问题匹配，则发布交叉引用评论，而不是创建新问题

Jira 和 Linear 提交功能要求项目已连接相应集成；GitHub 标志要求至少关联一个仓库。

增强视频与指令改写

• --enhanced-video — 除原始屏幕录制外，还会生成增强版视频，包含带有 Logo 的片头片尾、烧录字幕和关键时刻叠加效果。
• --enhance-instructions — 发布前使用项目知识库改写测试者指令（Enterprise+；项目必须成功运行过知识库）。

通知与组织范围

每项任务的通知覆盖设置可取 inherit（默认——依次采用项目设置和账户设置）、always 或 never：

runhuman job create https://staging.myapp.com -d "Test checkout" \
  --email always --in-app never \
  --email-on-failure always --in-app-on-failure always

账户隶属于多个组织时，传入 -o, --organization <id>，可将任务限定在特定组织范围内（与 job rerun 和 MCP create_job 工具的行为一致）。

异步工作流（创建、等待、获取结果）

如果不使用 --sync，请先创建任务，再单独等待：

# 1. Create the job (returns immediately)
JOB_ID=$(runhuman job create https://staging.myapp.com -d "Test search" --json | jq -r '.data.jobId')

# 2. Wait for the tester to complete (blocks with live status updates)
runhuman job wait "$JOB_ID"

# 3. Get the results
runhuman job results "$JOB_ID" --json

job wait 接受 --timeout <seconds>（默认值：600）。需要为脚本或自动化获取结构化输出时，可在任何命令中使用 --json。JSON 响应采用稳定的封装结构——列表数据位于 data.items，单个实体数据直接位于 data。

job status 和 job wait 都会输出 Recording: 行，报告屏幕录制是否已准备好下载（Ready to download、Processing，或在没有录制时省略）——获取录制文件前请先查看此信息。

模板

模板定义要测试的内容、测试时长以及要收集的结果。模板有三个来源，按以下顺序检查：

来源	位置	创建方式
仓库模板	用户仓库中的 .runhuman/templates/*.md	提交 Markdown 文件
项目模板	存储在 Runhuman 数据库中	使用 templates create 或通过仪表板创建
内置模板	随 Runhuman 一同提供	自动可用

内置模板

三个内置模板涵盖常见的 QA 场景：

模板	功能
查找 Bug	测试应用并报告 Bug，注明严重程度、复现步骤和预期行为
评估 UX	评估易用性、视觉设计、移动端适配性，并给出 1-10 分
提供产品反馈	提供真实反馈：第一印象、优点、不足和建议

仓库模板

仓库模板是 .runhuman/templates/ 中带有 YAML frontmatter 的 .md 文件：

---
name: Smoke Test
duration: 5
device_class: desktop
url: https://staging.example.com
---

Verify the app loads and core features work:

1. Load the homepage and confirm it renders without errors
2. Navigate to the login page and verify the form appears
3. Check that the main navigation links work

## Results

Page loads without errors: [ ]
Login form is accessible: [ ]
Navigation works: [ ]
Issues found: ___

Frontmatter 字段（均为可选）：name、duration（分钟，1-60）、device_class（desktop/mobile）、url、max_extension_minutes、extension_count、github_repos（由 owner/repo 字符串组成的 YAML 列表）。

通过 CLI 创建项目模板

runhuman templates create "Search Test" \
  --project proj_abc123 \
  -d "Search for 'recursion' and confirm the joke appears" \
  --schema ./search-test-schema.json

选项：--duration <minutes>（1-60）、--device-class <class>、--schema <path>。

列出模板：runhuman templates list --project <projectId>

作业输出：结果、构件、分享、问题

job results 是概览视图。如需原始数据访问或后续操作，可使用其他四个子命令：

# High-level results view (with optional rich-data flags)
runhuman job results <jobId>
runhuman job results <jobId> --transcript --console-logs
runhuman job results <jobId> --all          # every rich section
runhuman job results <jobId> --schema-only  # just extracted schema data
runhuman job results <jobId> --raw          # raw tester response

# Download a single raw artifact (good for piping)
runhuman job artifact <jobId> transcript
runhuman job artifact <jobId> console-logs --json | jq '.data.consoleMessages[]'
# Other types: structured-output, network-requests, conversation, events, key-moments

# Toggle public sharing — `share` prints the public URL
runhuman job share <jobId>
runhuman job unshare <jobId>

# File one extracted finding as a GitHub issue
runhuman job create-issue <jobId> --index 0
runhuman job create-issue <jobId> --index 0 --repo owner/repo  # override default

富数据部分（transcript、logs、network、events、key-moments、conversation）及相应的 job artifact 类型在服务端受付费套餐限制。未解锁访问权限的请求会返回清晰的“需要订阅”错误。

job create-issue 与仪表板中每条发现对应的“创建 Issue”按钮功能相同——它会原样提交该发现。如需之后修改标题或正文，请使用仪表板或 gh issue edit。

项目

runhuman projects list
runhuman projects create "My App" --organization <orgId> [--default-url <url>] [--github-repo <owner/repo>] [--github-repos <a/b,c/d>] [--set-default]
runhuman projects show <projectId>
runhuman projects update <projectId> [--name <text>] [--default-url <url>] [--github-repo <owner/repo>] [--github-repos <a/b,c/d>]
runhuman projects switch <projectId>            # `--global false` for current dir only
runhuman projects transfer <projectId> --to-org <orgId>   # full IDs required
runhuman projects delete <projectId> --force    # full ID required

--github-repo 接受单个 owner/repo；--github-repos 接受以逗号分隔的列表，并会替换项目的仓库集合（而非追加）。

组织

runhuman orgs list
runhuman orgs show <orgId>
runhuman orgs balance <orgId>
runhuman orgs projects <orgId>
runhuman orgs switch <orgId>                # `--global` (default) or local

# Membership
runhuman orgs members <orgId>
runhuman orgs invite <orgId> <email> --role <admin|contributor|viewer>
runhuman orgs remove <orgId> <userId>

# Pending invitations
runhuman orgs invitations list --organization <orgId>
runhuman orgs invitations revoke <invitationId> --organization <orgId> --yes

# Usage analytics
runhuman orgs usage                          # current org, last 30 days
runhuman orgs usage --period 7d              # 7d | 30d | 90d | all
runhuman orgs usage --year 2026 --month 4    # specific month (year+month)
runhuman orgs usage --json                   # full response, incl. overTime / byHour / bySource

orgs invite 默认使用 --role contributor。省略 --organization 时，invitations list/revoke 和 usage 会使用默认组织上下文。

账单

读取操作以用户为范围。购买流程和套餐变更仍需在 Web UI 中完成——使用 billing portal 前往。

runhuman billing balance                # credit balance for primary org (or --organization)
runhuman billing subscription           # current tier, period, add-ons
runhuman billing portal                 # one-time URL to the Polar customer portal
runhuman billing portal --open          # open it in the default browser

测试人员备注（付费功能）

备注是知识库条目，会作为补充上下文展示给测试人员。需要有效的组织订阅——否则调用会返回明确的“需要订阅”错误。

runhuman notes list                          # everything visible to you
runhuman notes list --search "checkout" --tags "context,gotcha"
runhuman notes show <noteId>
runhuman notes create "Auth context" -b "Use the demo account..." --tags "context"
runhuman notes create "Auth context" --body-file ./note.md --project <projectId>
runhuman notes update <noteId> [--title <t>] [--body <text> | --body-file <path>] [--tags <list>] [--public|--internal]
runhuman notes delete <noteId>               # full ID required

备注默认为仅内部可见；在 create/update 时传入 --public 可使其对客户可见。默认范围为组织，也可传入 --project 将范围限定为单个项目。

GitHub 集成

runhuman github link <owner/repo> --project <projectId>
runhuman github repos --organization <orgId> [--search <query>]
runhuman github issues <owner/repo> [--state open|closed|all] [--labels "bug,needs-qa"]
runhuman github test <issueNumber> -r <owner/repo> -u <url> [--template <id>] [--sync]
runhuman github bulk-test -r <owner/repo> -u <url> [--labels <list>] [--state <state>] [--limit <n>]

# Force-refresh a GitHub App installation's repo/permissions list — use after granting
# the app access to new repos if they don't show up in `github repos` yet.
runhuman github installation refresh --installation <installationId> --organization <orgId>

计划任务和传输

# Recurring scheduled jobs (cron-style)
runhuman schedules list
runhuman schedules create / show / update / delete   # see --help for each

# Project transfers (accept/reject/cancel a transfer to/from another org)
runhuman transfers list
runhuman transfers accept <transferId>
runhuman transfers reject <transferId>
runhuman transfers cancel <transferId>

运行 runhuman schedules --help 和 runhuman transfers --help 查看完整功能。

身份验证、初始化、配置

# Auth
runhuman login                    # browser OAuth
runhuman login --token <apiKey>   # non-interactive
runhuman logout
runhuman whoami

# Initialize a local .runhumanrc
runhuman init
runhuman init --name "My App" --github-repos "owner/frontend,owner/backend" --yes

# Config
runhuman config get <key>
runhuman config set <key> <value> [--global]
runhuman config list [--show-secrets]
runhuman config reset --project|--global|--all --force

配置优先级：CLI 标志 > 环境变量（RUNHUMAN_API_KEY、RUNHUMAN_API_URL、RUNHUMAN_PROJECT_ID、RUNHUMAN_NO_COLOR）> .runhumanrc（项目级）> ~/.config/runhuman/config.json（全局）> 默认值。

命令组

运行 runhuman <command> --help，可查看任意命令的完整用法。

组	命令	用途
Jobs	job create, status, wait, results, list, watch, artifact, share, unshare, create-issue	创建和管理 QA 测试任务（规范命名空间）
Auth	login, logout, whoami	身份验证
Init	init	在当前目录中初始化 .runhumanrc
Projects	projects list, create, show, update, switch, transfer, delete	管理项目
Organizations	orgs list, show, balance, projects, switch, members, invite, remove, invitations, usage	管理组织和成员
Billing	billing balance, subscription, portal	读取用户范围的账单信息
Templates	templates list, create, show, update, delete	可复用的测试配置
Schedules	schedules list, create, show, update, delete	定期计划任务
Transfers	transfers list, accept, reject, cancel	在组织之间转移项目
API Keys	keys list, create, show, delete	管理 API 密钥
GitHub	github link, repos, issues, test, bulk-test, installation refresh	GitHub 集成
Notes（付费）	notes list, show, create, update, delete	测试人员的知识库笔记
Config	config get, set, list, reset	CLI 配置

**提醒：**扁平的任务快捷命令（runhuman create、status、wait、results、list、watch）已弃用。新脚本中请始终使用 runhuman job <sub> 形式。

编写有效的测试描述

-d / --description 标志是测试中最重要的部分。请具体描述。

好示例：

Test the checkout process:
1. Add a product to cart
2. Click "Checkout"
3. Fill shipping address
4. Complete purchase
Report: bugs, UX confusions, mobile layout issues

差示例：

Test the site

提示：

• 写明要遵循的确切步骤或流程
• 指定要操作的页面和按钮
• 说明需要检查的内容（漏洞、UX 问题、视觉问题）
• 对于移动端测试，请在描述中明确说明

如果项目关联了代码仓库，Runhuman 就能了解代码库，返回的测试结果也会更丰富、更详细——你可以直接根据发现采取行动。请参阅 代码上下文文档。

CI/CD 集成

**当用户询问 CI/CD、GitHub Actions 或在流水线中自动化 QA 时：**请获取完整的 Agent 指南 https://runhuman.com/for_agents_github_actions.md，并按照其中的说明引导用户完成设置。该指南涵盖由 PR 触发的测试、定期探索式 QA、按需测试、标签管理，以及平台专属示例（Vercel、Netlify、Fly.io、Railway）。

**确定最新的 Action 版本：**编写任何工作流文件前，请运行 gh release list --repo volter-ai/runhuman-action --limit 1，或查看 https://github.com/volter-ai/runhuman-action/releases，确认 GitHub Action 的最新版本。请使用最新的版本标签，不要硬编码过时版本。

使用 GitHub Action（CI/CD 推荐方式）：

# .github/workflows/qa.yml
- name: Run QA tests
  uses: volter-ai/runhuman-action@v1  # Check latest version first
  with:
    url: ${{ env.PREVIEW_URL }}
    pr-numbers: '[${{ github.event.pull_request.number }}]'
    api-key: ${{ secrets.RUNHUMAN_API_KEY }}
    on-success-add-labels: '["qa:passed"]'
    on-failure-add-labels: '["qa:failed"]'
    fail-on-failure: true

**用于 PR 触发测试的代码上下文：**如果项目关联了代码仓库，请一并传入四个 code-context 输入项，让测试结果反映 PR 分支头部的代码，而非默认分支。

- uses: volter-ai/runhuman-action@v1
  with:
    url: ${{ env.PREVIEW_URL }}
    pr-numbers: '[${{ github.event.pull_request.number }}]'
    api-key: ${{ secrets.RUNHUMAN_API_KEY }}
    enable-code-context: true
    commit-sha: ${{ github.event.pull_request.head.sha }}
    commit-base-sha: ${{ github.event.pull_request.base.sha }}
    wait-for-code-context: true

请参阅 代码上下文文档，了解这些输入项的作用，以及提取的问题中会包含哪些内容。

在工作流中使用 CLI：

# Environment variable auth (for CI)
export RUNHUMAN_API_KEY=rh_live_...

# Synchronous test that blocks until complete
runhuman job create https://staging.myapp.com \
  -d "Test signup flow" \
  --sync \
  --wait 300

所有命令都支持 --json，可输出机器可读的数据。JSON 响应采用稳定的信封结构：成功时为 { success, data, pagination?, warnings?, timestamp }；失败时为 { success: false, error: { message, code?, details? }, timestamp }。列表命令将条目放在 data.items 中；单个实体命令将实体放在 data 中。

退出代码

代码	含义
0	成功
1	通用错误
2	身份验证错误
3	未找到
4	验证错误
5	超时
6	余额不足（请通过错误输出中的链接充值）

了解更多

# Top-level help
runhuman --help

# Help for any command
runhuman job create --help
runhuman projects --help
runhuman orgs invite --help
runhuman github installation refresh --help

资源

• 网站： https://runhuman.com
• 控制面板： https://runhuman.com/dashboard
• GitHub Action： https://github.com/marketplace/actions/runhuman-qa-test
• GitHub Actions 设置指南（面向 Agent）： https://runhuman.com/for_agents_github_actions.md - 当用户询问 GitHub Actions、CI/CD 管道或 QA 自动化时，获取此指南。