finalrun-test-runner

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

FinalRun Test Runner

FinalRun 测试运行器

Orchestrate FinalRun MCP tools to run mobile app tests on cloud or local devices.

编排FinalRun MCP工具，在云端或本地设备上运行移动应用测试。

MCP Preflight

MCP预检查

Before any test operation:

Run
```
ping
```
.
If ping fails, the FinalRun MCP server may not be installed or configured. Ask the user to verify their MCP setup.
Resume this workflow only after MCP is healthy.

执行任何测试操作前：

运行
```
ping
```
命令。
如果ping失败，说明FinalRun MCP服务器可能未安装或配置不正确，请用户确认其MCP设置。
只有MCP状态正常后，才能继续后续工作流。

Core Concepts

核心概念

Test: A single automated flow (one scenario).
Test Suite: An ordered group of tests executed together on a device.
Test Runs: Historical execution records of tests or suites that already ran.

测试（Test）：单个自动化流程（一个场景）。
测试套件（Test Suite）：一组按顺序排列的测试，会在同一台设备上一起执行。
测试运行记录（Test Runs）：已经执行过的测试或测试套件的历史执行记录。

Your Only Job

你的核心职责

Find the test or suite to run
Select the target device(s) — cloud or local
Map the app binary — use an existing app, or upload a new one if not available
Confirm the run plan with the user
Execute the test run

For creating tests, see
finalrun-generate-test
. For updating or deleting tests, see
finalrun-update-test
.

查找需要运行的测试或测试套件
选择目标设备——云端或本地
映射应用二进制包——使用现有应用，如果没有可用版本则上传新的二进制包
与用户确认运行计划
执行测试运行

如需创建测试，请参考
finalrun-generate-test
。如需更新或删除测试，请参考
finalrun-update-test
。

Required Inputs

必要输入项

Run Test: test name +
```
appMapping
```
+ one compatible device target (cloud or local)
Run Test Suite: suite name +
```
appMapping
```
+ one compatible device target (cloud or local)

运行单测试：测试名称 +
```
appMapping
```
+ 一个兼容的目标设备（云端或本地）
运行测试套件：套件名称 +
```
appMapping
```
+ 一个兼容的目标设备（云端或本地）

User Input & Credentials

用户输入与凭证

Tests often require user-specific data such as login credentials, form values, environment URLs, or account details. Follow these rules:

Never guess or fabricate credentials, emails, passwords, API keys, or environment-specific values.
Ask the user before proceeding if any required test input is unknown — this includes but is not limited to:
- Login credentials (username, email, password)
- Form field values (addresses, phone numbers, payment details)
- Environment-specific URLs or endpoints
- Account-specific data (user IDs, org names, project names)
Ask early — identify required inputs during Step 1 (finding the test) and resolve them before Step 4 (confirming the run plan).
Include provided values in the run plan confirmation so the user can verify them.

Not asking the user for unknown inputs is a blocker — do not skip this step.

测试通常需要用户专属数据，比如登录凭证、表单值、环境URL或账户详情。请遵循以下规则：

永远不要猜测或捏造凭证、邮箱、密码、API密钥或环境专属值。
如果有任何必填测试输入项未知，请先询问用户再继续，包括但不限于：
- 登录凭证（用户名、邮箱、密码）
- 表单字段值（地址、手机号、支付信息）
- 环境专属URL或端点
- 账户专属数据（用户ID、组织名称、项目名称）
尽早询问——在步骤1（查找测试）阶段就识别必填输入项，在步骤4（确认运行计划）前解决所有未知项。
在运行计划确认环节包含用户提供的所有值，方便用户核对。

不为未知输入项询问用户属于严重阻塞问题——不要跳过该步骤。

Platform Compatibility Rule (Strict)

平台兼容性规则（严格执行）

Android app upload -> Android devices only
iOS app upload -> iOS devices only
Never map Android app to iOS device, or iOS app to Android device
For
```
platform
```
and
```
autoSelectPlatform
```
parameters, use these exact values:
```
Android
```
or
```
IOS
```
In prose, "iOS" and
```
IOS
```
refer to the same platform; use
```
IOS
```
only when setting MCP arguments.

Android应用上传→仅可使用Android设备
iOS应用上传→仅可使用iOS设备
永远不要将Android应用映射到iOS设备，也不要将iOS应用映射到Android设备
对于
```
platform
```
和
```
autoSelectPlatform
```
参数，请使用以下精确值：
```
Android
```
或
```
IOS
```
在文本描述中，"iOS"和
```
IOS
```
指代同一平台；仅在设置MCP参数时使用
```
IOS
```
。

Workflow Steps

工作流步骤

Step 1 — Find the Test or Suite

步骤1 — 查找测试或测试套件

Search for the test or suite to run:

Use MCP tool: list_tests
Arguments: { "search": "<test name keyword>" }

Or for suites:

Use MCP tool: list_test_suites
Arguments: { "search": "<suite name keyword>" }

If the test or suite doesn't exist, follow the

finalrun-generate-test

workflow to create it first.

搜索需要运行的测试或测试套件：

Use MCP tool: list_tests
Arguments: { "search": "<test name keyword>" }

如果是查找测试套件：

Use MCP tool: list_test_suites
Arguments: { "search": "<suite name keyword>" }

如果对应的测试或测试套件不存在，请先遵循

finalrun-generate-test

工作流创建。

Step 2 — Select Target Devices

步骤2 — 选择目标设备

Cloud devices:

Use MCP tool: list_supported_devices
Arguments: { "platform": "Android" }  # or "IOS"

Note the

requirementId

for the target device(s).

Local devices:

Use MCP tool: list_local_devices
Arguments: {}

Note the

uuid

for the target device. Ensure local prerequisites are met (see Local Run Prerequisites section).

云端设备：

Use MCP tool: list_supported_devices
Arguments: { "platform": "Android" }  # or "IOS"

记录目标设备的

requirementId

。

本地设备：

Use MCP tool: list_local_devices
Arguments: {}

记录目标设备的

uuid

。确保满足本地运行前置条件（参见本地运行前置条件章节）。

Step 3 — Resolve App Mapping

步骤3 — 确认应用映射

Search for the app binary to use:

Use MCP tool: available_apps
Arguments: { "search": "<app name>", "platform": "Android" }  # or "IOS"

If app exists — if the user specified an upload, use that exact
```
appId
```
+
```
appUploadId
```
; otherwise, ask the user to choose the upload from the returned platform-compatible list
If no app is available — upload a new binary following the Upload Routing Rule below

Platform inference:

If app has uploads for only one platform — platform is already determined, select matching devices automatically without asking the user
If app has uploads for both platforms — ask the user which platform to run on

Enforce platform compatibility: Android app → Android device, iOS app → iOS device.

搜索要使用的应用二进制包：

Use MCP tool: available_apps
Arguments: { "search": "<app name>", "platform": "Android" }  # or "IOS"

如果应用已存在——如果用户指定了要上传的版本，使用对应的
```
appId
```
+
```
appUploadId
```
；否则请用户从返回的平台兼容列表中选择要使用的上传版本
如果没有可用应用——遵循下方的上传路由规则上传新的二进制包

平台推断：

如果应用仅上传过一个平台的版本——平台已确定，自动选择匹配的设备，无需询问用户
如果应用上传过两个平台的版本——询问用户要在哪个平台运行

强制执行平台兼容性：Android应用→Android设备，iOS应用→iOS设备。

Step 4 — Confirm the Run Plan

步骤4 — 确认运行计划

Present the run plan to the user for confirmation:

Test or suite name to run
Target device(s) and platform
App binary version (appId + appUploadId)
Cloud or local execution

Do not start the run until the user confirms the plan.

向用户展示运行计划，请其确认：

要运行的测试或测试套件名称
目标设备和平台
应用二进制包版本（appId + appUploadId）
云端或本地执行

用户确认计划前，不要启动运行。

Step 5 — Execute the Run

步骤5 — 执行运行

Cloud — Single Test:

Use MCP tool: run_test_by_name_on_devices
Arguments:
  testName: "<test name>"
  devices: [{ "cloudRequirementId": "<requirement-id>" }]
  appMapping: { "<appId>": "<appUploadId>" }

Cloud — Test Suite:

Use MCP tool: run_test_suite_by_name_on_devices
Arguments:
  testSuiteName: "<suite name>"
  devices: [{ "cloudRequirementId": "<requirement-id>" }]
  appMapping: { "<appId>": "<appUploadId>" }

Local — Single Test:

Use MCP tool: run_test_locally
Arguments:
  testName: "<test name>"
  deviceUUID: "<device-uuid>"
  appMapping: { "<appId>": "<appUploadId>" }

Local — Test Suite:

Use MCP tool: run_test_suite_locally
Arguments:
  testSuiteName: "<suite name>"
  deviceUUID: "<device-uuid>"
  appMapping: { "<appId>": "<appUploadId>" }

To stop a running local test:

Use MCP tool: stop_local_test_run
Arguments: { "testRunId": "<test-run-id>" }

云端——单测试：

Use MCP tool: run_test_by_name_on_devices
Arguments:
  testName: "<test name>"
  devices: [{ "cloudRequirementId": "<requirement-id>" }]
  appMapping: { "<appId>": "<appUploadId>" }

云端——测试套件：

Use MCP tool: run_test_suite_by_name_on_devices
Arguments:
  testSuiteName: "<suite name>"
  devices: [{ "cloudRequirementId": "<requirement-id>" }]
  appMapping: { "<appId>": "<appUploadId>" }

本地——单测试：

Use MCP tool: run_test_locally
Arguments:
  testName: "<test name>"
  deviceUUID: "<device-uuid>"
  appMapping: { "<appId>": "<appUploadId>" }

本地——测试套件：

Use MCP tool: run_test_suite_locally
Arguments:
  testSuiteName: "<suite name>"
  deviceUUID: "<device-uuid>"
  appMapping: { "<appId>": "<appUploadId>" }

停止正在运行的本地测试：

Use MCP tool: stop_local_test_run
Arguments: { "testRunId": "<test-run-id>" }

Local Run Prerequisites

本地运行前置条件

Before executing a Local Test Run or Local Test Suite Run:

Android: Ensure
```
adb
```
is installed. Verify by running
```
which adb
```
. If not present, install via Homebrew (
```
brew install android-platform-tools
```
) or Android Studio.
iOS: Ensure
```
xcrun
```
is available (mac only). Verify by running
```
which xcrun
```
. If not present, run
```
xcode-select --install
```
.

执行本地测试运行或本地测试套件运行前：

Android：确保已安装
```
adb
```
。运行
```
which adb
```
验证。如果未安装，可通过Homebrew安装（
```
brew install android-platform-tools
```
）或通过Android Studio安装。
iOS：确保
```
xcrun
```
可用（仅支持macOS）。运行
```
which xcrun
```
验证。如果未安装，运行
```
xcode-select --install
```
。

Upload Routing Rule

上传路由规则

When user asks to upload a new build, always ask:

"Should this upload go to an existing app or a new app container?"
"Confirm platform: Android or iOS?"

Then follow:

Existing app path
- Call
```
available_apps
```
- Filter/select by platform (
```
Android
```
  or
```
IOS
```
  )
- Pick target app node by
```
appId
```
  , then read its
```
appName
```
- Call
```
create_app_version(appName, filePath)
```
  using that exact
```
appName
```

New app path

Confirm platform (
```
Android
```
or
```
IOS
```
)
Call
```
create_app(name, appKnowledge?)
```
-> get
```
appId
```
Call
```
create_app_version(appName, filePath)
```
to upload first version

当用户要求上传新构建版本时，务必询问：

"本次上传要添加到现有应用还是新建应用容器？"
"确认平台：Android还是iOS？"

然后遵循以下流程：

现有应用路径
- 调用
```
available_apps
```
- 按平台（
```
Android
```
  或
```
IOS
```
  ）过滤/选择
- 通过
```
appId
```
  选择目标应用节点，读取其
```
appName
```
- 使用对应
```
appName
```
  调用
```
create_app_version(appName, filePath)
```

新建应用路径

确认平台（
```
Android
```
或
```
IOS
```
）
调用
```
create_app(name, appKnowledge?)
```
-> 获取
```
appId
```
调用
```
create_app_version(appName, filePath)
```
上传首个版本

App Mapping

应用映射

When running a test or suite,

appMapping

is required.

Identity rules:

```
appId
```
identifies the app container (the same app record that includes
```
appName
```
).
```
appUploadId
```
identifies the uploaded version/build under that app.

Canonical format:

json

{ "appId": "appUploadId" }

Use

available_apps

response to get valid pairs.

运行测试或测试套件时，

appMapping

是必填项。

标识规则：

```
appId
```
标识应用容器（包含
```
appName
```
的同一条应用记录）。
```
appUploadId
```
标识该应用下上传的版本/构建包。

标准格式：

json

{ "appId": "appUploadId" }

使用

available_apps

的返回结果获取有效的映射对。

Device Targeting

设备选择

For cloud runs, each device target must include exactly one:

```
cloudRequirementId
```
— from
```
list_supported_devices
```
, targets a specific cloud device
```
autoSelectPlatform
```
(
```
Android
```
or
```
IOS
```
) — auto-assigns any available device of that platform

For local runs:

Use
```
list_local_devices
```
to discover connected devices
Provide
```
deviceUUID
```
from the discovered device

Decision flow:

Ask: Local or Cloud run?
Cloud → Ask: auto-select or specific device?
- Auto-select → use
```
autoSelectPlatform
```
  (derived from app platform)
- Specific → use
```
list_supported_devices
```
  → pick
```
cloudRequirementId
```
Local → use
```
list_local_devices
```
→ pick
```
deviceUUID
```

对于云端运行，每个目标设备必须恰好包含以下其中一项：

```
cloudRequirementId
```
——来自
```
list_supported_devices
```
，指向特定的云端设备
```
autoSelectPlatform
```
（
```
Android
```
或
```
IOS
```
）——自动分配该平台下任意可用设备

对于本地运行：

使用
```
list_local_devices
```
发现已连接的设备
提供发现设备的
```
deviceUUID
```

决策流程：

询问：本地还是云端运行？
云端 → 询问：自动选择设备还是指定设备？
- 自动选择 → 使用
```
autoSelectPlatform
```
  （从应用平台推导）
- 指定设备 → 调用
```
list_supported_devices
```
  → 选择
```
cloudRequirementId
```
本地 → 调用
```
list_local_devices
```
→ 选择
```
deviceUUID
```

Two-Phase Confirmation Pattern

两阶段确认模式

For update/delete bulk actions in other workflows (for example,

finalrun-update-test

text

Step 1: Call without confirm=true -> receive preview + confirmationToken
Step 2: Call with confirm=true + confirmationToken -> execute

Always show preview to user before confirm.

This two-phase pattern does not apply to

run_test_by_name_on_devices

run_test_suite_by_name_on_devices

run_test_locally

, or

run_test_suite_locally

对于其他工作流中的更新/删除批量操作（例如

finalrun-update-test

）：