Skip to content

Commit 47a15f5

Browse files
committed
docs(action-button): claim only what a simulator can prove
The description told agents that an assigned Shortcut or App Intent fires whatever the app's state. Simulators run neither, so nothing in this PR can show that; the command proves the press was dispatched and that the session app was not brought forward. The help text, `commands.md`, and a CHANGELOG entry now say exactly that, and name a physical iPhone as the only place delivery is verifiable.
1 parent 267c5c0 commit 47a15f5

3 files changed

Lines changed: 13 additions & 2 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,16 @@
22

33
## Unreleased
44

5+
- Added (ios): `action-button` presses the iPhone or iPad Action Button once, and `client.command.actionButton()`
6+
does the same. XCUITest exposes `XCUIDevice.press(.action)` with no hold-duration overload, so there is no
7+
`long-press` and no `--duration-ms`, and the slide surface on the same edge is Camera Control, which this
8+
command does not drive. The press is dispatched without the runner's app-activation preflight and with no
9+
post-action observation, so the session app keeps the state the press found; the runner asks the device for
10+
the button with `hasHardwareButton(.action)` and refuses with `UNSUPPORTED_OPERATION` on a model that has
11+
none, and Android, HarmonyOS, Vega, Linux, web, tvOS, macOS, and visionOS each state their own refusal.
12+
Simulators run no Shortcuts or App Intents, so what a press triggers is verifiable only on a physical
13+
iPhone (#2699).
14+
515
- Fixed (android): `clipboard read` and `clipboard write` stop reporting success on a build whose
616
clipboard service has no shell command. Android 16 (API 36) answers every `adb shell cmd clipboard …`
717
with the framework default `Binder.handleShellCommand` — `No shell command implementation.` on

‎src/commands/system/index.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ const keyboardCommandDescription =
5454
const clipboardCommandDescription =
5555
'Read the current device clipboard text, or replace its contents with the given text. Android runs both through the clipboard service shell command, and a build that implements none (Android 16 does not) refuses with UNSUPPORTED_OPERATION rather than reporting an empty clipboard.';
5656
const actionButtonCommandDescription =
57-
'Press the iPhone Action Button. The press reaches the system exactly as a hardware press does, so a Shortcut or App Intent assigned to the button fires whether the app is foregrounded, backgrounded, or terminated. The app is never activated first and nothing is re-captured after: the press preserves the app state it found.';
57+
'Press the iPhone or iPad Action Button once. The press is dispatched without activating the session app and nothing is re-observed afterwards, so the app keeps the state the press found. What the system does with the press is not observed by this command: Simulators run no Shortcuts or App Intents, so delivery to an assigned Shortcut is verifiable only on a physical iPhone.';
5858
const tvRemoteCommandDescription =
5959
'Press or long-press a TV remote or D-pad button on Android TV, tvOS, or Vega OS. Choose the button and optional hold duration through the input fields. The aliases ok, center, and enter all map to select.';
6060

@@ -319,7 +319,7 @@ const clipboardCommandFacet = defineCommandFacet({
319319
const actionButtonCommandFacet = defineCommandFacet({
320320
name: ACTION_BUTTON_COMMAND_NAME,
321321
text: {
322-
summary: 'Press the iPhone Action Button',
322+
summary: 'Press the iPhone or iPad Action Button',
323323
cliDetail:
324324
'iPhone and iPad only. The runner asks the device for the button and reports unsupported when that model has none.',
325325
},

‎website/docs/docs/commands.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,7 @@ agent-device action-button
8787
- `action-button` is an iPhone and iPad command. Android, web, Linux, HarmonyOS, and Vega refuse it, and so do tvOS, macOS, and visionOS leaves.
8888
- `action-button` asks the device whether it has the button before pressing it. A target whose model has none — an iPhone SE beside an iPhone 15, or most iPad simulators — fails with `UNSUPPORTED_OPERATION` rather than reporting a press that never happened.
8989
- `action-button` does not activate or relaunch the session's app, and it takes no `--settle`: pressing a hardware button is not a navigation, so the app stays where it was.
90+
- `action-button` reports that the press was dispatched, not what the system did with it. Simulators run no Shortcuts and no App Intents, so what a press triggers can only be verified on a physical iPhone; on a Simulator the command proves the press was accepted and that the session app was not brought forward.
9091
- `action-button` is not a cheap command to loop. On an iPhone 17 Pro Simulator the press itself spent about five seconds inside XCUITest, while `home` and `app-switcher` on the same session took under two seconds each.
9192
- On iOS devices, `http(s)://` URLs open in Safari when no app is active. Custom scheme URLs require an active app in the session.
9293
- Commands that need one concrete device refuse to guess: if no `--device`/`--udid`/`--serial` is given and several candidates are equally preferred (for example two booted emulators), the command fails with `AMBIGUOUS_MATCH` and lists them, rather than picking one and returning a successful answer about a device you did not select. Preferences still apply first — virtual over physical, booted over offline — so one booted emulator beside offline ones resolves normally, as does any command running inside an existing session. `devices` lists everything as before.

0 commit comments

Comments
 (0)