argent-macos-app-interact

argent-device-interact

still applies for everything not listed here (

run-sequence

await-ui-element

, secrets).

Contract

Needs the
```
macos-apps
```
flag, which is on by default. When a tool says it is off, tell the user to run the command it names. Do not change the flag yourself.
One app is one device.
```
list-devices
```
shows only apps argent started that still run, also those of other sessions: never pick one unless the user named that app or this session started it.
Start an app with
```
boot-device {macosAppPath: "<abs path>.app"}
```
, never with
```
open
```
or Xcode. Use
```
launch-app
```
only for an app argent already started: with no recorded path it takes whichever copy Spotlight finds.
Build the
```
.app
```
without starting it:
```
xcodebuild ... build
```
, then take the bundle from
```
BUILT_PRODUCTS_DIR
```
(
```
xcodebuild -showBuildSettings
```
). Xcode Run and
```
react-native run-macos
```
start a copy without the argent library:
```
boot-device
```
then fails with
```
already running ... without the argent library
```
. Retry with
```
force: true
```
, but ask the user first when they may have work open in that copy.
Never pass
```
force
```
when the error names another build path; report it.
After a code change: rebuild, then
```
restart-app
```
.
A start result with a
```
note
```
that the app showed no window: taps and screenshots need one. Tell the user, and read the log file it names.
On a hardened-runtime refusal, report it to the user. Do not sign files or change code signing.
Never activate the app or drive it with
```
osascript
```
,
```
open
```
or other system tools.

At the end:

stop-all-simulator-servers {devices: ["macos-app-<bundle id>"]}

closes argent's connection; the app keeps running.

Per-tool notes

Swipe or drag:
```
gesture-drag
```
. Long press:
```
gesture-drag
```
with the same start and end point. Scroll:
```
gesture-scroll
```
.
Zoom or rotate:
```
gesture-pinch
```
and
```
gesture-rotate
```
fail; use the app's own controls or shortcuts.
After a right-click (
```
gesture-tap
```
with
```
button: "right"
```
), the returned tree lists the menu items; a plain
```
gesture-tap
```
on one chooses it (the menu can stay in the tree for a moment while it closes).
```
keyboard
```
```
escape
```
closes the menu;
```
enter
```
chooses nothing after a right-click, so tap the item.
No hover: a tooltip is out of reach.
```
open-url
```
: the URL goes to the running app. A custom scheme must be one the app declares;
```
http
```
and
```
https
```
go to the app, not the browser; a
```
file:
```
URL opens that document in the app.
A SwiftUI
```
DisclosureGroup
```
opens only at its chevron, near the left end of its frame: a tap at the centre passes and does nothing. Tap along the left end in steps of about 0.008 until its
```
value
```
changes.
```
menu-bar
```
for any menu command. An item listed
```
[disabled]
```
cannot be chosen right now: an edit command (Copy, Select All) needs the text field clicked first; while an alert is open only its own commands work, so answer the alert first. When a menu of the app is open,
```
choose
```
fails: send
```
keyboard {key: "escape"}
```
, then choose again.
Open and save panels: never click in the file list, which
```
describe
```
cannot read. Use
```
file-panel
```
, also for the Delete or Don't Save prompt of an edited new document.

Tree

Identifiers: AppKit accessibility identifier, SwiftUI
```
.accessibilityIdentifier()
```
, web
```
data-testid
```
(else
```
id
```
), React Native
```
testID
```
(also on a plain
```
View
```
or
```
Text
```
).
Hint
```
The Mac is locked
```
or
```
fallback walk
```
: clicks and typing still work, elements can be missing (an open context menu among them), and a
```
hidden
```
check cannot pass. Ask the user to unlock when a target is missing.
An action that fails or has no effect: a minimized window takes no input. Restore it by choosing it in the Window menu with
```
menu-bar
```
; without such an item, ask the user.

E2E tests

Read

references/e2e.md

before recording or writing a test for a Mac app.

react-native-macos

A Debug build loads JavaScript from Metro: start Metro before

boot-device

(see

argent-react-native-app-workflow

debugger-*

and the React profiler do not take a Mac app id: read the screen with

describe

argent-macos-app-interact

NPX Install

Tags

SKILL.md Content

Contract

Per-tool notes

Tree

E2E tests

react-native-macos