@allwright.dev/core 0.1.7 → 0.1.9

package/README.md

@@ -47,6 +47,10 @@ const download = await hook.wait();
 await download.saveAs(`artifacts/${download.suggestedFilename}`);
 ```
 
+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).
 
 Shared config files are stack-agnostic and can live in `allwright.config.yaml` or `allwright.config.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.7";
+const DEFAULT_RELEASE_VERSION = "0.1.9";
 const STARTUP_TIMEOUT_MS = 20_000;
 const PING_TIMEOUT_MS = 1_000;
 const PROTO_ROOT = fileURLToPath(new URL("../proto/", import.meta.url));

package/dist/mobile.js

@@ -1,5 +1,7 @@
 import { createBrowserSessionHandle, createPageHandle, getRuntime } from "./runtime.js";
-import { writeFile } from "node:fs/promises";
+import { open, rename, unlink, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { basename } from "node:path";
 import { chainMobileSelectorForTransport, normalizeMobileSelectorForTransport } from "./mobileSelectors.js";
 function retryOptions(timeoutMs) {
     return timeoutMs ? { timeoutMs } : undefined;
@@ -17,6 +19,164 @@ class MobileAndroidAppImpl {
     locator(selector) {
         return new MobileAndroidLocatorImpl(this, normalizeMobileSelectorForTransport(selector));
     }
+    async registerHook(type) {
+        if (type.name !== "fileChooser" && type.name !== "download") {
+            throw new Error(`hook type ${type.name} is not supported by Android apps`);
+        }
+        const handle = await this.#getHandle();
+        this.#ensureOpen(handle);
+        handle.stream.write({
+            surfaceSessionId: this.#surfaceSessionId,
+            contextSessionId: this.sessionId,
+            registerHook: type.name === "fileChooser"
+                ? { mobileFileChooser: {} }
+                : { mobileDownload: {} },
+        });
+        while (true) {
+            const event = await handle.queue.next();
+            if (event.hookRegistered?.hookId) {
+                const hookId = event.hookRegistered.hookId;
+                return {
+                    id: hookId,
+                    type,
+                    wait: (options = {}) => this.#waitForHook(hookId, type, options),
+                };
+            }
+            if (event.error?.message)
+                throw new Error(event.error.message);
+        }
+    }
+    async #waitForHook(hookId, type, options) {
+        const handle = await this.#getHandle();
+        this.#ensureOpen(handle);
+        handle.stream.write({
+            surfaceSessionId: this.#surfaceSessionId,
+            contextSessionId: this.sessionId,
+            waitForHook: { hookId, retryOptions: retryOptions(options.timeoutMs) },
+        });
+        while (true) {
+            const event = await handle.queue.next();
+            if (event.hookCompleted?.hookId === hookId) {
+                if (type.name === "fileChooser" && event.hookCompleted.mobileFileChooser?.fileChooserId) {
+                    return new MobileFileChooserImpl(this, event.hookCompleted.mobileFileChooser.fileChooserId, event.hookCompleted.mobileFileChooser.isMultiple ?? false);
+                }
+                if (type.name === "download" && event.hookCompleted.mobileDownload?.downloadId) {
+                    return new MobileDownloadImpl(this, event.hookCompleted.mobileDownload.downloadId, event.hookCompleted.mobileDownload.suggestedFilename ?? "download");
+                }
+                throw new Error(`Android ${type.name} hook returned an invalid result`);
+            }
+            if (event.error?.message)
+                throw new Error(event.error.message);
+        }
+    }
+    async setChooserFiles(fileChooserId, files, options) {
+        const handle = await this.#getHandle();
+        this.#ensureOpen(handle);
+        const fileIds = [];
+        for (const file of files)
+            fileIds.push(await this.#uploadLocalFile(handle, file));
+        handle.stream.write({
+            surfaceSessionId: this.#surfaceSessionId,
+            contextSessionId: this.sessionId,
+            setMobileFileChooserFiles: {
+                fileChooserId,
+                fileIds,
+                retryOptions: retryOptions(options.timeoutMs),
+            },
+        });
+        while (true) {
+            const event = await handle.queue.next();
+            if (event.mobileFileChooserFilesSet?.fileChooserId === fileChooserId)
+                return;
+            if (event.error?.message)
+                throw new Error(event.error.message);
+        }
+    }
+    async saveMobileDownload(downloadId, path, options) {
+        const handle = await this.#getHandle();
+        this.#ensureOpen(handle);
+        handle.stream.write({
+            surfaceSessionId: this.#surfaceSessionId,
+            contextSessionId: this.sessionId,
+            saveMobileDownload: { downloadId, retryOptions: retryOptions(options.timeoutMs) },
+        });
+        while (true) {
+            const event = await handle.queue.next();
+            if (event.mobileDownloadSaved?.downloadId === downloadId && event.mobileDownloadSaved.fileId) {
+                await this.#downloadToLocalFile(handle, event.mobileDownloadSaved.fileId, path);
+                return;
+            }
+            if (event.error?.message)
+                throw new Error(event.error.message);
+        }
+    }
+    async #uploadLocalFile(handle, path) {
+        const source = await open(path, "r");
+        const transferId = randomUUID();
+        let offset = 0;
+        try {
+            const size = (await source.stat()).size;
+            do {
+                const buffer = Buffer.alloc(Math.min(256 * 1024, Math.max(0, size - offset)) || 1);
+                const { bytesRead } = await source.read(buffer, 0, buffer.length, offset);
+                const last = offset + bytesRead >= size;
+                handle.stream.write({
+                    surfaceSessionId: this.#surfaceSessionId,
+                    contextSessionId: this.sessionId,
+                    uploadFileChunk: {
+                        transferId,
+                        name: basename(path),
+                        offset: String(offset),
+                        data: buffer.subarray(0, bytesRead),
+                        last,
+                    },
+                });
+                offset += bytesRead;
+            } while (offset < size);
+        }
+        finally {
+            await source.close();
+        }
+        while (true) {
+            const event = await handle.queue.next();
+            if (event.fileUploaded?.transferId === transferId && event.fileUploaded.fileId) {
+                return event.fileUploaded.fileId;
+            }
+            if (event.error?.message)
+                throw new Error(event.error.message);
+        }
+    }
+    async #downloadToLocalFile(handle, fileId, path) {
+        const temporaryPath = `${path}.allwright-${randomUUID()}.tmp`;
+        const destination = await open(temporaryPath, "wx");
+        let offset = 0;
+        try {
+            while (true) {
+                handle.stream.write({
+                    surfaceSessionId: this.#surfaceSessionId,
+                    contextSessionId: this.sessionId,
+                    readFileChunk: { fileId, offset: String(offset), maxBytes: 256 * 1024 },
+                });
+                const event = await handle.queue.next();
+                if (event.error?.message)
+                    throw new Error(event.error.message);
+                if (event.fileChunk?.fileId !== fileId || Number(event.fileChunk.offset ?? -1) !== offset)
+                    continue;
+                const data = event.fileChunk.data ?? new Uint8Array();
+                await destination.write(data, 0, data.length, offset);
+                offset += data.length;
+                if (event.fileChunk.last)
+                    break;
+            }
+            await destination.close();
+            await rename(temporaryPath, path);
+        }
+        catch (error) {
+            await destination.close().catch(() => undefined);
+            await unlink(temporaryPath).catch(() => undefined);
+            throw error;
+        }
+    }
     async click(selector, options = {}) {
         const handle = await this.#getHandle();
         this.#ensureOpen(handle);
@@ -322,6 +482,40 @@ class MobileAndroidAppImpl {
         }
     }
 }
+class MobileFileChooserImpl {
+    page;
+    id;
+    multiple;
+    constructor(page, id, multiple) {
+        this.page = page;
+        this.id = id;
+        this.multiple = multiple;
+    }
+    isMultiple() {
+        return this.multiple;
+    }
+    async setFiles(files, options = {}) {
+        const paths = typeof files === "string" ? [files] : files;
+        if (!this.multiple && paths.length > 1) {
+            throw new Error("Android file chooser does not accept multiple files");
+        }
+        await this.page.setChooserFiles(this.id, paths, options);
+    }
+}
+class MobileDownloadImpl {
+    page;
+    id;
+    suggestedFilename;
+    url = "";
+    constructor(page, id, suggestedFilename) {
+        this.page = page;
+        this.id = id;
+        this.suggestedFilename = suggestedFilename;
+    }
+    async saveAs(path, options = {}) {
+        await this.page.saveMobileDownload(this.id, path, options);
+    }
+}
 class MobileAndroidLocatorImpl {
     page;
     selector;

package/dist/page.js

@@ -1,6 +1,8 @@
 import { WebLocatorBuilders } from "./web-locators.js";
 import { LocatorImpl } from "./locator.js";
-import { writeFile } from "node:fs/promises";
+import { open, rename, unlink, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { basename } from "node:path";
 import { formatActionError } from "./errors.js";
 import { normalizeSelectorForTransport } from "./selectors.js";
 import { createPageHandle } from "./runtime.js";
@@ -85,12 +87,16 @@ export class PageImpl extends WebLocatorBuilders {
     async setFileChooserFiles(fileChooserId, files, options = {}) {
         const handle = await this.#getHandle();
         this.#ensureOpen(handle);
+        const fileIds = [];
+        for (const file of files) {
+            fileIds.push(await this.#uploadLocalFile(handle, file));
+        }
         handle.stream.write({
             surfaceSessionId: this.browserSessionId,
             contextSessionId: this.sessionId,
             setFileChooserFiles: {
                 fileChooserId,
-                files,
+                fileIds,
                 retryOptions: options.timeoutMs ? { timeoutMs: options.timeoutMs } : undefined,
             },
         });
@@ -112,13 +118,13 @@ export class PageImpl extends WebLocatorBuilders {
             contextSessionId: this.sessionId,
             saveDownload: {
                 downloadId,
-                path,
                 retryOptions: options.timeoutMs ? { timeoutMs: options.timeoutMs } : undefined,
             },
         });
         while (true) {
             const event = await handle.queue.next();
-            if (event.downloadSaved?.downloadId === downloadId) {
+            if (event.downloadSaved?.downloadId === downloadId && event.downloadSaved.fileId) {
+                await this.#downloadToLocalFile(handle, event.downloadSaved.fileId, path);
                 return;
             }
             if (event.error?.message) {
@@ -126,6 +132,77 @@ export class PageImpl extends WebLocatorBuilders {
             }
         }
     }
+    async #uploadLocalFile(handle, path) {
+        const source = await open(path, "r");
+        const transferId = randomUUID();
+        const name = basename(path);
+        let offset = 0;
+        try {
+            const size = (await source.stat()).size;
+            do {
+                const buffer = Buffer.alloc(Math.min(256 * 1024, Math.max(0, size - offset)) || 1);
+                const { bytesRead } = await source.read(buffer, 0, buffer.length, offset);
+                const last = offset + bytesRead >= size;
+                handle.stream.write({
+                    surfaceSessionId: this.browserSessionId,
+                    contextSessionId: this.sessionId,
+                    uploadFileChunk: {
+                        transferId,
+                        name,
+                        offset: String(offset),
+                        data: buffer.subarray(0, bytesRead),
+                        last,
+                    },
+                });
+                offset += bytesRead;
+            } while (offset < size);
+        }
+        finally {
+            await source.close();
+        }
+        while (true) {
+            const event = await handle.queue.next();
+            if (event.fileUploaded?.transferId === transferId && event.fileUploaded.fileId) {
+                return event.fileUploaded.fileId;
+            }
+            if (event.error?.message) {
+                throw formatActionError("upload file", event.error.message);
+            }
+        }
+    }
+    async #downloadToLocalFile(handle, fileId, path) {
+        const temporaryPath = `${path}.allwright-${randomUUID()}.tmp`;
+        const destination = await open(temporaryPath, "wx");
+        let offset = 0;
+        try {
+            while (true) {
+                handle.stream.write({
+                    surfaceSessionId: this.browserSessionId,
+                    contextSessionId: this.sessionId,
+                    readFileChunk: { fileId, offset: String(offset), maxBytes: 256 * 1024 },
+                });
+                const event = await handle.queue.next();
+                if (event.error?.message) {
+                    throw formatActionError("download file", event.error.message);
+                }
+                if (event.fileChunk?.fileId !== fileId || Number(event.fileChunk.offset ?? -1) !== offset) {
+                    continue;
+                }
+                const data = event.fileChunk.data ?? new Uint8Array();
+                await destination.write(data, 0, data.length, offset);
+                offset += data.length;
+                if (event.fileChunk.last)
+                    break;
+            }
+            await destination.close();
+            await rename(temporaryPath, path);
+        }
+        catch (error) {
+            await destination.close().catch(() => undefined);
+            await unlink(temporaryPath).catch(() => undefined);
+            throw error;
+        }
+    }
     locator(selector, options) {
         const result = new LocatorImpl({ page: this, selector: normalizeSelectorForTransport(selector) });
         return options ? result.filter(options) : result;

package/dist/types.d.ts

@@ -110,13 +110,13 @@ export interface Hook<T> {
 }
 export interface FileChooser {
     readonly id: string;
-    readonly page: Page;
+    readonly page: Page | MobileAndroidApp;
     isMultiple(): boolean;
     setFiles(files: string | string[], options?: CommandOptions): Promise<void>;
 }
 export interface Download {
     readonly id: string;
-    readonly page: Page;
+    readonly page: Page | MobileAndroidApp;
     readonly url: string;
     readonly suggestedFilename: string;
     saveAs(path: string, options?: CommandOptions): Promise<void>;
@@ -192,6 +192,7 @@ export interface MobileAndroidApp {
     innerText(selector: string, options?: CommandOptions): Promise<TextResult>;
     waitForSelector(selector: string, options?: WaitForSelectorOptions): Promise<WaitForSelectorResult>;
     screenshot(options?: ScreenshotOptions): Promise<ScreenshotResult>;
+    registerHook<T>(type: HookType<T>): Promise<Hook<T>>;
 }
 export interface MobileAndroidDevice {
     readonly sessionId: string;
@@ -411,15 +412,51 @@ export interface ContextSessionEvent {
             suggestedFilename?: string;
             note?: string;
         };
+        mobileFileChooser?: {
+            fileChooserId?: string;
+            isMultiple?: boolean;
+            note?: string;
+        };
+        mobileDownload?: {
+            downloadId?: string;
+            suggestedFilename?: string;
+            note?: string;
+        };
     };
     fileChooserFilesSet?: {
         fileChooserId?: string;
-        files?: string[];
+        fileIds?: string[];
         note?: string;
     };
     downloadSaved?: {
         downloadId?: string;
-        path?: string;
+        fileId?: string;
+        suggestedFilename?: string;
+        size?: string;
+        note?: string;
+    };
+    fileUploaded?: {
+        transferId?: string;
+        fileId?: string;
+        name?: string;
+        size?: string;
+    };
+    fileChunk?: {
+        fileId?: string;
+        offset?: string;
+        data?: Uint8Array;
+        last?: boolean;
+    };
+    mobileFileChooserFilesSet?: {
+        fileChooserId?: string;
+        fileIds?: string[];
+        note?: string;
+    };
+    mobileDownloadSaved?: {
+        downloadId?: string;
+        fileId?: string;
+        suggestedFilename?: string;
+        size?: string;
         note?: string;
     };
     navigated?: {
@@ -517,6 +554,8 @@ export interface RegisterHookRequest {
         newPage?: Record<string, never>;
         fileChooser?: Record<string, never>;
         download?: Record<string, never>;
+        mobileFileChooser?: Record<string, never>;
+        mobileDownload?: Record<string, never>;
     };
 }
 export interface SaveDownloadRequest {
@@ -524,7 +563,6 @@ export interface SaveDownloadRequest {
     contextSessionId: string;
     saveDownload: {
         downloadId: string;
-        path: string;
         retryOptions?: {
             timeoutMs?: number;
         };
@@ -535,7 +573,48 @@ export interface SetFileChooserFilesRequest {
     contextSessionId: string;
     setFileChooserFiles: {
         fileChooserId: string;
-        files: string[];
+        fileIds: string[];
+        retryOptions?: {
+            timeoutMs?: number;
+        };
+    };
+}
+export interface UploadFileChunkRequest {
+    surfaceSessionId: string;
+    contextSessionId: string;
+    uploadFileChunk: {
+        transferId: string;
+        name: string;
+        offset: string;
+        data: Uint8Array;
+        last: boolean;
+    };
+}
+export interface ReadFileChunkRequest {
+    surfaceSessionId: string;
+    contextSessionId: string;
+    readFileChunk: {
+        fileId: string;
+        offset: string;
+        maxBytes: number;
+    };
+}
+export interface SetMobileFileChooserFilesRequest {
+    surfaceSessionId: string;
+    contextSessionId: string;
+    setMobileFileChooserFiles: {
+        fileChooserId: string;
+        fileIds: string[];
+        retryOptions?: {
+            timeoutMs?: number;
+        };
+    };
+}
+export interface SaveMobileDownloadRequest {
+    surfaceSessionId: string;
+    contextSessionId: string;
+    saveMobileDownload: {
+        downloadId: string;
         retryOptions?: {
             timeoutMs?: number;
         };
@@ -730,7 +809,7 @@ export interface CloseContextRequest {
     close: Record<string, never>;
 }
 export type SurfaceSessionRequest = LaunchBrowserRequest | LaunchChromeRequest | OpenContextRequest | ConnectMobileRequest | LaunchAppRequest | SurfacePingRequest | CloseSurfaceRequest;
-export type ContextSessionRequest = ContextPingRequest | RegisterHookRequest | WaitForHookRequest | SetFileChooserFilesRequest | SaveDownloadRequest | NavigateRequest | ClickRequest | CountRequest | HighlightRequest | FocusRequest | FillRequest | HoverRequest | PressRequest | TextContentRequest | InnerTextRequest | WaitForSelectorRequest | AccessibilitySnapshotRequest | ScreenshotRequest | CloseContextRequest;
+export type ContextSessionRequest = ContextPingRequest | RegisterHookRequest | WaitForHookRequest | SetFileChooserFilesRequest | SaveDownloadRequest | UploadFileChunkRequest | ReadFileChunkRequest | SetMobileFileChooserFilesRequest | SaveMobileDownloadRequest | NavigateRequest | ClickRequest | CountRequest | HighlightRequest | FocusRequest | FillRequest | HoverRequest | PressRequest | TextContentRequest | InnerTextRequest | WaitForSelectorRequest | AccessibilitySnapshotRequest | ScreenshotRequest | CloseContextRequest;
 export type SurfaceSessionStream = grpc.ClientDuplexStream<SurfaceSessionRequest, SurfaceSessionEvent>;
 export type ContextSessionStream = grpc.ClientDuplexStream<ContextSessionRequest, ContextSessionEvent>;
 export interface EngineServiceClientShape {

package/package.json

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

package/proto/core/v1/context.proto

@@ -6,6 +6,7 @@ option java_package = "dev.allwright.engine.v1";
 option java_multiple_files = true;
 
 import "core/v1/common.proto";
+import "surfaces/mobile/v1/mobile.proto";
 import "surfaces/web/v1/web.proto";
 
 message ContextSessionCommand {
@@ -32,6 +33,10 @@ message ContextSessionCommand {
     WaitForHookCommand wait_for_hook = 19;
     SetFileChooserFilesCommand set_file_chooser_files = 20;
     SaveDownloadCommand save_download = 21;
+    UploadFileChunkCommand upload_file_chunk = 22;
+    ReadFileChunkCommand read_file_chunk = 23;
+    SetMobileFileChooserFilesCommand set_mobile_file_chooser_files = 24;
+    SaveMobileDownloadCommand save_mobile_download = 25;
   }
 }
 
@@ -67,6 +72,10 @@ message ContextSessionEvent {
     HookCompletedEvent hook_completed = 21;
     FileChooserFilesSetEvent file_chooser_files_set = 22;
     DownloadSavedEvent download_saved = 23;
+    FileUploadedEvent file_uploaded = 24;
+    FileChunkEvent file_chunk = 25;
+    MobileFileChooserFilesSetEvent mobile_file_chooser_files_set = 26;
+    MobileDownloadSavedEvent mobile_download_saved = 27;
   }
 }
 
@@ -91,6 +100,8 @@ message RegisterHookCommand {
     RegisterNewPageHook new_page = 1;
     RegisterFileChooserHook file_chooser = 2;
     RegisterDownloadHook download = 3;
+    RegisterMobileFileChooserHook mobile_file_chooser = 4;
+    RegisterMobileDownloadHook mobile_download = 5;
   }
 }
 
@@ -110,9 +121,39 @@ message HookCompletedEvent {
     NewPageHookResult new_page = 2;
     FileChooserHookResult file_chooser = 3;
     DownloadHookResult download = 4;
+    MobileFileChooserHookResult mobile_file_chooser = 5;
+    MobileDownloadHookResult mobile_download = 6;
   }
 }
 
+message UploadFileChunkCommand {
+  string transfer_id = 1;
+  string name = 2;
+  uint64 offset = 3;
+  bytes data = 4;
+  bool last = 5;
+}
+
+message FileUploadedEvent {
+  string transfer_id = 1;
+  string file_id = 2;
+  string name = 3;
+  uint64 size = 4;
+}
+
+message ReadFileChunkCommand {
+  string file_id = 1;
+  uint64 offset = 2;
+  uint32 max_bytes = 3;
+}
+
+message FileChunkEvent {
+  string file_id = 1;
+  uint64 offset = 2;
+  bytes data = 3;
+  bool last = 4;
+}
+
 message NavigatePageCommand {
   string url = 1;
   optional CommandRetryOptions retry_options = 2;

package/proto/surfaces/mobile/v1/mobile.proto

@@ -56,3 +56,12 @@ message AppLaunchedEvent {
   optional string activity_name = 4;
   optional string webview_context = 5;
 }
+
+message RegisterMobileFileChooserHook {}
+message MobileFileChooserHookResult { string file_chooser_id = 1; bool is_multiple = 2; string note = 3; }
+message SetMobileFileChooserFilesCommand { string file_chooser_id = 1; repeated string file_ids = 2; optional CommandRetryOptions retry_options = 3; }
+message MobileFileChooserFilesSetEvent { string file_chooser_id = 1; repeated string file_ids = 2; string note = 3; }
+message RegisterMobileDownloadHook {}
+message MobileDownloadHookResult { string download_id = 1; string suggested_filename = 2; string note = 3; }
+message SaveMobileDownloadCommand { string download_id = 1; optional CommandRetryOptions retry_options = 2; }
+message MobileDownloadSavedEvent { string download_id = 1; string file_id = 2; string suggested_filename = 3; uint64 size = 4; string note = 5; }

package/proto/surfaces/web/v1/web.proto

@@ -57,13 +57,13 @@ message FileChooserHookResult {
 
 message SetFileChooserFilesCommand {
   string file_chooser_id = 1;
-  repeated string files = 2;
+  repeated string file_ids = 2;
   optional CommandRetryOptions retry_options = 3;
 }
 
 message FileChooserFilesSetEvent {
   string file_chooser_id = 1;
-  repeated string files = 2;
+  repeated string file_ids = 2;
   string note = 3;
 }
 
@@ -78,12 +78,13 @@ message DownloadHookResult {
 
 message SaveDownloadCommand {
   string download_id = 1;
-  string path = 2;
-  optional CommandRetryOptions retry_options = 3;
+  optional CommandRetryOptions retry_options = 2;
 }
 
 message DownloadSavedEvent {
   string download_id = 1;
-  string path = 2;
-  string note = 3;
+  string file_id = 2;
+  string suggested_filename = 3;
+  uint64 size = 4;
+  string note = 5;
 }