feat(android, harmony): add terminate action to support force-stopping apps and update documentation (#2214)

* feat(android,harmony): Added a terminate action to support forced application termination and supplemented documentation.

Added a terminate interface for Android and Harmony Agent.
Registered the Terminate action in the device action space, supporting forced termination of applications by package name or bundle name.
Completed unit tests for agent/device, covering success, URI truncation, and failure branches.

* fix(core): map yaml terminate shortcut to uri param

* fix(harmony): improve terminate app resolution

* ci(workflow): add workflow dispatch to ci and lint

* fix(visualizer): capitalize action names in playground dropdown

The actionNameForType function did not handle lowercase interfaceAlias
values (e.g. "launch", "terminate", "runHdcShell"), causing inconsistent
capitalization in the Device-Specific APIs dropdown.

---------

Co-authored-by: jeffjiang <jeffjiang@didiglobal.com>
Co-authored-by: quanruzhuoxiu <quanruzhuoxiu@gmail.com>

Author: 3 people

.github/workflows/ci.yml

@@ -5,6 +5,7 @@ on:
     branches:
       - main
   pull_request:
+  workflow_dispatch:
 
 permissions:
   contents: read

.github/workflows/lint.yml

@@ -6,6 +6,7 @@ on:
       - main
   pull_request:
     types: [opened, synchronize, reopened]
+  workflow_dispatch:
 
 permissions:
   contents: read

apps/site/docs/en/android-api-reference.mdx

@@ -17,6 +17,7 @@ Use this doc when you need to customize Midscene's Android automation or review
 - `Pinch` &mdash; Two-finger pinch gesture. Use `scale > 1` to zoom in, `scale < 1` to zoom out.
 - `ClearInput` &mdash; Clear the contents of an input field.
 - `Launch` &mdash; Open a web URL or `package/.Activity` string.
+- `Terminate` &mdash; Force-stop an app by package name.
 - `RunAdbShell` &mdash; Execute raw `adb shell` commands.
 - `AndroidBackButton` &mdash; Trigger the system back action.
 - `AndroidHomeButton` &mdash; Return to the home screen.
@@ -148,7 +149,7 @@ const agent = new AndroidAgent(device, {
 :::info
 
 - Use one agent per device connection.
-- Android-only helpers such as `launch` and `runAdbShell` are also exposed in YAML scripts. See [Android platform-specific actions](./automate-with-scripts-in-yaml#the-android-part).
+- Android-only helpers such as `launch`, `terminate`, and `runAdbShell` are also exposed in YAML scripts. See [Android platform-specific actions](./automate-with-scripts-in-yaml#the-android-part).
 - For shared interaction methods, see [API reference (Common)](./api#interaction-methods).
 
 :::
@@ -180,6 +181,20 @@ const result = await agent.runAdbShell('dumpsys battery');
 console.log(result);
 ```
 
+#### `agent.terminate()`
+
+Terminate (force-stop) a running Android app.
+
+```ts
+function terminate(uri: string): Promise<void>;
+```
+
+- `uri: string` &mdash; Package name, app name in `appNameMapping`, or `package/.Activity` (only the package part is used).
+
+```ts
+await agent.terminate('com.android.settings');
+```
+
 #### Navigation helpers
 
 - `agent.back(): Promise<void>` &mdash; Trigger the Android system Back action.

apps/site/docs/en/automate-with-scripts-in-yaml.mdx

@@ -276,6 +276,20 @@ tasks:
       - launch: https://www.example.com
 ```
 
+**`terminate` - Terminate App**
+
+Terminate (force-stop) a running Android app by package name.
+
+```yaml
+android:
+  deviceId: 'test-device'
+
+tasks:
+  - name: Terminate Settings app
+    flow:
+      - terminate: com.android.settings
+```
+
 ### The `ios` part
 
 ```yaml

apps/site/docs/en/harmony-api-reference.mdx

@@ -16,6 +16,7 @@ When you need to customize device behavior, integrate Midscene into a framework,
 - `ClearInput` — Clear input field contents.
 - ~~`Pinch`~~ — Not supported. The HarmonyOS `uitest` framework does not provide multi-touch input APIs.
 - `Launch` — Open a HarmonyOS app (bundle name).
+- `Terminate` — Force-stop a HarmonyOS app by bundle name.
 - `RunHdcShell` — Execute a raw `hdc shell` command.
 - `HarmonyBackButton` — Trigger system back.
 - `HarmonyHomeButton` — Return to home screen.
@@ -113,7 +114,7 @@ const agent = new HarmonyAgent(device, {
 :::info
 
 - One device connection corresponds to one Agent.
-- HarmonyOS-specific helpers like `launch` and `runHdcShell` can also be used in YAML scripts. See [HarmonyOS platform-specific actions](./automate-with-scripts-in-yaml#the-harmony-part).
+- HarmonyOS-specific helpers like `launch`, `terminate`, and `runHdcShell` can also be used in YAML scripts. See [HarmonyOS platform-specific actions](./automate-with-scripts-in-yaml#the-harmony-part).
 - For common interaction methods, see [API Reference (Common)](./api#interaction-methods).
 
 :::
@@ -150,6 +151,20 @@ const result = await agent.runHdcShell('hidumper -s RenderService -a screen');
 console.log(result);
 ```
 
+#### `agent.terminate()`
+
+Terminate (force-stop) a running HarmonyOS app.
+
+```ts
+function terminate(uri: string): Promise<void>;
+```
+
+- `uri: string` — Bundle name, app name in `appNameMapping`, or `bundle/Ability` (only the bundle part is used).
+
+```ts
+await agent.terminate('com.huawei.hmos.settings');
+```
+
 #### Navigation Helpers
 
 - `agent.back(): Promise<void>` — Trigger HarmonyOS system back.

apps/site/docs/zh/android-api-reference.mdx

@@ -17,6 +17,7 @@
 - `Pinch` —— 双指缩放手势。`scale > 1` 放大，`scale < 1` 缩小。
 - `ClearInput` —— 清空输入框内容。
 - `Launch` —— 打开网页或 `package/.Activity`。
+- `Terminate` —— 按包名强制停止应用。
 - `RunAdbShell` —— 执行原始 `adb shell` 命令。
 - `AndroidBackButton` —— 触发系统返回。
 - `AndroidHomeButton` —— 回到桌面。
@@ -147,7 +148,7 @@ const agent = new AndroidAgent(device, {
 :::info
 
 - 一个设备连接对应一个 Agent。
-- `launch`、`runAdbShell` 等 Android 专属辅助函数也可在 YAML 脚本中使用，语法见 [Android 平台特定动作](./automate-with-scripts-in-yaml#the-android-part)。
+- `launch`、`terminate`、`runAdbShell` 等 Android 专属辅助函数也可在 YAML 脚本中使用，语法见 [Android 平台特定动作](./automate-with-scripts-in-yaml#the-android-part)。
 - 通用交互方法请查阅 [API 参考（通用）](./api#interaction-methods)。
 
 :::
@@ -179,6 +180,20 @@ const result = await agent.runAdbShell('dumpsys battery');
 console.log(result);
 ```
 
+#### `agent.terminate()`
+
+终止（强制停止）正在运行的 Android 应用。
+
+```ts
+function terminate(uri: string): Promise<void>;
+```
+
+- `uri: string` —— 应用包名、`appNameMapping` 中的应用名称，或 `package/.Activity`（仅使用包名部分）。
+
+```ts
+await agent.terminate('com.android.settings');
+```
+
 #### 导航辅助
 
 - `agent.back(): Promise<void>` —— 触发 Android 系统的返回操作。

apps/site/docs/zh/automate-with-scripts-in-yaml.mdx

@@ -278,6 +278,20 @@ tasks:
       - launch: https://www.example.com
 ```
 
+**`terminate` - 终止应用**
+
+通过包名终止（强制停止）正在运行的 Android 应用。
+
+```yaml
+android:
+  deviceId: 'test-device'
+
+tasks:
+  - name: 终止设置应用
+    flow:
+      - terminate: com.android.settings
+```
+
 ### `ios` 部分
 
 ```yaml

apps/site/docs/zh/harmony-api-reference.mdx

@@ -16,6 +16,7 @@
 - `ClearInput` —— 清空输入框内容。
 - ~~`Pinch`~~ —— 不支持。HarmonyOS `uitest` 框架未提供多触点输入 API。
 - `Launch` —— 打开 HarmonyOS 应用（bundle name）。
+- `Terminate` —— 按 bundle name 强制停止应用。
 - `RunHdcShell` —— 执行原始 `hdc shell` 命令。
 - `HarmonyBackButton` —— 触发系统返回。
 - `HarmonyHomeButton` —— 回到桌面。
@@ -113,7 +114,7 @@ const agent = new HarmonyAgent(device, {
 :::info
 
 - 一个设备连接对应一个 Agent。
-- `launch`、`runHdcShell` 等 HarmonyOS 专属辅助函数也可在 YAML 脚本中使用，语法见 [HarmonyOS 平台特定动作](./automate-with-scripts-in-yaml#harmony-部分)。
+- `launch`、`terminate`、`runHdcShell` 等 HarmonyOS 专属辅助函数也可在 YAML 脚本中使用，语法见 [HarmonyOS 平台特定动作](./automate-with-scripts-in-yaml#harmony-部分)。
 - 通用交互方法请查阅 [API 参考（通用）](./api#interaction-methods)。
 
 :::
@@ -150,6 +151,20 @@ const result = await agent.runHdcShell('hidumper -s RenderService -a screen');
 console.log(result);
 ```
 
+#### `agent.terminate()`
+
+终止（强制停止）正在运行的 HarmonyOS 应用。
+
+```ts
+function terminate(uri: string): Promise<void>;
+```
+
+- `uri: string` —— 应用 bundle name、`appNameMapping` 中的应用名称，或 `bundle/Ability`（仅使用 bundle name 部分）。
+
+```ts
+await agent.terminate('com.huawei.hmos.settings');
+```
+
 #### 导航辅助
 
 - `agent.back(): Promise<void>` —— 触发 HarmonyOS 系统的返回操作。

packages/android/src/agent.ts

@@ -11,6 +11,7 @@ import {
   type DeviceActionAndroidRecentAppsButton,
   type DeviceActionLaunch,
   type DeviceActionRunAdbShell,
+  type DeviceActionTerminate,
 } from './device';
 import { getConnectedDevices } from './utils';
 
@@ -92,6 +93,16 @@ export class AndroidAgent extends PageAgent<AndroidDevice> {
     return action({ uri });
   }
 
+  /**
+   * Terminate (force-stop) an Android app by package name
+   * @param uri - Package name or app name to terminate
+   */
+  async terminate(uri: string): Promise<void> {
+    const action =
+      this.wrapActionInActionSpace<DeviceActionTerminate>('Terminate');
+    return action({ uri });
+  }
+
   /**
    * Execute ADB shell command on Android device
    * @param command - ADB shell command to execute

packages/android/src/device.ts

@@ -609,6 +609,27 @@ ${Object.keys(size)
     return this;
   }
 
+  /**
+   * Terminate (force-stop) an Android app by package name.
+   * Supports app name resolution via setAppNameMapping.
+   * If uri contains "/" (e.g. com.example.app/.MainActivity), only the package part is used.
+   */
+  public async terminate(uri: string): Promise<void> {
+    const packagePart = uri.includes('/') ? uri.split('/')[0] : uri;
+    const resolved = this.resolvePackageName(packagePart) ?? packagePart;
+    const adb = await this.getAdb();
+    try {
+      debugDevice(`Terminating app: ${resolved}`);
+      await adb.shell(`am force-stop ${resolved}`);
+      debugDevice(`Successfully terminated: ${resolved}`);
+    } catch (error: any) {
+      debugDevice(`Error terminating ${resolved}: ${error}`);
+      throw new Error(`Failed to terminate ${resolved}: ${error.message}`, {
+        cause: error,
+      });
+    }
+  }
+
   async execYadb(
     keyboardContent: string,
     options?: { overwrite?: boolean },
@@ -1989,17 +2010,28 @@ const launchParamSchema = z.object({
     ),
 });
 
+const terminateParamSchema = z.object({
+  uri: z
+    .string()
+    .describe(
+      'Package name or app name to terminate. Use the exact package name, e.g. com.android.settings.',
+    ),
+});
+
 type RunAdbShellParam = z.infer<typeof runAdbShellParamSchema>;
 type LaunchParam = z.infer<typeof launchParamSchema>;
+type TerminateParam = z.infer<typeof terminateParamSchema>;
 
 export type DeviceActionRunAdbShell = DeviceAction<RunAdbShellParam, string>;
 export type DeviceActionLaunch = DeviceAction<LaunchParam, void>;
+export type DeviceActionTerminate = DeviceAction<TerminateParam, void>;
 
 const createPlatformActions = (
   device: AndroidDevice,
 ): {
   RunAdbShell: DeviceActionRunAdbShell;
   Launch: DeviceActionLaunch;
+  Terminate: DeviceActionTerminate;
   AndroidBackButton: DeviceActionAndroidBackButton;
   AndroidHomeButton: DeviceActionAndroidHomeButton;
   AndroidRecentAppsButton: DeviceActionAndroidRecentAppsButton;
@@ -2040,6 +2072,18 @@ const createPlatformActions = (
         await device.launch(param.uri);
       },
     }),
+    Terminate: defineAction<typeof terminateParamSchema, TerminateParam, void>({
+      name: 'Terminate',
+      description: 'Terminate (force-stop) an Android app by package name',
+      interfaceAlias: 'terminate',
+      paramSchema: terminateParamSchema,
+      call: async (param) => {
+        if (!param.uri || param.uri.trim() === '') {
+          throw new Error('Terminate requires a non-empty uri parameter');
+        }
+        await device.terminate(param.uri);
+      },
+    }),
     AndroidBackButton: defineAction({
       name: 'AndroidBackButton',
       description: 'Trigger the system "back" operation on Android devices',