@allwright.dev/core 0.0.43 → 0.0.45

package/dist/bootstrap.d.ts

@@ -1,2 +1,4 @@
 export declare function ensureRuntimeReady(serverAddr: string): Promise<string>;
 export declare function shutdownManagedServer(): Promise<void>;
+export declare function ensurePluginsInstalled(pluginIds: string[]): Promise<void>;
+export declare function invokePlugin<TResponse>(pluginId: string, request: unknown): Promise<TResponse>;

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.0.43";
+const DEFAULT_RELEASE_VERSION = "0.0.45";
 const STARTUP_TIMEOUT_MS = 20_000;
 const PING_TIMEOUT_MS = 1_000;
 const PROTO_ROOT = fileURLToPath(new URL("../proto/", import.meta.url));
@@ -50,7 +50,7 @@ export async function ensureRuntimeReady(serverAddr) {
         managedServerSpawnError = null;
     }
     const cliPath = await ensureCliAvailable(expectedVersion);
-    ensureWebPlugin(cliPath, expectedVersion);
+    ensurePluginsInstalledWithCli(cliPath, expectedVersion, ["web"]);
     let resolvedServerAddr = serverAddr;
     if (status && status.version !== expectedVersion) {
         resolvedServerAddr = await allocateManagedServerAddr(serverAddr);
@@ -169,29 +169,63 @@ async function installCli() {
     fs.rmSync(assetPath, { force: true });
     return cliPath;
 }
-function ensureWebPlugin(cliPath, expectedVersion) {
-    const pluginPath = path.join(allwrightHome(), "plugins", "web", "lib", webPluginFilename());
-    if (isFile(pluginPath) && installedPluginVersion("web") === expectedVersion) {
-        return;
-    }
-    const result = spawnSync(cliPath, ["plugin", "install", "web", "--version", expectedVersion], {
+export async function ensurePluginsInstalled(pluginIds) {
+    const expectedVersion = expectedRuntimeVersion();
+    const cliPath = await ensureCliAvailable(expectedVersion);
+    ensurePluginsInstalledWithCli(cliPath, expectedVersion, pluginIds);
+}
+export async function invokePlugin(pluginId, request) {
+    const expectedVersion = expectedRuntimeVersion();
+    const cliPath = await ensureCliAvailable(expectedVersion);
+    const requestJson = JSON.stringify(request);
+    const result = spawnSync(cliPath, ["plugin", "invoke", pluginId, "--request-json", requestJson], {
         encoding: "utf8",
         stdio: ["ignore", "pipe", "pipe"],
     });
     if (result.error) {
-        throw new Error(`failed to install allwright web plugin with ${cliPath}: ${result.error.message}`);
+        throw new Error(`failed to invoke allwright ${pluginId} plugin with ${cliPath}: ${result.error.message}`);
     }
-    if (result.status !== 0 || !isFile(pluginPath)) {
+    if (result.status !== 0) {
         const details = [result.stdout, result.stderr]
             .map((value) => value?.trim())
             .filter((value) => !!value)
             .join("\n");
         throw new Error(details
-            ? `allwright attempted to install the \`web\` plugin automatically, but the install did not complete successfully:\n${details}`
-            : "allwright attempted to install the `web` plugin automatically, but the install did not complete successfully");
+            ? `allwright ${pluginId} plugin invocation failed:\n${details}`
+            : `allwright ${pluginId} plugin invocation failed`);
     }
-    if (installedPluginVersion("web") !== expectedVersion) {
-        throw new Error(`allwright attempted to install the \`web\` plugin automatically, but version ${expectedVersion} is still not active`);
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch (error) {
+        throw new Error(`failed to decode allwright ${pluginId} plugin response: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function ensurePluginsInstalledWithCli(cliPath, expectedVersion, pluginIds) {
+    for (const pluginId of new Set(pluginIds.map((value) => value.trim()).filter(Boolean))) {
+        const pluginPath = path.join(allwrightHome(), "plugins", pluginId, "lib", pluginLibraryFilename(pluginId));
+        if (isFile(pluginPath) && installedPluginVersion(pluginId) === expectedVersion) {
+            continue;
+        }
+        const result = spawnSync(cliPath, ["plugin", "install", pluginId, "--version", expectedVersion], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        if (result.error) {
+            throw new Error(`failed to install allwright ${pluginId} plugin with ${cliPath}: ${result.error.message}`);
+        }
+        if (result.status !== 0 || !isFile(pluginPath)) {
+            const details = [result.stdout, result.stderr]
+                .map((value) => value?.trim())
+                .filter((value) => !!value)
+                .join("\n");
+            throw new Error(details
+                ? `allwright attempted to install the \`${pluginId}\` plugin automatically, but the install did not complete successfully:\n${details}`
+                : `allwright attempted to install the \`${pluginId}\` plugin automatically, but the install did not complete successfully`);
+        }
+        if (installedPluginVersion(pluginId) !== expectedVersion) {
+            throw new Error(`allwright attempted to install the \`${pluginId}\` plugin automatically, but version ${expectedVersion} is still not active`);
+        }
     }
 }
 async function resolveReleaseTag() {
@@ -421,14 +455,25 @@ function findExtractedCli(extractRoot) {
     }
     return null;
 }
-function webPluginFilename() {
+function pluginLibraryFilename(pluginId) {
+    const stem = pluginLibraryStem(pluginId);
     if (process.platform === "darwin") {
-        return "liballwright_surface_web.dylib";
+        return `lib${stem}.dylib`;
     }
     if (process.platform === "win32") {
-        return "allwright_surface_web.dll";
+        return `${stem}.dll`;
+    }
+    return `lib${stem}.so`;
+}
+function pluginLibraryStem(pluginId) {
+    switch (pluginId) {
+        case "web":
+            return "allwright_surface_web";
+        case "mobile-android":
+            return "allwright_surface_mobile_android";
+        default:
+            throw new Error(`automatic install is not supported for allwright plugin \`${pluginId}\``);
     }
-    return "liballwright_surface_web.so";
 }
 function autoInstallEnabled() {
     const raw = process.env[ALLWRIGHT_AUTO_INSTALL_ENV_VAR]?.trim().toLowerCase();

package/dist/config.js

@@ -40,9 +40,12 @@ export function resolveConfig(options = {}) {
         throw new Error(`allwright config suite "${suiteName}" was not found in ${configFilePath ?? "the resolved config file"}`);
     }
     const serverAddr = suiteConfig?.server?.addr ?? fileConfig.server?.addr;
-    const browserName = suiteConfig?.browser?.name ?? fileConfig.browser?.name ?? "chromium";
-    const browserBinary = suiteConfig?.browser?.binary ?? fileConfig.browser?.binary;
-    const launchOptions = mergeLaunchOptions(fileConfig.browser?.launchOptions, suiteConfig?.browser?.launchOptions);
+    const web = resolveWebSurface(fileConfig.web, suiteConfig?.web);
+    const mobile = resolveMobileSurface(fileConfig.mobile, suiteConfig?.mobile);
+    const desktop = resolveDesktopSurface(fileConfig.desktop, suiteConfig?.desktop);
+    const browserName = web?.browserName ?? defaultBrowserNameForResolvedSurfaces(mobile, desktop);
+    const browserBinary = web?.browserBinary;
+    const launchOptions = web?.launchOptions ?? {};
     const expect = {
         ...(fileConfig.expect ?? {}),
         ...(suiteConfig?.expect ?? {}),
@@ -55,6 +58,9 @@ export function resolveConfig(options = {}) {
         browserBinary,
         launchOptions: browserBinary ? { ...launchOptions, browserBinary } : launchOptions,
         expect,
+        web,
+        mobile,
+        desktop,
     };
 }
 function mergeLaunchOptions(base, override) {
@@ -71,11 +77,74 @@ function validateConfigShape(value, source) {
     if (config.schemaVersion !== undefined && config.schemaVersion !== 1) {
         throw new Error(`allwright config ${source} has unsupported schemaVersion ${String(config.schemaVersion)}; expected 1`);
     }
-    const browserName = config.browser?.name;
+    const browserName = ((config.web?.browser)?.name);
     if (browserName !== undefined && browserName !== "chromium" && browserName !== "firefox") {
         throw new Error(`allwright config ${source} has unsupported browser.name ${String(browserName)}; use "chromium" or "firefox"`);
     }
 }
+function resolveMobileSurface(base, override) {
+    return {
+        android: resolveMobileTarget(base?.android, override?.android),
+        ios: resolveMobileTarget(base?.ios, override?.ios),
+    };
+}
+function resolveDesktopSurface(base, override) {
+    return {
+        mac: resolveDesktopTarget(base?.mac, override?.mac),
+        windows: resolveDesktopTarget(base?.windows, override?.windows),
+        linux: resolveDesktopTarget(base?.linux, override?.linux),
+    };
+}
+function resolveWebSurface(base, override) {
+    const browser = override?.browser ?? base?.browser;
+    const browserName = override?.browser?.name ?? base?.browser?.name;
+    const browserBinary = override?.browser?.binary ?? base?.browser?.binary;
+    const launchOptions = mergeLaunchOptions(base?.browser?.launchOptions, override?.browser?.launchOptions);
+    if (!browser && !browserName && !browserBinary && !Object.keys(launchOptions).length) {
+        return undefined;
+    }
+    return {
+        browserName,
+        browserBinary,
+        launchOptions: browserBinary ? { ...launchOptions, browserBinary } : launchOptions,
+    };
+}
+function resolveMobileTarget(base, override) {
+    const app = mergeAppConfig(base?.app, override?.app);
+    const resolved = {
+        device: override?.device ?? base?.device,
+        appId: app?.id,
+        appBinary: app?.binary,
+        appActivity: app?.activity,
+    };
+    return hasResolvedValues(resolved) ? resolved : undefined;
+}
+function resolveDesktopTarget(base, override) {
+    const app = mergeAppConfig(base?.app, override?.app);
+    const resolved = {
+        appId: app?.id,
+        appBinary: app?.binary,
+        appActivity: app?.activity,
+    };
+    return hasResolvedValues(resolved) ? resolved : undefined;
+}
+function mergeAppConfig(base, override) {
+    const resolved = {
+        id: override?.id ?? base?.id,
+        binary: override?.binary ?? base?.binary,
+        activity: override?.activity ?? base?.activity,
+    };
+    return hasResolvedValues(resolved) ? resolved : undefined;
+}
+function hasResolvedValues(value) {
+    return Object.values(value).some((entry) => entry !== undefined && entry !== null && entry !== "");
+}
+function defaultBrowserNameForResolvedSurfaces(mobile, desktop) {
+    if (mobile.android || mobile.ios || desktop.mac || desktop.windows || desktop.linux) {
+        return undefined;
+    }
+    return "chromium";
+}
 function parseConfigContents(raw, source) {
     const extension = path.extname(source).toLowerCase();
     if (extension === ".json") {

package/dist/index.d.ts

@@ -1,12 +1,14 @@
 import { BrowserImpl, BrowserTypeImpl } from "./browser.js";
 import { findConfigFile, loadConfigFile, resolveConfig } from "./config.js";
+import { mobile } from "./mobile.js";
 import { PageImpl } from "./page.js";
 import { setServerAddr, shutdown } from "./runtime.js";
 import type { Browser, BrowserKind, BrowserType, LaunchOptions, Page, ResolveConfigOptions, ResolvedAllwrightConfig } from "./types.js";
 export { findConfigFile, loadConfigFile, resolveConfig, setServerAddr, shutdown };
-export type { AllwrightConfig, Browser, BrowserInfo, BrowserKind, BrowserType, ClickResult, CommandOptions, CountResult, ElementResult, FillResult, HighlightOptions, HighlightResult, LaunchOptions, Locator, LocatorInfo, NavigateResult, Page, PageInfo, PressOptions, PressResult, ResolveConfigOptions, ResolvedAllwrightConfig, RetryConfig, TextResult, WaitForSelectorOptions, WaitForSelectorResult, } from "./types.js";
+export type { AllwrightConfig, Browser, BrowserInfo, BrowserKind, BrowserType, ClickResult, CommandOptions, CountResult, ElementResult, FillResult, HighlightOptions, HighlightResult, LaunchOptions, MobileAndroidConnectOptions, MobileAndroidDevice, MobileAndroidLaunchOptions, MobileAndroidPage, Locator, LocatorInfo, MobileSurfaceNamespace, NavigateResult, Page, PageInfo, PressOptions, PressResult, ResolveConfigOptions, ResolvedAllwrightConfig, RetryConfig, TextResult, WaitForSelectorOptions, WaitForSelectorResult, } from "./types.js";
 export declare const chromium: BrowserType;
 export declare const firefox: BrowserType;
+export { mobile };
 export type Tab = Page;
 export declare function ping(): Promise<string>;
 export declare function launchChrome(options?: LaunchOptions): Promise<Browser>;

package/dist/index.js

@@ -1,11 +1,13 @@
 import { BrowserImpl, BrowserTypeImpl } from "./browser.js";
 import { formatActionError } from "./errors.js";
 import { findConfigFile, loadConfigFile, resolveConfig } from "./config.js";
+import { mobile } from "./mobile.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 };
 export const chromium = new BrowserTypeImpl("chromium");
 export const firefox = new BrowserTypeImpl("firefox");
+export { mobile };
 export async function ping() {
     return runtimePing();
 }

package/dist/mobile.d.ts

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

package/dist/mobile.js

@@ -0,0 +1,103 @@
+import { ensurePluginsInstalled, invokePlugin } from "./bootstrap.js";
+function timeoutMsOf(options) {
+    return options?.timeoutMs;
+}
+async function invokeAndroidExpected(commandName, request) {
+    const envelope = await invokePlugin("mobile-android", request);
+    if (!envelope.ok) {
+        throw new Error(envelope.error ?? `mobile-android plugin ${commandName} failed`);
+    }
+    if (envelope.result === undefined) {
+        throw new Error(`mobile-android plugin ${commandName} returned no result`);
+    }
+    return envelope.result;
+}
+class MobileAndroidPageImpl {
+    browserSession;
+    pageSession;
+    constructor(browserSession, pageSession) {
+        this.browserSession = browserSession;
+        this.pageSession = pageSession;
+    }
+    get sessionId() {
+        return this.pageSession.page_id;
+    }
+    async click(selector, options = {}) {
+        const result = await invokeAndroidExpected("click", {
+            command: "click_element",
+            browser_session: this.browserSession,
+            page_session: this.pageSession,
+            selector,
+            timeout_ms: timeoutMsOf(options),
+        });
+        return {
+            selector: result.selector,
+            note: result.note,
+            bidiSessionId: result.session_id,
+        };
+    }
+    async fill(selector, value, options = {}) {
+        const result = await invokeAndroidExpected("fill", {
+            command: "fill_element",
+            browser_session: this.browserSession,
+            page_session: this.pageSession,
+            selector,
+            value,
+            timeout_ms: timeoutMsOf(options),
+        });
+        return {
+            selector: result.selector,
+            value: result.value,
+            note: result.note,
+        };
+    }
+}
+class MobileAndroidDeviceImpl {
+    connectInfoRaw;
+    #initialPage;
+    constructor(connectInfoRaw) {
+        this.connectInfoRaw = connectInfoRaw;
+        this.#initialPage = new MobileAndroidPageImpl(this.connectInfoRaw.browser_session, this.connectInfoRaw.initial_page.page_session);
+    }
+    get sessionId() {
+        return this.connectInfoRaw.browser_session.automation.session_id;
+    }
+    page() {
+        return this.#initialPage;
+    }
+    initialPage() {
+        return this.#initialPage;
+    }
+    async launch(options = {}) {
+        const page = await invokeAndroidExpected("launch", {
+            command: "launch_app",
+            browser_session: this.connectInfoRaw.browser_session,
+            options: {
+                apk_path: options.apkPath,
+                app_id: options.appId,
+                launch_activity: options.launchActivity,
+                stop_before_launch: options.stopBeforeLaunch ?? false,
+                timeout_ms: timeoutMsOf(options),
+            },
+        });
+        this.#initialPage = new MobileAndroidPageImpl(this.connectInfoRaw.browser_session, page.page_session);
+        return this.#initialPage;
+    }
+}
+class MobileAndroidSurfaceImpl {
+    async connect(options = {}) {
+        await ensurePluginsInstalled(["mobile-android"]);
+        const connectInfo = await invokeAndroidExpected("connect", {
+            command: "connect",
+            platform: "android",
+            device: options.device,
+            adb_endpoint: options.adbEndpoint,
+            preserve_app_state: options.preserveAppState ?? false,
+            timeout_ms: timeoutMsOf(options),
+        });
+        return new MobileAndroidDeviceImpl(connectInfo);
+    }
+}
+export const mobile = {
+    android: new MobileAndroidSurfaceImpl(),
+};

package/dist/runtime.js

@@ -57,6 +57,9 @@ export async function createBrowserSessionHandle(runtime) {
     return { stream, queue };
 }
 export async function launchConfiguredBrowser(config, launchBrowserKind) {
+    if (!config.browserName) {
+        throw new Error("resolved config does not define web.browser.name and includes only non-web surfaces");
+    }
     return launchBrowserKind(config.browserName, {
         ...config.launchOptions,
         browserBinary: config.browserBinary ?? config.launchOptions.browserBinary,

package/dist/types.d.ts

@@ -114,6 +114,35 @@ export interface Page extends PageInfo {
     ping(message?: string): Promise<string>;
     pageInfo(): PageInfo;
 }
+export interface MobileAndroidConnectOptions {
+    device?: string;
+    adbEndpoint?: string;
+    preserveAppState?: boolean;
+    timeoutMs?: number;
+}
+export interface MobileAndroidLaunchOptions {
+    apkPath?: string;
+    appId?: string;
+    launchActivity?: string;
+    stopBeforeLaunch?: boolean;
+    timeoutMs?: number;
+}
+export interface MobileAndroidPage {
+    readonly sessionId: string;
+    click(selector: string, options?: CommandOptions): Promise<ClickResult>;
+    fill(selector: string, value: string, options?: CommandOptions): Promise<FillResult>;
+}
+export interface MobileAndroidDevice {
+    readonly sessionId: string;
+    page(): MobileAndroidPage;
+    initialPage(): MobileAndroidPage;
+    launch(options?: MobileAndroidLaunchOptions): Promise<MobileAndroidPage>;
+}
+export interface MobileSurfaceNamespace {
+    android: {
+        connect(options?: MobileAndroidConnectOptions): Promise<MobileAndroidDevice>;
+    };
+}
 export interface Locator {
     readonly page: Page;
     readonly selector: string;
@@ -134,11 +163,9 @@ export interface AllwrightConfig {
     server?: {
         addr?: string;
     };
-    browser?: {
-        name?: BrowserKind;
-        binary?: string;
-        launchOptions?: LaunchOptions;
-    };
+    web?: WebConfig;
+    mobile?: MobileConfig;
+    desktop?: DesktopConfig;
     expect?: RetryConfig;
     suites?: Record<string, AllwrightSuiteConfig>;
 }
@@ -146,25 +173,77 @@ export interface AllwrightSuiteConfig {
     server?: {
         addr?: string;
     };
+    web?: WebConfig;
+    mobile?: MobileConfig;
+    desktop?: DesktopConfig;
+    expect?: RetryConfig;
+}
+export interface WebConfig {
     browser?: {
         name?: BrowserKind;
         binary?: string;
         launchOptions?: LaunchOptions;
     };
-    expect?: RetryConfig;
+}
+export interface SurfaceAppConfig {
+    id?: string;
+    binary?: string;
+    activity?: string;
+}
+export interface SurfaceMobileTargetConfig {
+    device?: string;
+    app?: SurfaceAppConfig;
+}
+export interface SurfaceDesktopTargetConfig {
+    app?: SurfaceAppConfig;
+}
+export interface MobileConfig {
+    android?: SurfaceMobileTargetConfig;
+    ios?: SurfaceMobileTargetConfig;
+}
+export interface DesktopConfig {
+    mac?: SurfaceDesktopTargetConfig;
+    windows?: SurfaceDesktopTargetConfig;
+    linux?: SurfaceDesktopTargetConfig;
 }
 export interface RetryConfig {
     timeoutMs?: number;
     intervalMs?: number;
 }
+export interface ResolvedWebSurfaceConfig {
+    browserName?: BrowserKind;
+    browserBinary?: string;
+    launchOptions: LaunchOptions;
+}
+export interface ResolvedMobileTargetConfig {
+    device?: string;
+    appId?: string;
+    appBinary?: string;
+    appActivity?: string;
+}
+export interface ResolvedDesktopTargetConfig {
+    appId?: string;
+    appBinary?: string;
+    appActivity?: string;
+}
 export interface ResolvedAllwrightConfig {
     configFilePath: string | null;
     suiteName: string | null;
     serverAddr?: string;
-    browserName: BrowserKind;
+    browserName?: BrowserKind;
     browserBinary?: string;
     launchOptions: LaunchOptions;
     expect: RetryConfig;
+    web?: ResolvedWebSurfaceConfig;
+    mobile: {
+        android?: ResolvedMobileTargetConfig;
+        ios?: ResolvedMobileTargetConfig;
+    };
+    desktop: {
+        mac?: ResolvedDesktopTargetConfig;
+        windows?: ResolvedDesktopTargetConfig;
+        linux?: ResolvedDesktopTargetConfig;
+    };
 }
 export interface ResolveConfigOptions {
     cwd?: string;

package/package.json

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