Skip to content

Commit 5e16f81

Browse files
committed
docs(capture): clarify alert exclusion and refusal remedy
1 parent bb69e6a commit 5e16f81

4 files changed

Lines changed: 4 additions & 4 deletions

File tree

‎packages/platform-apple/src/os/macos/helper.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -282,7 +282,7 @@ for (const reason of ['front-window-not-shareable', 'front-window-capture-exclud
282282
assert.equal(error.details?.reason, reason);
283283
assert.equal(error.details?.frontWindowId, '4242');
284284
if (reason === 'front-window-capture-excluded') {
285-
assert.match(String(error.details?.hint), /Use a window that permits capture/);
285+
assert.match(String(error.details?.hint), /Run `snapshot` to read the window/);
286286
assert.match(String(error.details?.hint), /retrying the excluded window will not help/);
287287
assert.doesNotMatch(String(error.details?.hint), /retry after/);
288288
} else if (reason === 'front-window-not-shareable') {

‎packages/platform-apple/src/os/macos/helper.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -158,7 +158,7 @@ const MACOS_SCREENSHOT_REFUSAL_HINTS: Record<MacOsScreenshotRefusalReason, strin
158158
'front-window-not-shareable':
159159
'The front window is unavailable to screen capture. If it is opening or closing, retry after it settles.',
160160
'front-window-capture-excluded':
161-
'The app excludes the front window from screen capture. Use a window that permits capture; retrying the excluded window will not help.',
161+
"The app excludes the front window from screen capture. Run `snapshot` to read the window's UI tree; retrying the excluded window will not help.",
162162
};
163163
export const MACOS_DELIVERY_MECHANISMS = [
164164
'ax-press',

‎src/commands/capture/screenshot.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ export const screenshotCommandFacet = defineCommandFacet({
7474
text: {
7575
summary: 'Capture a screenshot',
7676
cliDetail:
77-
"Web defaults to the viewport; use --fullscreen, --full, or -f for the entire page. iOS simulators default to 1x logical-point output; use --pixel-density to request a different screenshot density. macOS app sessions default to the app window; use --fullscreen for full desktop, --scale to downscale, --crop-on <selector> to crop the capture to the frame the selector resolves on the same screen (currently iOS simulators and Android emulators), --overlay-refs to annotate current refs, --normalize-status-bar for deterministic iOS simulator chrome, or --no-stabilize for low-latency Android capture loops. With the native macOS backend, the front window is the app's frontmost visible, nonempty normal-level window on the current Space; floating palettes are skipped, and a sheet is captured as its own window. On macOS, any --surface other than app (desktop, menubar, frontmost-app) always captures the main display and refuses an explicit --fullscreen. On single-display iOS simulators and Android devices, the result reports displayRotation, the rotation the display rendered the capture in, when the device returns a reading in time; otherwise the field is absent.",
77+
"Web defaults to the viewport; use --fullscreen, --full, or -f for the entire page. iOS simulators default to 1x logical-point output; use --pixel-density to request a different screenshot density. macOS app sessions default to the app window; use --fullscreen for full desktop, --scale to downscale, --crop-on <selector> to crop the capture to the frame the selector resolves on the same screen (currently iOS simulators and Android emulators), --overlay-refs to annotate current refs, --normalize-status-bar for deterministic iOS simulator chrome, or --no-stabilize for low-latency Android capture loops. With the native macOS backend, the front window is the app's frontmost visible, nonempty normal-level window on the current Space; floating palettes are skipped, and a sheet is captured as its own window. Only layer-0 windows count as the front window; app-modal alerts at window level 8 are skipped. On macOS, any --surface other than app (desktop, menubar, frontmost-app) always captures the main display and refuses an explicit --fullscreen. On single-display iOS simulators and Android devices, the result reports displayRotation, the rotation the display rendered the capture in, when the device returns a reading in time; otherwise the field is absent.",
7878
},
7979
metadata: screenshotCommandMetadata,
8080
run: (client, input) => client.capture.screenshot(input),

‎website/docs/docs/commands.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -321,7 +321,7 @@ agent-device snapshot -i --platform apple --target desktop
321321
322322
Set `AGENT_DEVICE_MACOS_APP_BACKEND=native` to run macOS app sessions without XCTest. There is no Automation Mode overlay, the app can stay behind other windows, and your pointer stays yours while a drawn pointer shows each action.
323323
324-
- `click`, `press`, and `fill` use accessibility actions on the element at the target point, which must be inside one of the app's on-screen windows, not its menu bar. `type` inserts at the focused control or falls back to key events. `scroll` moves the scroll bar under the front window's center. Chromium-based apps expose their full tree. `screenshot` captures only the app's front window, even when it is covered. The front window is the app's frontmost visible, nonempty normal-level window on the current Space; floating palettes are skipped, and a sheet is captured as its own window. If that window cannot be captured, `screenshot` fails; it never captures another window.
324+
- `click`, `press`, and `fill` use accessibility actions on the element at the target point, which must be inside one of the app's on-screen windows, not its menu bar. `type` inserts at the focused control or falls back to key events. `scroll` moves the scroll bar under the front window's center. Chromium-based apps expose their full tree. `screenshot` captures only the app's front window, even when it is covered. The front window is the app's frontmost visible, nonempty normal-level window on the current Space; floating palettes are skipped, and a sheet is captured as its own window. Only layer-0 windows count as the front window; app-modal alerts at window level 8 are skipped. If that window cannot be captured, `screenshot` fails; it never captures another window.
325325
- `record`, `prepare`, `back`, `longpress`, `--hold-ms`, `--double-tap`, `--button secondary`, gestures, and clicks on an element with no accessibility action fail with `UNSUPPORTED_OPERATION` (`reason: unsupported-device-backend`). Use the default XCTest backend for those.
326326
327327
```bash

0 commit comments

Comments
 (0)