@allwright.dev/core 0.1.22 → 0.1.24

package/README.md

@@ -51,7 +51,18 @@ 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), [examples/android-basic.ts](./examples/android-basic.ts), and [examples/ios-basic.ts](./examples/ios-basic.ts).
+Runnable examples cover every implemented surface:
+[Web](./examples/web-basic.ts), [Android](./examples/android-basic.ts),
+[iOS](./examples/ios-basic.ts), [macOS](./examples/macos-basic.ts), and
+[Windows](./examples/windows-basic.ts). The desktop examples default to
+Calculator on macOS and Notepad on Windows and accept `ALLWRIGHT_MAC_APP_ID`
+or `ALLWRIGHT_WINDOWS_APP_ID`.
+
+Android, iOS, macOS, and Windows applications implement the shared `NativeApp` and
+`NativeAppLocator` interfaces. Platform-specific type names such as
+`MobileAndroidApp`, `MobileIosLocator`, `DesktopMacLocator`, and
+`DesktopWindowsLocator` remain exported
+as aliases for compatibility and platform-oriented annotations.
 
 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.22";
+const DEFAULT_RELEASE_VERSION = "0.1.24";
 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.js

@@ -1,5 +1,5 @@
 import { createBrowserSessionHandle, getRuntime } from "./runtime.js";
-import { MobileAndroidAppImpl } from "./mobile.js";
+import { NativeAppImpl } from "./mobile.js";
 function retryOptions(timeoutMs) {
     return timeoutMs === undefined ? undefined : { timeoutMs };
 }
@@ -9,22 +9,24 @@ class DesktopMacImpl {
     runtime;
     stream;
     queue;
+    platformLabel;
     #closed = false;
     #currentApp;
-    constructor(sessionId, surfaceSessionId, runtime, stream, queue, initialAppSessionId) {
+    constructor(sessionId, surfaceSessionId, runtime, stream, queue, initialAppSessionId, platformLabel = "macOS") {
         this.sessionId = sessionId;
         this.surfaceSessionId = surfaceSessionId;
         this.runtime = runtime;
         this.stream = stream;
         this.queue = queue;
-        this.#currentApp = new MobileAndroidAppImpl(runtime, surfaceSessionId, initialAppSessionId);
+        this.platformLabel = platformLabel;
+        this.#currentApp = new NativeAppImpl(runtime, surfaceSessionId, initialAppSessionId);
     }
     app() {
         return this.#currentApp;
     }
     async launch(options) {
         if (this.#closed)
-            throw new Error(`macOS desktop session ${this.sessionId} is closed`);
+            throw new Error(`${this.platformLabel} desktop session ${this.sessionId} is closed`);
         this.stream.write({
             launchDesktopApp: {
                 appId: options.appId,
@@ -35,14 +37,14 @@ class DesktopMacImpl {
         while (true) {
             const event = await this.queue.next();
             if (event.desktopAppLaunched?.appSessionId) {
-                this.#currentApp = new MobileAndroidAppImpl(this.runtime, this.surfaceSessionId, event.desktopAppLaunched.appSessionId);
+                this.#currentApp = new NativeAppImpl(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`);
+                throw new Error(`${this.platformLabel} desktop session ${this.sessionId} closed while launching app`);
             }
         }
     }
@@ -61,7 +63,28 @@ class DesktopMacSurfaceImpl {
         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);
+                return new DesktopMacImpl(event.desktopConnected.desktopSessionId ?? event.sessionId ?? "", event.sessionId ?? "", runtime, stream, queue, event.desktopConnected.initialAppSessionId, "macOS");
+            }
+            if (event.error?.message)
+                throw new Error(event.error.message);
+        }
+    }
+}
+class DesktopWindowsSurfaceImpl {
+    async connect(options = {}) {
+        const runtime = await getRuntime();
+        const { stream, queue } = await createBrowserSessionHandle(runtime);
+        stream.write({
+            connectDesktop: {
+                platform: 2,
+                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, "Windows");
             }
             if (event.error?.message)
                 throw new Error(event.error.message);
@@ -70,4 +93,5 @@ class DesktopMacSurfaceImpl {
 }
 export const desktop = {
     mac: new DesktopMacSurfaceImpl(),
+    windows: new DesktopWindowsSurfaceImpl(),
 };

package/dist/index.d.ts

@@ -6,7 +6,7 @@ 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, DesktopMacApp, DesktopMacConnectOptions, DesktopMacDesktop, DesktopMacLaunchOptions, DesktopMacLocator, DesktopSurfaceNamespace, 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, NativeApp, NativeAppLocator, MobileAndroidConnectOptions, MobileAndroidDevice, MobileAndroidLaunchOptions, MobileAndroidLocator, MobileAndroidApp, MobileIosConnectOptions, MobileIosDevice, MobileIosLaunchOptions, MobileIosLocator, MobileIosApp, Locator, LocatorInfo, MobileSurfaceNamespace, DesktopMacApp, DesktopMacConnectOptions, DesktopMacDesktop, DesktopMacLaunchOptions, DesktopMacLocator, DesktopWindowsApp, DesktopWindowsConnectOptions, DesktopWindowsDesktop, DesktopWindowsLaunchOptions, DesktopWindowsLocator, 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: {

package/dist/mobile.d.ts

@@ -1,14 +1,14 @@
 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 {
+import type { AccessibilitySnapshotOptions, CommandOptions, Hook, HookType, MobileSurfaceNamespace, NativeApp, NativeAppLocator, PressOptions, RuntimeClient, ScreenshotOptions, WaitForSelectorOptions } from "./types.js";
+export declare class NativeAppImpl implements NativeApp {
     #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;
+    locator(selector: string): NativeAppLocator;
+    getByRole(role: string, options?: RoleOptions): NativeAppLocator;
+    getByText(text: TextMatcher, options?: TextOptions): NativeAppLocator;
+    getByLabel(text: TextMatcher, options?: TextOptions): NativeAppLocator;
+    getByTestId(text: TextMatcher): NativeAppLocator;
     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>;

package/dist/mobile.js

@@ -7,7 +7,7 @@ import { semanticSelector } from "./web-locators.js";
 function retryOptions(timeoutMs) {
     return timeoutMs ? { timeoutMs } : undefined;
 }
-export class MobileAndroidAppImpl {
+export class NativeAppImpl {
     sessionId;
     #runtime;
     #surfaceSessionId;
@@ -18,7 +18,7 @@ export class MobileAndroidAppImpl {
         this.#surfaceSessionId = surfaceSessionId;
     }
     locator(selector) {
-        return new MobileAndroidLocatorImpl(this, normalizeMobileSelectorForTransport(selector));
+        return new NativeAppLocatorImpl(this, normalizeMobileSelectorForTransport(selector));
     }
     getByRole(role, options = {}) {
         return this.locator(semanticSelector({ ...options, kind: "role", role }));
@@ -34,7 +34,7 @@ export class MobileAndroidAppImpl {
     }
     async registerHook(type) {
         if (type.name !== "fileChooser" && type.name !== "download") {
-            throw new Error(`hook type ${type.name} is not supported by Android apps`);
+            throw new Error(`hook type ${type.name} is not supported by native apps`);
         }
         const handle = await this.#getHandle();
         this.#ensureOpen(handle);
@@ -530,7 +530,7 @@ class MobileDownloadImpl {
         await this.page.saveMobileDownload(this.id, path, options);
     }
 }
-class MobileAndroidLocatorImpl {
+class NativeAppLocatorImpl {
     page;
     selector;
     constructor(page, selector) {
@@ -562,7 +562,7 @@ class MobileAndroidLocatorImpl {
         return this.page.waitForSelector(this.selector, options);
     }
     locator(selector) {
-        return new MobileAndroidLocatorImpl(this.page, chainMobileSelectorForTransport(this.selector, selector));
+        return new NativeAppLocatorImpl(this.page, chainMobileSelectorForTransport(this.selector, selector));
     }
     getByRole(role, options = {}) {
         return this.locator(semanticSelector({ ...options, kind: "role", role }));
@@ -591,7 +591,7 @@ class MobileAndroidDeviceImpl {
         this.runtime = runtime;
         this.#stream = stream;
         this.#queue = queue;
-        this.#currentApp = new MobileAndroidAppImpl(runtime, surfaceSessionId, initialAppSessionId);
+        this.#currentApp = new NativeAppImpl(runtime, surfaceSessionId, initialAppSessionId);
     }
     app() {
         return this.#currentApp;
@@ -613,7 +613,7 @@ class MobileAndroidDeviceImpl {
         while (true) {
             const event = await this.#queue.next();
             if (event.appLaunched?.appSessionId) {
-                this.#currentApp = new MobileAndroidAppImpl(this.runtime, this.surfaceSessionId, event.appLaunched.appSessionId);
+                this.#currentApp = new NativeAppImpl(this.runtime, this.surfaceSessionId, event.appLaunched.appSessionId);
                 return this.#currentApp;
             }
             if (event.error?.message) {
@@ -645,7 +645,7 @@ class MobileIosDeviceImpl {
         this.runtime = runtime;
         this.#stream = stream;
         this.#queue = queue;
-        this.#currentApp = new MobileAndroidAppImpl(runtime, surfaceSessionId, initialAppSessionId);
+        this.#currentApp = new NativeAppImpl(runtime, surfaceSessionId, initialAppSessionId);
     }
     app() { return this.#currentApp; }
     initialApp() { return this.#currentApp; }
@@ -663,7 +663,7 @@ class MobileIosDeviceImpl {
         while (true) {
             const event = await this.#queue.next();
             if (event.appLaunched?.appSessionId) {
-                this.#currentApp = new MobileAndroidAppImpl(this.runtime, this.surfaceSessionId, event.appLaunched.appSessionId);
+                this.#currentApp = new NativeAppImpl(this.runtime, this.surfaceSessionId, event.appLaunched.appSessionId);
                 return this.#currentApp;
             }
             if (event.error?.message)

package/dist/types.d.ts

@@ -119,13 +119,13 @@ export interface Dialog {
 }
 export interface FileChooser {
     readonly id: string;
-    readonly page: Page | MobileAndroidApp;
+    readonly page: Page | NativeApp;
     isMultiple(): boolean;
     setFiles(files: string | string[], options?: CommandOptions): Promise<void>;
 }
 export interface Download {
     readonly id: string;
-    readonly page: Page | MobileAndroidApp;
+    readonly page: Page | NativeApp;
     readonly url: string;
     readonly suggestedFilename: string;
     saveAs(path: string, options?: CommandOptions): Promise<void>;
@@ -183,8 +183,8 @@ export interface MobileAndroidLaunchOptions {
     stopBeforeLaunch?: boolean;
     timeoutMs?: number;
 }
-export interface MobileAndroidLocator {
-    readonly page: MobileAndroidApp;
+export interface NativeAppLocator {
+    readonly page: NativeApp;
     readonly selector: string;
     click(options?: CommandOptions): Promise<void>;
     count(options?: CommandOptions): Promise<number>;
@@ -194,22 +194,22 @@ export interface MobileAndroidLocator {
     textContent(options?: CommandOptions): Promise<string | null>;
     innerText(options?: CommandOptions): Promise<string>;
     waitFor(options?: WaitForSelectorOptions): Promise<void>;
-    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;
+    locator(selector: string): NativeAppLocator;
+    getByRole(role: string, options?: RoleOptions): NativeAppLocator;
+    getByText(text: TextMatcher, options?: TextOptions): NativeAppLocator;
+    getByLabel(text: TextMatcher, options?: TextOptions): NativeAppLocator;
+    getByTestId(text: TextMatcher): NativeAppLocator;
 }
-export interface MobileAndroidApp {
+export interface NativeApp {
     accessibilitySnapshot(options?: AccessibilitySnapshotOptions): Promise<string>;
     readonly sessionId: string;
     goto(url: string, options?: CommandOptions): Promise<void>;
     navigate(url: string, options?: CommandOptions): Promise<void>;
-    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;
+    locator(selector: string): NativeAppLocator;
+    getByRole(role: string, options?: RoleOptions): NativeAppLocator;
+    getByText(text: TextMatcher, options?: TextOptions): NativeAppLocator;
+    getByLabel(text: TextMatcher, options?: TextOptions): NativeAppLocator;
+    getByTestId(text: TextMatcher): NativeAppLocator;
     click(selector: string, options?: CommandOptions): Promise<void>;
     count(selector: string, options?: CommandOptions): Promise<number>;
     focus(selector: string, options?: CommandOptions): Promise<void>;
@@ -221,6 +221,8 @@ export interface MobileAndroidApp {
     screenshot(options?: ScreenshotOptions): Promise<Uint8Array>;
     registerHook<T>(type: HookType<T>): Promise<Hook<T>>;
 }
+export type MobileAndroidLocator = NativeAppLocator;
+export type MobileAndroidApp = NativeApp;
 export interface MobileAndroidDevice {
     readonly sessionId: string;
     app(): MobileAndroidApp;
@@ -239,8 +241,8 @@ export interface MobileIosLaunchOptions {
     stopBeforeLaunch?: boolean;
     timeoutMs?: number;
 }
-export type MobileIosLocator = MobileAndroidLocator;
-export type MobileIosApp = MobileAndroidApp;
+export type MobileIosLocator = NativeAppLocator;
+export type MobileIosApp = NativeApp;
 export interface MobileIosDevice {
     readonly sessionId: string;
     app(): MobileIosApp;
@@ -264,17 +266,29 @@ export interface DesktopMacLaunchOptions {
     terminateRunning?: boolean;
     timeoutMs?: number;
 }
-export type DesktopMacApp = MobileAndroidApp;
-export type DesktopMacLocator = MobileAndroidLocator;
+export type DesktopMacApp = NativeApp;
+export type DesktopMacLocator = NativeAppLocator;
 export interface DesktopMacDesktop {
     readonly sessionId: string;
     app(): DesktopMacApp;
     launch(options: DesktopMacLaunchOptions): Promise<DesktopMacApp>;
 }
+export type DesktopWindowsConnectOptions = DesktopMacConnectOptions;
+export type DesktopWindowsLaunchOptions = DesktopMacLaunchOptions;
+export type DesktopWindowsApp = NativeApp;
+export type DesktopWindowsLocator = NativeAppLocator;
+export interface DesktopWindowsDesktop {
+    readonly sessionId: string;
+    app(): DesktopWindowsApp;
+    launch(options: DesktopWindowsLaunchOptions): Promise<DesktopWindowsApp>;
+}
 export interface DesktopSurfaceNamespace {
     mac: {
         connect(options?: DesktopMacConnectOptions): Promise<DesktopMacDesktop>;
     };
+    windows: {
+        connect(options?: DesktopWindowsConnectOptions): Promise<DesktopWindowsDesktop>;
+    };
 }
 export interface Locator extends WebLocators {
     inputValue(options?: CommandOptions): Promise<string>;

package/package.json

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