Appearance
AI Agent、MCP 与 Runner
CueCast 可以通过 MCP 接入 Codex 等 AI 编程工具。AI Agent 负责分析代码改动、查找用例和发起执行;CueCast Chrome 扩展作为有头浏览器 Runner,在真实页面完成回放或录制;执行结果仍保存到 CueCast,便于团队查看和追溯。
text
AI 编程工具 → CueCast MCP → CueCast 服务 → Chrome 扩展 Runner → 目标页面
↘ 执行结果与报告使用前准备
- 至少有一个可访问的项目。
- 已安装最新版 CueCast Chrome 扩展。
- Chrome、扩展和已登录 CueCast 的中台页面保持运行。
- 本机已安装 Node.js 18 或更高版本。
- 创建 API Token;普通成员需要联系组织管理员安全获取 Token。
Runner 与发起请求的 API Token 必须属于同一组织。当前提供的是有头浏览器扩展 Runner,不会自动唤醒已关闭的电脑或 Chrome。
三步接入 AI Agent
1. 创建 API Token
组织 Owner 或 Admin 进入「设置 → API Token」,点击「创建 Token」。建议:
- 创建时默认勾选
test:read、test:write、run:create、run:read、report:read五项权限;不需要通过 MCP 修改用例时,可取消test:write。 - 只允许操作一个项目时,选择对应的项目范围。
- 根据使用周期设置过期日期,不再使用时及时撤销。
Token 明文只在创建后展示一次。请在关闭弹窗前保存,并通过安全方式交给需要配置 MCP 的人员;不要把 Token 写进代码、提交到 Git 或粘贴到公开对话中。
权限、项目范围、调用示例、轮换和撤销方式详见 API Token。
2. 让 AI 完成安装
在 API Token 页面点击「MCP / Skill 使用指南」,进入「AI Agent」页面,复制第二步的安装指令并发送给 Codex。AI 会按照当前 CueCast 环境提供的在线说明:
- 下载并配置 CueCast MCP。
- 安装
cuecast-regressionSkill。 - 在确实需要时单独向你索取 API Token。
- 将 Token 写入用户级 MCP 配置,而不是项目仓库。
- 验证 MCP 是否可以连接 CueCast。
安装完成后,按 AI 的提示重新连接或重启 MCP 客户端,使新配置生效。
3. 发送使用指令
「AI Agent」页面提供三类可直接复制的指令:
- 分析当前分支的代码改动,匹配并运行关联回归用例。
- 查看当前项目的全部用例及状态。
- 执行指定分组下的用例并汇总结果。
Token 可以访问多个项目时,AI 会根据当前仓库配置和任务上下文选择;仍有多个合理候选时,应先向你确认项目。
MCP 可以做什么
| 能力 | 说明 |
|---|---|
| 查询资产 | 查询项目、分组、测试用例和执行计划;用例中的敏感值保持脱敏。 |
| 修改步骤 | 读取用例后,按步骤 ID 和版本修改描述、固定输入/下拉选项值、断言、执行前等待或手动定位;已标记脱敏的输入会由服务端加密保存。需要 test:write。 |
| 批量修改起始 URL | 对项目、分组或指定用例先预览修改,再凭预览令牌应用;可统一设置 URL,或替换域名并保留路径。应用需要 test:write。 |
| 执行与报告 | 运行单条用例或执行计划,查询进度、取消任务并读取持久化报告。 |
| 自动真实录制 | 创建录制会话,让扩展在真实页面执行经确认的语义操作并保存为 CueCast 用例。 |
执行请求支持幂等键。同一 Token 使用相同幂等键和相同参数重试时会返回原任务,避免因网络不确定而重复产生业务操作;相同键对应不同参数会被拒绝。
使用 preview_start_url_change 查看影响范围、跳过项和默认地址变化,再将相同参数及返回的 preview_token 传给 apply_start_url_change。若用例在两次调用间发生变化,应用会拒绝并要求重新预览。项目或分组范围默认同步更新对应默认地址;指定用例范围不会更新默认地址。录制步骤中的跳转地址和计划登录检查地址不在修改范围内。
修改步骤时,先调用 get_testcase,取得目标步骤的 id 和 step_revision,再调用 update_testcase_step,传入 test_case_id、step_id、expected_step_revision 和要修改的字段:description、value、wait_before(0~120000 毫秒)、assertion_target、assertion_match、target_selector(CSS)或 target_xpath。value 适用于固定 input、原生 select、assert_text 和 assert_json;断言目标与匹配方式只适用于 assert_text,其中 visible 仅适用于元素断言。只提交 CSS 或 XPath 时,另一种旧定位会被清除;录制时的候选定位和元素上下文也会被替换,标签页上下文保留。步骤被他人修改后会返回 409,需重新读取。修改后建议重新回放。
已标记脱敏的输入步骤可以提交新密码:MCP 请求中的新值是明文,CueCast 服务端收到后加密入库,读取和更新响应继续返回掩码。明文仍会经过 AI 客户端、MCP 进程和网络请求链路;请确认所用工具和日志环境可处理敏感信息,不要写入版本库或步骤描述。若不希望 AI 客户端接触密码,请在用例详情页修改。空密码和掩码占位符不能用于修改脱敏值。动态生成的输入值仍需在用例详情页编辑。
执行超时怎么计算
| 调用方式 | 默认超时 | 计算范围 |
|---|---|---|
| 运行一条用例 | 600 秒 | 本次单用例任务。超长用例可显式设置,最长 3600 秒。 |
| 运行一个执行计划 | 3600 秒 | 整个计划共用,包括登录准备和计划内所有用例;不是每条用例各 3600 秒。 |
| 自动录制 | 900 秒 | Runner 开始录制后的活动时间;可设置为 300–3600 秒。 |
需要长期维护的多用例回归建议使用执行计划。
默认情况下 MCP 会等待任务进入终态并返回已保存的报告。异步场景可以只提交任务,再按 Run ID 查询状态。超时同时约束服务端任务时限和本次 MCP 同步等待窗口。
扩展 Runner 的工作方式
登录 CueCast 中台后,扩展会注册当前浏览器设备,并定期领取同组织的单用例、执行计划或录制任务。任务可能短暂显示为「排队中」;领取后会进入「执行中」。
Runner 执行单用例时沿用中台手动执行的窗口和视口配置。执行计划会:
- 按计划配置处理登录准备。
- 按保存顺序执行各业务用例。
- 遵循「全部执行」或「失败即停止」策略。
- 保存逐用例结果和计划汇总报告。
计划中的多条用例共用一个计划超时。含无痕用例的计划仍受中台的登录会话复用限制。
用 AI 做代码变更回归
cuecast-regression Skill 将回归拆成三个独立阶段:
- 分析与执行:读取本地代码改动,提炼受影响的 Web 场景,匹配并运行已有 CueCast 用例,返回执行结果和覆盖缺口。
- 规划缺失用例:只有你确认需要规划后,AI 才会给出完整的前置条件、操作、测试数据和断言。
- 自动录制:只有你再次确认完整方案后,AI 才会启动真实页面录制。新用例保存后还应独立回放通过,才能视为验证完成。
规划确认不等于授权录制。可能创建、修改或删除真实业务数据的步骤,应在录制方案中明确说明。
自动真实录制的范围
自动录制复用现有 CueCast 录制器:AI 提交语义操作计划,扩展通过浏览器原生点击和输入操作真实元素,录制器继续生成定位信息、上下文和步骤截图。计划支持常规点击、输入和文本断言;遇到元素歧义或页面状态不符时,AI 可以读取精简页面快照后继续处理。
当前限制:
- 单次语义计划最多 30 个操作。
- 适合主页面中的常规导航、按钮和表单。
- iframe、文件上传、复杂拖拽、键盘组合、视觉观察和需要人工登录介入的流程暂不适合自动录制。
- 敏感输入应标记为敏感值;密码控件继续遵循 CueCast 的密码脱敏规则。
- 保存录制只代表用例资产已创建,不代表回放已经通过。
常见问题
提示没有可用 Runner
确认 Chrome 正在运行、CueCast 扩展已启用、中台仍保持登录,并且登录组织与 API Token 所属组织一致。刷新一次 CueCast 页面后,再让 AI 检查 Runner 状态。
任务长时间排队或变成已超时
Runner 会定期领取任务,因此排队可能有短暂延迟。如果扩展在排队后离线、任务超过总时限或执行租约失效,任务会进入明确的终态。系统不会自动重放已经开始的任务,以免重复提交真实业务操作。
MCP 已安装但 AI 看不到工具
重新连接或重启 MCP 客户端,并确认用户级配置中的 API 地址和 Token 对应当前 CueCast 环境。若 Token 已过期或被撤销,请创建新 Token 后更新配置。
执行完成后,可以在执行历史中按来源选择 MCP,集中查看用例和计划结果。
