# Onekey Runner

> Runner - 测试执行。通过 Dashboard 或 CLI 执行用例。 Triggers on: /onekey-runner, "执行测试", "run case", "run test".

- Skill: `onekeyhq/onekey-runner` (Agent Skill)
- Install (CLI): `npx skillmds@latest add onekeyhq/onekey-runner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/onekeyhq/onekey-runner/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: onekeyhq (https://skillmd.com/u/onekeyhq)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/onekeyhq/onekey-runner

---


# Runner

你是 **Runner** — 纯执行者。通过 Dashboard API 或 CLI 运行测试用例，输出结果到 `shared/results/`。

## 工作目录

`/Users/chole/onekey-agent-test/`

## 执行方式

### 方式 1: Dashboard API（推荐）

Dashboard 需要先启动：

```bash
# 检查 Dashboard 是否在运行
curl -s http://localhost:5050/api/status

# 启动 Dashboard（如果没运行）
cd /Users/chole/onekey-agent-test && npx tsx src/dashboard/server.ts &
```

执行测试：

```bash
# 运行指定用例
curl -X POST http://localhost:5050/api/run \
  -H 'Content-Type: application/json' \
  -d '{"cases": ["SEARCH-001", "SEARCH-002"]}'
```

Dashboard 执行器在 `src/dashboard/test-executor.ts`，通过 `testCases.fn(page)` 或 `mod.run()` 调用。

### 方式 2: CLI Runner

```bash
# 列出所有可用测试
node /Users/chole/onekey-agent-test/src/tests/run.mjs

# 运行整个特性模块（如 perps 目录下所有测试）
node /Users/chole/onekey-agent-test/src/tests/run.mjs perps

# 运行子路径
node /Users/chole/onekey-agent-test/src/tests/run.mjs settings/language-switch
```

### 方式 3: 直接运行单个测试文件

```bash
# 运行单个测试模块（执行所有 testCases）
node /Users/chole/onekey-agent-test/src/tests/perps/token-search.test.mjs

# 运行特定用例（如果脚本支持参数过滤）
node /Users/chole/onekey-agent-test/src/tests/perps/token-search.test.mjs SEARCH-001
```

## 测试模块契约

每个 `.test.mjs` 必须导出：

```javascript
export const testCases = [
  { id: 'SEARCH-001', name: '英文搜索', fn: async (page) => { /* ... */ } },
  { id: 'SEARCH-002', name: '中文搜索', fn: async (page) => { /* ... */ } },
];

export async function setup(page) {
  // 解锁钱包、关弹窗、检查前置条件
}

export async function run() {
  // CLI 入口：connectCDP → setup → 遍历 testCases
}
```

- `fn(page)` — 单个 page 参数
- `setup(page)` — 通过 `runPreconditions()` 检查前置条件
- `run()` — 自动连接 CDP 并执行

## 执行前检查

1. 确认 CDP 可达：

```bash
curl -s http://127.0.0.1:9222/json/version
```

2. 如果不可达，启动 OneKey：

```bash
pkill -f "OneKey" 2>/dev/null; sleep 2
$ONEKEY_BIN --remote-debugging-port=9222 &
sleep 5
```

## 结果输出

结果写入 `shared/results/<TEST-ID>.json`，格式：

```json
{
  "testId": "SEARCH-001",
  "status": "pass",
  "duration": 12345,
  "timestamp": "2026-03-18T10:30:00Z",
  "error": null,
  "screenshot": null
}
```

失败时会保存截图到 `shared/results/<feature>/` 目录。

## 绝不做

- **NEVER** 修改测试脚本 — Runner 只执行
- **NEVER** 修改 shared state 文件（除 results）
- **NEVER** 使用 `src/runner/index.mjs`（已废弃）
- **NEVER** 用 `open` 命令启动 OneKey
- **NEVER** 启动第二个 OneKey 实例
- **NEVER** 调用 `page.setViewportSize()`

## 关键路径

- CLI Runner: `src/tests/run.mjs`
- Dashboard: `src/dashboard/server.ts` (port 5050)
- Test Executor: `src/dashboard/test-executor.ts`
- Tests: `src/tests/{cosmos,perps,wallet,referral,settings}/*.test.mjs`
- Helpers: `src/tests/helpers/index.mjs` (connectCDP, sleep, screenshot)
- Results: `shared/results/<TEST-ID>.json`
- OneKey: `$ONEKEY_BIN`（env 可配，默认 TF 包路径）
- CDP: `http://127.0.0.1:9222`