@allwright.dev/core 0.1.20 → 0.1.22

package/README.md

@@ -51,7 +51,7 @@ Paths passed to `setFiles` and `saveAs` belong to the test process, even when
 the Allwright server is remote. Android apps support the same `fileChooser` and
 `download` hook shape; Android `newPage` hooks are not applicable.
 
-Runnable examples live in [examples/web-basic.ts](./examples/web-basic.ts) and [examples/android-basic.ts](./examples/android-basic.ts).
+Runnable examples live in [examples/web-basic.ts](./examples/web-basic.ts), [examples/android-basic.ts](./examples/android-basic.ts), and [examples/ios-basic.ts](./examples/ios-basic.ts).
 
 Shared config files are stack-agnostic and can live in `allwright.config.yaml` or `allwright.config.json`.
 The shared schema lives at the repo root in `allwright.schema.json`.

package/dist/bootstrap.js

@@ -12,7 +12,7 @@ const ALLWRIGHT_HOME_ENV_VAR = "ALLWRIGHT_HOME";
 const ALLWRIGHT_REPOSITORY_ENV_VAR = "ALLWRIGHT_REPOSITORY";
 const ALLWRIGHT_VERSION_ENV_VAR = "ALLWRIGHT_VERSION";
 const DEFAULT_RELEASE_REPOSITORY = "allwright-dev/allwright";
-const DEFAULT_RELEASE_VERSION = "0.1.20";
+const DEFAULT_RELEASE_VERSION = "0.1.22";
 const STARTUP_TIMEOUT_MS = 20_000;
 const PING_TIMEOUT_MS = 1_000;
 const PROTO_ROOT = fileURLToPath(new URL("../proto/", import.meta.url));

package/dist/desktop.d.ts

@@ -0,0 +1,2 @@
+import type { DesktopSurfaceNamespace } from "./types.js";
+export declare const desktop: DesktopSurfaceNamespace;

package/dist/desktop.js

@@ -0,0 +1,73 @@
+import { createBrowserSessionHandle, getRuntime } from "./runtime.js";
+import { MobileAndroidAppImpl } from "./mobile.js";
+function retryOptions(timeoutMs) {
+    return timeoutMs === undefined ? undefined : { timeoutMs };
+}
+class DesktopMacImpl {
+    sessionId;
+    surfaceSessionId;
+    runtime;
+    stream;
+    queue;
+    #closed = false;
+    #currentApp;
+    constructor(sessionId, surfaceSessionId, runtime, stream, queue, initialAppSessionId) {
+        this.sessionId = sessionId;
+        this.surfaceSessionId = surfaceSessionId;
+        this.runtime = runtime;
+        this.stream = stream;
+        this.queue = queue;
+        this.#currentApp = new MobileAndroidAppImpl(runtime, surfaceSessionId, initialAppSessionId);
+    }
+    app() {
+        return this.#currentApp;
+    }
+    async launch(options) {
+        if (this.#closed)
+            throw new Error(`macOS desktop session ${this.sessionId} is closed`);
+        this.stream.write({
+            launchDesktopApp: {
+                appId: options.appId,
+                terminateRunning: options.terminateRunning ?? false,
+                retryOptions: retryOptions(options.timeoutMs),
+            },
+        });
+        while (true) {
+            const event = await this.queue.next();
+            if (event.desktopAppLaunched?.appSessionId) {
+                this.#currentApp = new MobileAndroidAppImpl(this.runtime, this.surfaceSessionId, event.desktopAppLaunched.appSessionId);
+                return this.#currentApp;
+            }
+            if (event.error?.message)
+                throw new Error(event.error.message);
+            if (event.closed) {
+                this.#closed = true;
+                throw new Error(`macOS desktop session ${this.sessionId} closed while launching app`);
+            }
+        }
+    }
+}
+class DesktopMacSurfaceImpl {
+    async connect(options = {}) {
+        const runtime = await getRuntime();
+        const { stream, queue } = await createBrowserSessionHandle(runtime);
+        stream.write({
+            connectDesktop: {
+                platform: 1,
+                agentEndpoint: options.agentEndpoint,
+                retryOptions: retryOptions(options.timeoutMs),
+            },
+        });
+        while (true) {
+            const event = await queue.next();
+            if (event.desktopConnected?.initialAppSessionId) {
+                return new DesktopMacImpl(event.desktopConnected.desktopSessionId ?? event.sessionId ?? "", event.sessionId ?? "", runtime, stream, queue, event.desktopConnected.initialAppSessionId);
+            }
+            if (event.error?.message)
+                throw new Error(event.error.message);
+        }
+    }
+}
+export const desktop = {
+    mac: new DesktopMacSurfaceImpl(),
+};

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 import { BrowserImpl, BrowserTypeImpl } from "./browser.js";
 import { findConfigFile, loadConfigFile, resolveConfig } from "./config.js";
 import { mobile } from "./mobile.js";
+import { desktop } from "./desktop.js";
 import { PageImpl } from "./page.js";
 import { setServerAddr, shutdown } from "./runtime.js";
 import type { Browser, BrowserKind, BrowserType, LaunchOptions, Page, Dialog, FileChooser, Download, HookType, ResolveConfigOptions, ResolvedAllwrightConfig } from "./types.js";
 export { findConfigFile, loadConfigFile, resolveConfig, setServerAddr, shutdown };
-export type { CapturedOption, BoundingBox, AccessibilitySnapshotOptions, AllwrightConfig, Browser, BrowserInfo, BrowserKind, BrowserType, Hook, HookType, Dialog, FileChooser, Download, ClickResult, CommandOptions, CountResult, ElementResult, FillResult, HighlightOptions, HighlightResult, LaunchOptions, MobileAndroidConnectOptions, MobileAndroidDevice, MobileAndroidLaunchOptions, MobileAndroidLocator, MobileAndroidApp, MobileIosConnectOptions, MobileIosDevice, MobileIosLaunchOptions, MobileIosLocator, MobileIosApp, Locator, LocatorInfo, MobileSurfaceNamespace, NavigateResult, Page, PageInfo, PressOptions, PressResult, ResolveConfigOptions, ResolvedAllwrightConfig, RetryConfig, ScreenshotOptions, ScreenshotResult, TextResult, WaitForSelectorOptions, WaitForSelectorResult, } from "./types.js";
+export type { CapturedOption, BoundingBox, AccessibilitySnapshotOptions, AllwrightConfig, Browser, BrowserInfo, BrowserKind, BrowserType, Hook, HookType, Dialog, FileChooser, Download, ClickResult, CommandOptions, CountResult, ElementResult, FillResult, HighlightOptions, HighlightResult, LaunchOptions, MobileAndroidConnectOptions, MobileAndroidDevice, MobileAndroidLaunchOptions, MobileAndroidLocator, MobileAndroidApp, MobileIosConnectOptions, MobileIosDevice, MobileIosLaunchOptions, MobileIosLocator, MobileIosApp, Locator, LocatorInfo, MobileSurfaceNamespace, DesktopMacApp, DesktopMacConnectOptions, DesktopMacDesktop, DesktopMacLaunchOptions, DesktopMacLocator, DesktopSurfaceNamespace, NavigateResult, Page, PageInfo, PressOptions, PressResult, ResolveConfigOptions, ResolvedAllwrightConfig, RetryConfig, ScreenshotOptions, ScreenshotResult, TextResult, WaitForSelectorOptions, WaitForSelectorResult, } from "./types.js";
 export declare const chromium: BrowserType;
 export declare const firefox: BrowserType;
 export declare const hooks: {
@@ -15,6 +16,7 @@ export declare const hooks: {
     download: HookType<Download>;
 };
 export { mobile };
+export { desktop };
 export type Tab = Page;
 export declare function ping(): Promise<string>;
 export declare function launchChrome(options?: LaunchOptions): Promise<Browser>;

package/dist/index.js

@@ -2,6 +2,7 @@ import { BrowserImpl, BrowserTypeImpl } from "./browser.js";
 import { formatActionError } from "./errors.js";
 import { findConfigFile, loadConfigFile, resolveConfig } from "./config.js";
 import { mobile } from "./mobile.js";
+import { desktop } from "./desktop.js";
 import { PageImpl } from "./page.js";
 import { createBrowserSessionHandle, getRuntime, launchConfiguredBrowser as launchConfiguredBrowserWithResolver, ping as runtimePing, resolveLaunchBrowserArgs, setServerAddr, shutdown, } from "./runtime.js";
 export { findConfigFile, loadConfigFile, resolveConfig, setServerAddr, shutdown };
@@ -14,6 +15,7 @@ export const hooks = {
     download: Object.freeze({ name: "download" }),
 };
 export { mobile };
+export { desktop };
 export async function ping() {
     return runtimePing();
 }

package/dist/mobile.d.ts

@@ -1,2 +1,28 @@
-import type { MobileSurfaceNamespace } from "./types.js";
+import { type RoleOptions, type TextMatcher, type TextOptions } from "./web-locators.js";
+import type { AccessibilitySnapshotOptions, CommandOptions, Hook, HookType, MobileAndroidLocator, MobileAndroidApp, MobileSurfaceNamespace, PressOptions, RuntimeClient, ScreenshotOptions, WaitForSelectorOptions } from "./types.js";
+export declare class MobileAndroidAppImpl implements MobileAndroidApp {
+    #private;
+    readonly sessionId: string;
+    constructor(runtime: RuntimeClient, surfaceSessionId: string, sessionId: string);
+    locator(selector: string): MobileAndroidLocator;
+    getByRole(role: string, options?: RoleOptions): MobileAndroidLocator;
+    getByText(text: TextMatcher, options?: TextOptions): MobileAndroidLocator;
+    getByLabel(text: TextMatcher, options?: TextOptions): MobileAndroidLocator;
+    getByTestId(text: TextMatcher): MobileAndroidLocator;
+    registerHook<T>(type: HookType<T>): Promise<Hook<T>>;
+    setChooserFiles(fileChooserId: string, files: string[], options: CommandOptions): Promise<void>;
+    saveMobileDownload(downloadId: string, path: string, options: CommandOptions): Promise<void>;
+    click(selector: string, options?: CommandOptions): Promise<void>;
+    goto(url: string, options?: CommandOptions): Promise<void>;
+    navigate(url: string, options?: CommandOptions): Promise<void>;
+    count(selector: string, options?: CommandOptions): Promise<number>;
+    focus(selector: string, options?: CommandOptions): Promise<void>;
+    fill(selector: string, value: string, options?: CommandOptions): Promise<void>;
+    press(selector: string, key: string, options?: PressOptions): Promise<void>;
+    textContent(selector: string, options?: CommandOptions): Promise<string | null>;
+    innerText(selector: string, options?: CommandOptions): Promise<string>;
+    waitForSelector(selector: string, options?: WaitForSelectorOptions): Promise<void>;
+    accessibilitySnapshot(options?: AccessibilitySnapshotOptions): Promise<string>;
+    screenshot(options?: ScreenshotOptions): Promise<Uint8Array>;
+}
 export declare const mobile: MobileSurfaceNamespace;

package/dist/mobile.js

@@ -7,7 +7,7 @@ import { semanticSelector } from "./web-locators.js";
 function retryOptions(timeoutMs) {
     return timeoutMs ? { timeoutMs } : undefined;
 }
-class MobileAndroidAppImpl {
+export class MobileAndroidAppImpl {
     sessionId;
     #runtime;
     #surfaceSessionId;

package/dist/types.d.ts

@@ -255,6 +255,27 @@ export interface MobileSurfaceNamespace {
         connect(options?: MobileIosConnectOptions): Promise<MobileIosDevice>;
     };
 }
+export interface DesktopMacConnectOptions {
+    agentEndpoint?: string;
+    timeoutMs?: number;
+}
+export interface DesktopMacLaunchOptions {
+    appId: string;
+    terminateRunning?: boolean;
+    timeoutMs?: number;
+}
+export type DesktopMacApp = MobileAndroidApp;
+export type DesktopMacLocator = MobileAndroidLocator;
+export interface DesktopMacDesktop {
+    readonly sessionId: string;
+    app(): DesktopMacApp;
+    launch(options: DesktopMacLaunchOptions): Promise<DesktopMacApp>;
+}
+export interface DesktopSurfaceNamespace {
+    mac: {
+        connect(options?: DesktopMacConnectOptions): Promise<DesktopMacDesktop>;
+    };
+}
 export interface Locator extends WebLocators {
     inputValue(options?: CommandOptions): Promise<string>;
     selectedOptions(options?: CommandOptions): Promise<CapturedOption[]>;
@@ -417,6 +438,19 @@ export interface SurfaceSessionEvent {
         activityName?: string;
         webviewContext?: string;
     };
+    desktopConnected?: {
+        platform?: number | string;
+        hostName?: string;
+        note?: string;
+        backend?: string;
+        desktopSessionId?: string;
+        initialAppSessionId?: string;
+    };
+    desktopAppLaunched?: {
+        appSessionId?: string;
+        appId?: string;
+        note?: string;
+    };
     contextOpened?: {
         contextSessionId?: string;
         note?: string;
@@ -736,6 +770,24 @@ export interface LaunchAppRequest {
         };
     };
 }
+export interface ConnectDesktopRequest {
+    connectDesktop: {
+        platform: number;
+        agentEndpoint?: string;
+        retryOptions?: {
+            timeoutMs?: number;
+        };
+    };
+}
+export interface LaunchDesktopAppRequest {
+    launchDesktopApp: {
+        appId: string;
+        terminateRunning?: boolean;
+        retryOptions?: {
+            timeoutMs?: number;
+        };
+    };
+}
 export interface SurfacePingRequest {
     ping: {
         message: string;
@@ -892,7 +944,7 @@ export interface CloseContextRequest {
     contextSessionId: string;
     close: Record<string, never>;
 }
-export type SurfaceSessionRequest = LaunchBrowserRequest | LaunchChromeRequest | OpenContextRequest | ConnectMobileRequest | LaunchAppRequest | SurfacePingRequest | CloseSurfaceRequest;
+export type SurfaceSessionRequest = LaunchBrowserRequest | LaunchChromeRequest | OpenContextRequest | ConnectMobileRequest | LaunchAppRequest | ConnectDesktopRequest | LaunchDesktopAppRequest | SurfacePingRequest | CloseSurfaceRequest;
 export type ContextSessionRequest = {
     surfaceSessionId: string;
     contextSessionId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allwright.dev/core",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "High-level TypeScript client for the allwright automation engine.",
   "license": "MIT",
   "type": "module",

package/proto/core/v1/surface.proto

@@ -6,6 +6,7 @@ option java_package = "dev.allwright.engine.v1";
 option java_multiple_files = true;
 
 import "core/v1/common.proto";
+import "surfaces/desktop/v1/desktop.proto";
 import "surfaces/mobile/v1/mobile.proto";
 import "surfaces/web/v1/web.proto";
 
@@ -18,6 +19,8 @@ message SurfaceSessionCommand {
     LaunchBrowserCommand launch_browser = 5;
     ConnectMobileCommand connect_mobile = 6;
     LaunchAppCommand launch_app = 7;
+    ConnectDesktopCommand connect_desktop = 8;
+    LaunchDesktopAppCommand launch_desktop_app = 9;
   }
 }
 
@@ -43,6 +46,8 @@ message SurfaceSessionEvent {
     BrowserLaunchedEvent browser_launched = 7;
     MobileConnectedEvent mobile_connected = 8;
     AppLaunchedEvent app_launched = 9;
+    DesktopConnectedEvent desktop_connected = 10;
+    DesktopAppLaunchedEvent desktop_app_launched = 11;
   }
 }
 

package/proto/surfaces/desktop/v1/desktop.proto

@@ -0,0 +1,40 @@
+syntax = "proto3";
+
+package allwright.engine.v1;
+option go_package = "allwright.dev/gen/allwright/engine/v1;enginev1";
+option java_package = "dev.allwright.engine.v1";
+option java_multiple_files = true;
+
+import "core/v1/common.proto";
+
+enum DesktopPlatform {
+  DESKTOP_PLATFORM_UNSPECIFIED = 0;
+  DESKTOP_PLATFORM_MAC = 1;
+}
+
+message ConnectDesktopCommand {
+  DesktopPlatform platform = 1;
+  optional string agent_endpoint = 2;
+  optional CommandRetryOptions retry_options = 3;
+}
+
+message DesktopConnectedEvent {
+  DesktopPlatform platform = 1;
+  string host_name = 2;
+  string note = 3;
+  string backend = 4;
+  string desktop_session_id = 5;
+  string initial_app_session_id = 6;
+}
+
+message LaunchDesktopAppCommand {
+  string app_id = 1;
+  bool terminate_running = 2;
+  optional CommandRetryOptions retry_options = 3;
+}
+
+message DesktopAppLaunchedEvent {
+  string app_session_id = 1;
+  string app_id = 2;
+  string note = 3;
+}