API ReferenceTypeScriptDesktop
Desktop
Native macOS application automation through the installable desktop-mac XCUITest plugin. Windows and Linux are not available yet.
desktop.mac.connect
Connects to the local macOS desktop and starts the bundled XCUITest runner automatically. Requires macOS 14 or newer, Xcode, and UI automation permission for the process running Xcode.
desktop.mac.connect(options?: DesktopMacConnectOptions): Promise<DesktopMacDesktop>Example
const mac = await desktop.mac.connect();DesktopMacDesktop.launch
Launches an installed macOS application by bundle identifier. The returned app supports native locators, actions, text reads, waits, screenshots, and accessibility snapshots.
launch(options: DesktopMacLaunchOptions): Promise<DesktopMacApp>Example
const app = await mac.launch({ appId: "com.apple.TextEdit" });DesktopMacApp locators and actions
Uses native XCUITest selectors and the Playwright-style role, text, label, and test-id locator subset. App methods include click, fill, focus, press, count, textContent, innerText, waitForSelector, screenshot, and accessibilitySnapshot.
locator(selector: string): DesktopMacLocator
getByRole(role: string, options?: RoleOptions): DesktopMacLocator