diff --git a/docs/evidence/harmonyos-launch-args-2026-11-23.md b/docs/evidence/harmonyos-launch-args-2026-11-23.md new file mode 100644 index 0000000000..78ce5c640e --- /dev/null +++ b/docs/evidence/harmonyos-launch-args-2026-11-23.md @@ -0,0 +1,121 @@ +# HarmonyOS open --launch-args forwarding, 2026-11-23 + +Evidence for #4287 (forward `open --launch-args` to `aa start` verbatim), re-run at the +rebased head. The option forwards each entry as one argument of the `aa start` argv. The +CLI adds no `--ps`/`--pi` words of its own: every parameter word in this run is one the +caller chose. + +## Build under test + +- Source SHA `306a2f397`, branch `forge/launch-args-harmony`, commit + `feat(harmonyos): forward open --launch-args to aa start verbatim` +- Build: `pnpm install --frozen-lockfile && pnpm build` in the branch worktree. The CLI + and the daemon ran from that dist. +- The daemon ran under an isolated `AGENT_DEVICE_HOME`, so no other build served these + commands. + +## Device + +- HUAWEI 畅享 90 Plus, model `JDY-AL50`, HarmonyOS 7.0.0.111 (SP10C00E111R4P3), API 26, USB +- Serial ``. The app is a personal data-carrying user app, driven read-only and + named `` below. + +The app is force-stopped before cases (a), (b) and (c), so the recorded foreground state +belongs to that launch. + +## (a) `--activity` route with parameter words + +```sh +$ agent-device open --platform harmonyos --serial --activity EntryAbility \ + --launch-args --ps --launch-args k --launch-args v +Opened: +$ hdc -t shell "aa dump -l" + Mission ID #102 mission name #[#:entry:EntryAbility] lockedState #0 mission affinity #[] + AbilityRecord ID #21149 + app name [] + main name [EntryAbility] + bundle name [] + ability type [PAGE] + state #FOREGROUND start time [1444191858] + app state #FOREGROUND + ready #1 window attached #0 launcher #0 +``` + +## (b) no `--activity`, the `bm dump` route + +```sh +$ agent-device open --platform harmonyos --serial \ + --launch-args --ps --launch-args k --launch-args v +Opened: +``` + +The `aa dump -l` mission block matches case (a). The unit test +`openHarmonyApp keeps the module flag ahead of launch args on the bm dump route` pins the +argv: `-m ` precedes the forwarded entries. + +## (c) a value with shell-live characters: the launch fails, and that is the finding + +The review asks that a value carrying `$`, `"` and `\` arrives literally with nothing +executed. At this head it does not arrive at all: + +```sh +$ agent-device open --platform harmonyos --serial --activity EntryAbility \ + --launch-args '$(id)"q"\c' +Error (COMMAND_FAILED): Failed to start +[exit=1] +``` + +The failure reproduced twice, with the app force-stopped before each attempt. A manual +`hdc shell aa start ... --ps ` with the unescaped value, run after the session as a +diagnostic, answers `invalid number of parameters for option --ps`. That repro bypasses +the branch's escaping, so it shows only how `aa` counts operands. The branch run's own +device-side stdout was not captured in the request log. What the two branch runs prove is +narrower: at this head, a value with shell-live characters fails the launch instead of +arriving verbatim. Whether the device shell expands anything before the grammar rejects +the word is not determinable from the captured output. Finding the reshaping layer (the +`hdc` argv join, or the device shell) needs one instrumented probe, and the transport +claim in this PR does not hold until that lands. + +## (d) empty entry: typed refusal before any device call + +```sh +$ agent-device open --platform harmonyos --serial --activity EntryAbility \ + --launch-args "" +Error (INVALID_ARGS): hdc drops an empty element instead of carrying it, so the device +command would lose an operand. May have reached the device. Next: Run snapshot to check +the screen before you retry. Pass a value the transport can carry, or use a device action +that needs no operand. +[exit=1] +``` + +## (e) lone `--ps` word: `aa` refuses the operand grammar + +```sh +$ agent-device open --platform harmonyos --serial --activity EntryAbility \ + --launch-args --ps +Error (COMMAND_FAILED): Failed to start +[exit=1] +``` + +A single `--ps` leaves `aa` without a value operand, and the CLI reports the start +failure as `COMMAND_FAILED`. + +## Receipt is not observable at default levels, stated plainly + +- `aa dump -l` and `aa dump -a` print no parameter lines for the mission. +- After a cleared hilog ring, a launch with `--ps evidence_key_4287 evidence_value_4287` + leaves zero grep hits in `hilog -x`. + +This run proves an accepted dispatch with the forwarded argv and a clean foreground +launch. It does not prove in-app receipt. Proving receipt needs an instrumented build; +this session drove a user-built app and could not add one. + +## Guard + +`assertOpenDeviceSupport` refuses `--launch-args` on Linux +(`packages/contracts/src/application-lifecycle-interaction.ts`). macOS rejects the flag in +the Apple launch path. + +## Cleanup + +`close ` ran after the last case and answered `Closed: default`. diff --git a/packages/command-registry/src/flag-definitions-target.ts b/packages/command-registry/src/flag-definitions-target.ts index f9995de54a..e1f2711bc3 100644 --- a/packages/command-registry/src/flag-definitions-target.ts +++ b/packages/command-registry/src/flag-definitions-target.ts @@ -447,7 +447,7 @@ export const TARGET_FLAG_DEFINITIONS: readonly FlagDefinition[] = [ multiple: true, usageLabel: '--launch-args ', usageDescription: - 'open: repeatable launch argument forwarded verbatim to the platform launch command (iOS app process args; Android adb shell am start args). Linux and macOS reject the flag.', + 'open: repeatable launch argument forwarded verbatim to the platform launch command (iOS app process args; Android adb shell am start args; HarmonyOS aa start args). Linux and macOS reject the flag.', projectConfig: true, recorded: false, }, diff --git a/packages/platform-harmonyos/src/__tests__/app-lifecycle.test.ts b/packages/platform-harmonyos/src/__tests__/app-lifecycle.test.ts index d6b67c2064..10ade1f151 100644 --- a/packages/platform-harmonyos/src/__tests__/app-lifecycle.test.ts +++ b/packages/platform-harmonyos/src/__tests__/app-lifecycle.test.ts @@ -111,6 +111,105 @@ test('HarmonyOS lifecycle commands use HDC bundle and ability primitives', async assert.deepEqual(invalidateHarmonyGestureViewport.mock.calls, [[DEVICE], [DEVICE]]); }); +test('openHarmonyApp appends launch args verbatim after the aa start target words', async () => { + mockRunCmd.mockResolvedValueOnce({ + exitCode: 0, + stdout: 'start ability successfully', + stderr: '', + }); + + await openHarmonyApp(DEVICE, 'com.example.application', { + activity: 'EntryAbility', + launchArgs: ['--ps', 'configKey', 'debug', '--pi', 'retryCount', '3'], + }); + + assert.deepEqual(mockRunCmd.mock.calls[0]?.slice(0, 2), [ + 'hdc', + [ + '-t', + 'harmony-1', + 'shell', + 'aa', + 'start', + '-a', + 'EntryAbility', + '-b', + 'com.example.application', + '--ps', + 'configKey', + 'debug', + '--pi', + 'retryCount', + '3', + ], + ]); +}); + +test('openHarmonyApp forwards no extra aa start words when launch args are absent', async () => { + mockRunCmd.mockResolvedValueOnce({ + exitCode: 0, + stdout: 'start ability successfully', + stderr: '', + }); + + await openHarmonyApp(DEVICE, 'com.example.application', { activity: 'EntryAbility' }); + + assert.deepEqual(mockRunCmd.mock.calls[0]?.slice(0, 2), [ + 'hdc', + [ + '-t', + 'harmony-1', + 'shell', + 'aa', + 'start', + '-a', + 'EntryAbility', + '-b', + 'com.example.application', + ], + ]); +}); + +test('openHarmonyApp keeps the module flag ahead of launch args on the bm dump route', async () => { + mockRunCmd + .mockResolvedValueOnce({ + exitCode: 0, + stdout: `com.example.application:\n${JSON.stringify({ + hapModuleInfos: [{ moduleName: 'entry', mainElementName: 'EntryAbility' }], + })}`, + stderr: '', + }) + .mockResolvedValueOnce({ exitCode: 0, stdout: 'start ability successfully', stderr: '' }); + + await openHarmonyApp(DEVICE, 'com.example.application', { + launchArgs: ['--ps', 'configKey', 'debug'], + }); + + assert.deepEqual(mockRunCmd.mock.calls[0]?.slice(0, 2), [ + 'hdc', + ['-t', 'harmony-1', 'shell', 'bm', 'dump', '-n', 'com.example.application'], + ]); + assert.deepEqual(mockRunCmd.mock.calls[1]?.slice(0, 2), [ + 'hdc', + [ + '-t', + 'harmony-1', + 'shell', + 'aa', + 'start', + '-a', + 'EntryAbility', + '-b', + 'com.example.application', + '-m', + 'entry', + '--ps', + 'configKey', + 'debug', + ], + ]); +}); + test('openHarmonyApp refuses an ability name outside the module grammar before any hdc call', async () => { for (const activity of ['Entry$(id)', 'Entry;reboot', 'Entry Ability', '1Entry', 'Entry"x', '']) { await assert.rejects( diff --git a/packages/platform-harmonyos/src/app-lifecycle.ts b/packages/platform-harmonyos/src/app-lifecycle.ts index a5d68f6c3d..2fc2a8fbad 100644 --- a/packages/platform-harmonyos/src/app-lifecycle.ts +++ b/packages/platform-harmonyos/src/app-lifecycle.ts @@ -186,10 +186,11 @@ function requireHarmonyAbilityName(ability: string): void { }); } +/** Launches a bundle's ability; each `launchArgs` entry lands as one quoted `aa start` argument. */ export async function openHarmonyApp( device: DeviceInfo, bundleId: string, - options?: { activity?: string; signal?: AbortSignal }, + options?: { activity?: string; launchArgs?: string[]; signal?: AbortSignal }, ): Promise { if (options?.activity !== undefined) requireHarmonyAbilityName(options.activity); const launchTarget = options?.activity @@ -213,6 +214,7 @@ export async function openHarmonyApp( } const words: ShellWord[] = ['aa', 'start', '-a', launchTarget.ability, '-b', bundleId]; if (launchTarget.module) words.push('-m', launchTarget.module); + words.push(...(options?.launchArgs ?? [])); const result = await runHarmonyShell(device, words, { signal: options?.signal }); if (!result.stdout.includes('start ability successfully')) { throw new AppError('COMMAND_FAILED', `Failed to start ${bundleId}`, { diff --git a/packages/platform-harmonyos/src/interactor.test.ts b/packages/platform-harmonyos/src/interactor.test.ts index 09a21e84ec..35391948a5 100644 --- a/packages/platform-harmonyos/src/interactor.test.ts +++ b/packages/platform-harmonyos/src/interactor.test.ts @@ -1,7 +1,8 @@ import { expect, test, vi } from 'vitest'; import type { DeviceInfo } from '@agent-device/kernel/device'; -const { pressHarmonyKeyboardKey, snapshotHarmony } = vi.hoisted(() => ({ +const { openHarmonyApp, pressHarmonyKeyboardKey, snapshotHarmony } = vi.hoisted(() => ({ + openHarmonyApp: vi.fn(async () => undefined), pressHarmonyKeyboardKey: vi.fn(async () => undefined), snapshotHarmony: vi.fn(async () => ({ nodes: [{ index: 0, type: 'Button', label: 'Continue' }], @@ -17,7 +18,7 @@ vi.mock('./index.ts', () => ({ fillHarmony: vi.fn(), homeHarmony: vi.fn(), longPressHarmony: vi.fn(), - openHarmonyApp: vi.fn(), + openHarmonyApp, performHarmonyGesture: vi.fn(), pressHarmony: vi.fn(), pressHarmonyKeyboardKey, @@ -56,3 +57,26 @@ test('harmonyos keyboard dismiss invalidates gesture viewport through the Back r expect(pressHarmonyKeyboardKey).toHaveBeenCalledWith(device, 'Back'); }); + +test('harmonyos open forwards launch args with the activity to the app launcher', async () => { + await createHarmonyInteractor(device).open('com.example.application', { + activity: 'EntryAbility', + launchArgs: ['--ps', 'configKey', 'debug'], + }); + + expect(openHarmonyApp).toHaveBeenCalledWith(device, 'com.example.application', { + activity: 'EntryAbility', + launchArgs: ['--ps', 'configKey', 'debug'], + }); +}); + +test('harmonyos open without launch args forwards none to the app launcher', async () => { + await createHarmonyInteractor(device).open('com.example.application', { + activity: 'EntryAbility', + }); + + expect(openHarmonyApp).toHaveBeenCalledWith(device, 'com.example.application', { + activity: 'EntryAbility', + launchArgs: undefined, + }); +}); diff --git a/packages/platform-harmonyos/src/interactor.ts b/packages/platform-harmonyos/src/interactor.ts index bc545a3a1f..9f08df3b69 100644 --- a/packages/platform-harmonyos/src/interactor.ts +++ b/packages/platform-harmonyos/src/interactor.ts @@ -29,7 +29,8 @@ export function createHarmonyInteractor(device: DeviceInfo, _runner?: RunnerCont throw new AppError('UNSUPPORTED_OPERATION', `${name} is not supported on HarmonyOS`); }; return { - open: (app, options) => openHarmonyApp(device, app, { activity: options?.activity }), + open: (app, options) => + openHarmonyApp(device, app, { activity: options?.activity, launchArgs: options?.launchArgs }), openDevice: () => homeHarmony(device), close: (app) => closeHarmonyApp(device, app), tap: (x, y) => pressHarmony(device, x, y), diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md index b976c831e5..9754df9e6f 100644 --- a/website/docs/docs/commands.md +++ b/website/docs/docs/commands.md @@ -193,7 +193,7 @@ Aliases: `launch`, `relaunch`. | `--no-test-ime` | open/test/replay: keep the real Android keyboard even on emulators (opt out of the headless test IME; on test/replay it applies to the sessions the flow opens) | | `--activity ` | Android launch activity (package/Class, .Class, or Class) or HarmonyOS ability name; not for URL opens | | `--launch-console ` | open: capture the initial local or Limrun iOS simulator launch console window to a file | -| `--launch-args ` | open: repeatable launch argument forwarded verbatim to the platform launch command (iOS app process args; Android adb shell am start args). Linux and macOS reject the flag. | +| `--launch-args ` | open: repeatable launch argument forwarded verbatim to the platform launch command (iOS app process args; Android adb shell am start args; HarmonyOS aa start args). Linux and macOS reject the flag. | | `--no-post-gesture-stabilization` | Scroll, swipe, gesture swipe, open: skip the movement check and the stabilization wait that follow a gesture, and on a local iOS simulator the first-screen wait after an app launch; use it only when your own polling verifies the screen | | `--save-script [path]` | Arm evidence capture on open, publish the armed recording on close; close --save-script alone (without an armed open) is rejected — start with open --save-script, or use session save-script mid-session. Optional custom output path. On Windows, absolute paths need a drive letter or ordinary UNC share. | | `--relaunch` | open: terminate app process before launching it | @@ -559,6 +559,7 @@ agent-device capabilities --session checkout --json HarmonyOS support uses HDC and ArkUI `uitest`. On API 24 devices it supports lifecycle and HAP deployment, ArkUI snapshot/screenshot and selector reads, one-pointer touch and text actions, keyboard `enter`/`dismiss`, app logs, foreground app state, process RSS samples, and `settings clear-app-state`. Run `agent-device capabilities --platform harmonyos` for the command list of a selected device. - Gestures use one pointer. Multi-touch gestures and `gesture drag` return `UNSUPPORTED_OPERATION`. +- `open --launch-args` appends each argument to the `aa start` command. Pass the `aa start` parameter pairs you need, such as `--launch-args --ps --launch-args configKey --launch-args debug` for a string extra. - Physical devices support whole-screen recording with `record start --scope device` or `--scope system`, without `--fps`, `--quality`, or `--hide-touches`. Emulator recording is refused. - Not available: orientation, clipboard, alerts, network/audio capture, push and app-event delivery, React Native helpers, and trace capture. `settings` supports only `clear-app-state`. `perf memory sample` reports process RSS only.