argent-macos-app-interact

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

argent-device-interact

still applies for everything not listed here (

run-sequence

await-ui-element

, secrets).

argent-device-interact

仍适用于此处未列出的所有内容（

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.

需要启用
```
macos-apps
```
flag，该 flag 默认开启。如果某个工具提示它未开启，应告知用户运行该工具指定的命令。不要自行修改此 flag。
一个应用对应一个设备。
```
list-devices
```
仅显示由 argent 启动且仍在运行的应用，也包括其他会话中的应用：除非用户明确指定了某个应用，或该应用由当前会话启动，否则不要选择它。
使用
```
boot-device {macosAppPath: "<abs path>.app"}
```
启动应用，绝不要使用
```
open
```
或 Xcode。仅对 argent 已经启动的应用使用
```
launch-app
```
：如果没有记录路径，它会使用 Spotlight 找到的任意副本。
构建
```
.app
```
时不要启动应用：运行
```
xcodebuild ... build
```
，然后从
```
BUILT_PRODUCTS_DIR
```
获取应用包（
```
xcodebuild -showBuildSettings
```
）。Xcode Run 和
```
react-native run-macos
```
启动的应用副本不包含 argent library，随后执行
```
boot-device
```
会失败并提示
```
already running ... without the argent library
```
。可以使用
```
force: true
```
重试，但如果该副本中可能存在用户尚未保存的工作，应先询问用户。
如果错误信息指出了另一个构建路径，绝不要传入
```
force
```
；应向用户报告该错误。
修改代码后：重新构建，然后执行
```
restart-app
```
。
如果启动结果中的
```
note
```
表示应用未显示窗口，点击和截图操作都需要一个可见窗口。应告知用户，并读取其中指定的日志文件。
如果 hardened-runtime 拒绝执行，应向用户报告。不要签名文件或更改 code signing。
绝不要使用
```
osascript
```
、
```
open
```
或其他系统工具激活或驱动应用。
最后执行
```
stop-all-simulator-servers {devices: ["macos-app-<bundle id>"]}
```
，这会关闭 argent 的连接，但应用会继续运行。

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.

滑动或拖拽：使用
```
gesture-drag
```
。长按：使用
```
gesture-drag
```
，并将起点和终点设为同一位置。滚动：使用
```
gesture-scroll
```
。
缩放或旋转：
```
gesture-pinch
```
和
```
gesture-rotate
```
无法使用；请改用应用自身的控件或快捷键。
右键点击（使用
```
gesture-tap
```
并设置
```
button: "right"
```
）后，返回的 tree 中会列出菜单项；使用普通的
```
gesture-tap
```
点击菜单项即可选择它（菜单关闭期间，菜单项可能会在 tree 中短暂保留）。
```
keyboard
```
的
```
escape
```
可关闭菜单；右键点击后，
```
enter
```
不会选择任何内容，因此应点击菜单项。
不支持 hover：无法访问 tooltip。
```
open-url
```
：URL 会传递给正在运行的应用。自定义 scheme 必须是应用已经声明的；
```
http
```
和
```
https
```
会传递给应用，而不是浏览器；
```
file:
```
URL 会让应用打开相应文档。
SwiftUI
```
DisclosureGroup
```
只能通过其 chevron 展开，该 chevron 位于控件 frame 左端附近：点击中心位置会穿透且不会产生任何效果。沿左端以约 0.008 的步长逐步点击，直到其
```
value
```
发生变化。
任何菜单命令都应使用
```
menu-bar
```
。标记为
```
[disabled]
```
的菜单项当前无法选择：编辑命令（Copy、Select All）需要先点击文本字段；当 alert 打开时，只有该 alert 自身的命令可用，因此应先处理 alert。应用菜单处于打开状态时，
```
choose
```
会失败：先发送
```
keyboard {key: "escape"}
```
，然后再次选择。
打开和保存面板：绝不要点击文件列表，因为
```
describe
```
无法读取它。应使用
```
file-panel
```
，编辑新文档后出现的 Delete 或 Don't Save 提示也应如此处理。

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.

标识符：AppKit accessibility identifier、SwiftUI
```
.accessibilityIdentifier()
```
、Web
```
data-testid
```
（否则为
```
id
```
）、React Native
```
testID
```
（也可设置在普通
```
View
```
或
```
Text
```
上）。
当出现提示
```
The Mac is locked
```
或
```
fallback walk
```
时：点击和输入仍然有效，但部分元素可能缺失（例如已打开的 context menu），并且
```
hidden
```
检查无法通过。如果目标元素缺失，应请用户解锁 Mac。
操作失败或没有效果：最小化的窗口无法接收输入。通过
```
menu-bar
```
在 Window 菜单中选择该窗口以恢复；如果没有对应菜单项，应询问用户。

E2E tests

E2E 测试

Read

references/e2e.md

before recording or writing a test for a Mac app.

为 Mac 应用录制或编写测试前，请阅读

references/e2e.md

。

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

Debug build 会从 Metro 加载 JavaScript：在执行

boot-device

前启动 Metro（参见

argent-react-native-app-workflow

）。

debugger-*

和 React profiler 不接受 Mac app id：请使用

describe

读取屏幕。