@elizaos/computeruse 0.24.20

package/tests/locator-waitfor.test.js

@@ -0,0 +1,286 @@
+const { Desktop } = require("../index.js");
+
+/**
+ * Test for Locator.waitFor() method with 'exists' condition
+ */
+async function testWaitForExists() {
+  console.log("🕐 Testing Locator.waitFor('exists')...");
+
+  try {
+    const desktop = new Desktop();
+
+    // Get any available application for testing
+    const apps = desktop.applications();
+    if (apps.length === 0) {
+      throw new Error("No applications found for testing");
+    }
+
+    const testApp = apps[0];
+    console.log(`📱 Testing with app: ${testApp.name()}`);
+
+    // Test: Wait for a window to exist (should succeed immediately)
+    console.log("Test: Wait for window to exist");
+    const element = await desktop.locator("role:window").waitFor("exists", 5000);
+
+    if (!element) {
+      throw new Error("Expected element to be returned");
+    }
+
+    console.log(`✅ Found window: ${element.name()}`);
+    return true;
+  } catch (error) {
+    console.error("❌ WaitFor exists test failed:", error.message);
+    return false;
+  }
+}
+
+/**
+ * Test waitFor() with 'visible' condition
+ */
+async function testWaitForVisible() {
+  console.log("🕐 Testing Locator.waitFor('visible')...");
+
+  try {
+    const desktop = new Desktop();
+
+    // Test: Wait for a visible window
+    console.log("Test: Wait for window to be visible");
+    const element = await desktop.locator("role:window").waitFor("visible", 5000);
+
+    // Check that the element is actually visible
+    if (!element.isVisible()) {
+      throw new Error("Element should be visible");
+    }
+
+    console.log(`✅ Found visible window: ${element.name()}`);
+    return true;
+  } catch (error) {
+    console.error("❌ WaitFor visible test failed:", error.message);
+    return false;
+  }
+}
+
+/**
+ * Test waitFor() timeout behavior
+ */
+async function testWaitForTimeout() {
+  console.log("🕐 Testing Locator.waitFor() timeout...");
+
+  try {
+    const desktop = new Desktop();
+
+    // Test: Wait for a non-existent element (should timeout)
+    console.log("Test: Wait for non-existent element (expecting timeout)");
+    let timedOut = false;
+
+    try {
+      await desktop
+        .locator("role:button|ThisButtonDoesNotExist12345XYZ")
+        .waitFor("exists", 1000);
+    } catch (err) {
+      if (err.message.includes("Timed out") || err.message.includes("timeout")) {
+        timedOut = true;
+        console.log("✅ Correctly timed out");
+      } else {
+        throw new Error(`Unexpected error: ${err.message}`);
+      }
+    }
+
+    if (!timedOut) {
+      throw new Error("Expected timeout error");
+    }
+
+    return true;
+  } catch (error) {
+    console.error("❌ WaitFor timeout test failed:", error.message);
+    return false;
+  }
+}
+
+/**
+ * Test waitFor() with different conditions
+ */
+async function testWaitForConditions() {
+  console.log("🕐 Testing Locator.waitFor() with different conditions...");
+
+  try {
+    const desktop = new Desktop();
+
+    // Test each condition on a window (which should be visible and enabled)
+    const conditions = ["exists", "visible", "enabled"];
+
+    for (const condition of conditions) {
+      console.log(`Test: waitFor('${condition}')`);
+      const element = await desktop
+        .locator("role:window")
+        .waitFor(condition, 5000);
+
+      if (!element) {
+        throw new Error(`No element returned for condition '${condition}'`);
+      }
+
+      console.log(`✅ Condition '${condition}' met`);
+    }
+
+    return true;
+  } catch (error) {
+    console.error("❌ WaitFor conditions test failed:", error.message);
+    return false;
+  }
+}
+
+/**
+ * Test waitFor() with invalid condition
+ */
+async function testWaitForInvalidCondition() {
+  console.log("🕐 Testing Locator.waitFor() with invalid condition...");
+
+  try {
+    const desktop = new Desktop();
+
+    // Test: Invalid condition should throw error
+    console.log("Test: Wait with invalid condition");
+    let errorThrown = false;
+
+    try {
+      await desktop.locator("role:window").waitFor("invalid_condition", 1000);
+    } catch (err) {
+      if (err.message.includes("Invalid condition")) {
+        errorThrown = true;
+        console.log("✅ Correctly rejected invalid condition");
+      } else {
+        throw new Error(`Unexpected error: ${err.message}`);
+      }
+    }
+
+    if (!errorThrown) {
+      throw new Error("Expected error for invalid condition");
+    }
+
+    return true;
+  } catch (error) {
+    console.error("❌ WaitFor invalid condition test failed:", error.message);
+    return false;
+  }
+}
+
+/**
+ * Test waitFor() with chaining
+ */
+async function testWaitForChaining() {
+  console.log("🕐 Testing Locator.waitFor() with chaining...");
+
+  try {
+    const desktop = new Desktop();
+    const apps = desktop.applications();
+
+    if (apps.length === 0) {
+      throw new Error("No applications found for testing");
+    }
+
+    const testApp = apps[0];
+
+    // Test: Wait with chained locator
+    console.log("Test: waitFor with chained locator");
+    const element = await testApp
+      .locator("role:window")
+      .waitFor("visible", 3000);
+
+    console.log(`✅ Found element via chain: ${element.name()}`);
+    return true;
+  } catch (error) {
+    // This might fail if the app has no window, which is acceptable
+    if (error.message.includes("Timed out")) {
+      console.log("ℹ️  No window found in chain (acceptable)");
+      return true;
+    }
+    console.error("❌ WaitFor chaining test failed:", error.message);
+    return false;
+  }
+}
+
+/**
+ * Main test runner
+ */
+async function runWaitForTests() {
+  console.log("🚀 Starting Locator.waitFor() tests...\n");
+
+  let passed = 0;
+  let total = 0;
+
+  // Test 1: Wait for exists
+  total++;
+  if (await testWaitForExists()) {
+    passed++;
+  }
+
+  console.log(); // Empty line
+
+  // Test 2: Wait for visible
+  total++;
+  if (await testWaitForVisible()) {
+    passed++;
+  }
+
+  console.log(); // Empty line
+
+  // Test 3: Timeout behavior
+  total++;
+  if (await testWaitForTimeout()) {
+    passed++;
+  }
+
+  console.log(); // Empty line
+
+  // Test 4: Different conditions
+  total++;
+  if (await testWaitForConditions()) {
+    passed++;
+  }
+
+  console.log(); // Empty line
+
+  // Test 5: Invalid condition
+  total++;
+  if (await testWaitForInvalidCondition()) {
+    passed++;
+  }
+
+  console.log(); // Empty line
+
+  // Test 6: Chaining
+  total++;
+  if (await testWaitForChaining()) {
+    passed++;
+  }
+
+  console.log(); // Empty line
+
+  // Results
+  if (passed === total) {
+    console.log(`🎉 All waitFor tests passed! (${passed}/${total})`);
+    process.exit(0);
+  } else {
+    console.log(`❌ Some tests failed: ${passed}/${total} passed`);
+    process.exit(1);
+  }
+}
+
+// Export for use in other test files
+module.exports = {
+  testWaitForExists,
+  testWaitForVisible,
+  testWaitForTimeout,
+  testWaitForConditions,
+  testWaitForInvalidCondition,
+  testWaitForChaining,
+  runWaitForTests,
+};
+
+// Run tests if this file is executed directly
+if (require.main === module) {
+  runWaitForTests().catch((error) => {
+    console.error("💥 Test runner crashed:", error);
+    process.exit(1);
+  });
+}

package/wrapper.d.ts

@@ -0,0 +1,84 @@
+// Re-export everything from the native bindings
+export * from "./index";
+
+/** Thrown when an element is not found. */
+export class ElementNotFoundError extends Error {
+  constructor(message: string);
+}
+
+/** Thrown when an operation times out. */
+export class TimeoutError extends Error {
+  constructor(message: string);
+}
+
+/** Thrown when permission is denied. */
+export class PermissionDeniedError extends Error {
+  constructor(message: string);
+}
+
+/** Thrown for platform-specific errors. */
+export class PlatformError extends Error {
+  constructor(message: string);
+}
+
+/** Thrown for unsupported operations. */
+export class UnsupportedOperationError extends Error {
+  constructor(message: string);
+}
+
+/** Thrown for unsupported platforms. */
+export class UnsupportedPlatformError extends Error {
+  constructor(message: string);
+}
+
+/** Thrown for invalid arguments. */
+export class InvalidArgumentError extends Error {
+  constructor(message: string);
+}
+
+/** Thrown for internal errors. */
+export class InternalError extends Error {
+  constructor(message: string);
+}
+
+// Browser script execution types
+export type BrowserScriptEnv = Record<string, unknown>;
+export type BrowserScriptFunction<
+  T = unknown,
+  Env extends BrowserScriptEnv = BrowserScriptEnv,
+> = (env: Env) => T | Promise<T>;
+export interface BrowserScriptOptions<
+  Env extends BrowserScriptEnv = BrowserScriptEnv,
+> {
+  file: string;
+  env?: Env;
+}
+
+// Augment Desktop class with browser script methods
+declare module "./index.d" {
+  interface Desktop {
+    executeBrowserScript<
+      T = unknown,
+      Env extends BrowserScriptEnv = BrowserScriptEnv,
+    >(
+      fn: BrowserScriptFunction<T, Env>,
+      env?: Env,
+    ): Promise<T>;
+    executeBrowserScript<Env extends BrowserScriptEnv = BrowserScriptEnv>(
+      options: BrowserScriptOptions<Env>,
+    ): Promise<string>;
+  }
+
+  interface Element {
+    executeBrowserScript<
+      T = unknown,
+      Env extends BrowserScriptEnv = BrowserScriptEnv,
+    >(
+      fn: BrowserScriptFunction<T, Env>,
+      env?: Env,
+    ): Promise<T>;
+    executeBrowserScript<Env extends BrowserScriptEnv = BrowserScriptEnv>(
+      options: BrowserScriptOptions<Env>,
+    ): Promise<string>;
+  }
+}

package/wrapper.js

@@ -0,0 +1,344 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var wrapper_exports = {};
+__export(wrapper_exports, {
+  ClickType: () => import_index.ClickType,
+  ClusteredBoundsEntry: () => import_index.ClusteredBoundsEntry,
+  ClusteredFormattingResult: () => import_index.ClusteredFormattingResult,
+  Desktop: () => Desktop,
+  Element: () => Element,
+  ElementNotFoundError: () => ElementNotFoundError,
+  ElementSource: () => import_index.ElementSource,
+  InternalError: () => InternalError,
+  InvalidArgumentError: () => InvalidArgumentError,
+  Locator: () => Locator,
+  PermissionDeniedError: () => PermissionDeniedError,
+  PlatformError: () => PlatformError,
+  PropertyLoadingMode: () => import_index.PropertyLoadingMode,
+  Selector: () => Selector,
+  TextPosition: () => import_index.TextPosition,
+  TimeoutError: () => TimeoutError,
+  TreeOutputFormat: () => import_index.TreeOutputFormat,
+  UnsupportedOperationError: () => UnsupportedOperationError,
+  UnsupportedPlatformError: () => UnsupportedPlatformError,
+  VisionType: () => import_index.VisionType,
+  WindowManager: () => WindowManager
+});
+module.exports = __toCommonJS(wrapper_exports);
+var native = __toESM(require("./index.js"));
+var util = __toESM(require("util"));
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var import_index = require("./index.js");
+function patchInspector(Klass, methodName = "toString", forcePlainObject = false) {
+  if (!Klass || typeof Klass !== "function") {
+    console.log("inspect not a function");
+    return;
+  }
+  const proto = Klass.prototype;
+  const original = proto[util.inspect.custom];
+  proto[util.inspect.custom] = function(...args) {
+    if (typeof this[methodName] === "function") {
+      const result = this[methodName](...args);
+      if (forcePlainObject && result && typeof result === "object") {
+        return { ...result };
+      }
+      return result;
+    }
+    if (typeof original === "function") {
+      return original.apply(this, args);
+    }
+    return { ...this };
+  };
+}
+function wrapNativeFunction(fn) {
+  if (typeof fn !== "function") return fn;
+  return function(...args) {
+    try {
+      const result = fn.apply(this, args);
+      if (result instanceof Promise) {
+        return result.catch((error) => {
+          throw mapNativeError(error);
+        });
+      }
+      return result;
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  };
+}
+function wrapClassMethods(Class) {
+  const prototype = Class.prototype;
+  const methods = Object.getOwnPropertyNames(prototype);
+  methods.forEach((method) => {
+    if (method !== "constructor" && typeof prototype[method] === "function") {
+      prototype[method] = wrapNativeFunction(prototype[method]);
+    }
+  });
+  return Class;
+}
+function wrapClass(Class, ...inspectOptions) {
+  const Wrapped = wrapClassMethods(Class);
+  patchInspector(Wrapped, ...inspectOptions || []);
+  return Wrapped;
+}
+class ElementNotFoundError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ElementNotFoundError";
+  }
+}
+class TimeoutError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TimeoutError";
+  }
+}
+class PermissionDeniedError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PermissionDeniedError";
+  }
+}
+class PlatformError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PlatformError";
+  }
+}
+class UnsupportedOperationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UnsupportedOperationError";
+  }
+}
+class UnsupportedPlatformError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UnsupportedPlatformError";
+  }
+}
+class InvalidArgumentError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidArgumentError";
+  }
+}
+class InternalError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InternalError";
+  }
+}
+function mapNativeError(error) {
+  if (!error.message) return error;
+  const message = error.message;
+  if (message.startsWith("ELEMENT_NOT_FOUND:")) {
+    return new ElementNotFoundError(
+      message.replace("ELEMENT_NOT_FOUND:", "").trim()
+    );
+  }
+  if (message.startsWith("OPERATION_TIMED_OUT:")) {
+    return new TimeoutError(message.replace("OPERATION_TIMED_OUT:", "").trim());
+  }
+  if (message.startsWith("PERMISSION_DENIED:")) {
+    return new PermissionDeniedError(
+      message.replace("PERMISSION_DENIED:", "").trim()
+    );
+  }
+  if (message.startsWith("PLATFORM_ERROR:")) {
+    return new PlatformError(message.replace("PLATFORM_ERROR:", "").trim());
+  }
+  if (message.startsWith("UNSUPPORTED_OPERATION:")) {
+    return new UnsupportedOperationError(
+      message.replace("UNSUPPORTED_OPERATION:", "").trim()
+    );
+  }
+  if (message.startsWith("UNSUPPORTED_PLATFORM:")) {
+    return new UnsupportedPlatformError(
+      message.replace("UNSUPPORTED_PLATFORM:", "").trim()
+    );
+  }
+  if (message.startsWith("INVALID_ARGUMENT:")) {
+    return new InvalidArgumentError(
+      message.replace("INVALID_ARGUMENT:", "").trim()
+    );
+  }
+  if (message.startsWith("INTERNAL_ERROR:")) {
+    return new InternalError(message.replace("INTERNAL_ERROR:", "").trim());
+  }
+  return error;
+}
+async function enhancedExecuteBrowserScript(scriptOrFunction, processOrEnv, timeoutMs) {
+  const isDesktop = this.constructor?.name === "Desktop";
+  let process;
+  let envOrOptions;
+  if (isDesktop) {
+    if (typeof processOrEnv !== "string") {
+      throw new Error(
+        "Desktop.executeBrowserScript requires 'process' as second argument (e.g., 'chrome', 'msedge', 'firefox'). Usage: desktop.executeBrowserScript(script, 'chrome', timeoutMs?)"
+      );
+    }
+    process = processOrEnv;
+  } else {
+    envOrOptions = processOrEnv;
+  }
+  let script;
+  let env = {};
+  let shouldInjectEnv = false;
+  if (typeof scriptOrFunction === "string") {
+    if (scriptOrFunction.endsWith(".ts") || scriptOrFunction.endsWith(".js")) {
+      const filePath = path.resolve(scriptOrFunction);
+      if (!fs.existsSync(filePath)) {
+        throw new Error(`Browser script file not found: ${filePath}`);
+      }
+      let fileContent = fs.readFileSync(filePath, "utf-8");
+      if (filePath.endsWith(".ts")) {
+        try {
+          const esbuild = require("esbuild");
+          const result = await esbuild.transform(fileContent, {
+            loader: "ts",
+            target: "es2020",
+            format: "iife"
+          });
+          fileContent = result.code;
+        } catch (e) {
+          console.warn(
+            "esbuild not found - using TypeScript file as-is:",
+            e.message
+          );
+        }
+      }
+      script = fileContent;
+      env = envOrOptions || {};
+      shouldInjectEnv = true;
+    } else {
+      script = scriptOrFunction;
+    }
+  } else if (typeof scriptOrFunction === "function") {
+    const funcString = scriptOrFunction.toString();
+    env = envOrOptions || {};
+    script = `
+      (async function() {
+        const fn = ${funcString};
+        const result = await fn(${JSON.stringify(env)});
+
+        // Auto-stringify result if it's an object
+        if (result !== undefined && result !== null) {
+          if (typeof result === 'object') {
+            return JSON.stringify(result);
+          }
+          return String(result);
+        }
+        return "undefined";
+      })()
+    `;
+  } else if (typeof scriptOrFunction === "object" && scriptOrFunction.file) {
+    const options = scriptOrFunction;
+    const filePath = path.resolve(options.file);
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`Browser script file not found: ${filePath}`);
+    }
+    let fileContent = fs.readFileSync(filePath, "utf-8");
+    if (filePath.endsWith(".ts")) {
+      try {
+        const esbuild = require("esbuild");
+        const result = await esbuild.transform(fileContent, {
+          loader: "ts",
+          target: "es2020",
+          format: "iife"
+        });
+        fileContent = result.code;
+      } catch (e) {
+        console.warn(
+          "esbuild not found - using TypeScript file as-is:",
+          e.message
+        );
+      }
+    }
+    script = fileContent;
+    env = options.env || {};
+    shouldInjectEnv = true;
+  } else {
+    throw new Error(
+      "Invalid argument to executeBrowserScript: expected string, function, or {file, env} object"
+    );
+  }
+  if (shouldInjectEnv && env && Object.keys(env).length > 0) {
+    const envObject = `const env = ${JSON.stringify(env)};`;
+    script = `${envObject}
+${script}`;
+  }
+  const resultStr = isDesktop ? await this._originalExecuteBrowserScript(script, process, timeoutMs) : await this._originalExecuteBrowserScript(script);
+  if (typeof scriptOrFunction === "function") {
+    try {
+      return JSON.parse(resultStr);
+    } catch (e) {
+      return resultStr;
+    }
+  }
+  return resultStr;
+}
+const Desktop = wrapClassMethods(native.Desktop);
+const Element = wrapClass(native.Element);
+const Locator = wrapClass(native.Locator);
+const Selector = wrapClass(native.Selector);
+const WindowManager = wrapClassMethods(native.WindowManager);
+if (Desktop.prototype.executeBrowserScript) {
+  Desktop.prototype._originalExecuteBrowserScript = Desktop.prototype.executeBrowserScript;
+  Desktop.prototype.executeBrowserScript = enhancedExecuteBrowserScript;
+}
+if (Element.prototype.executeBrowserScript) {
+  Element.prototype._originalExecuteBrowserScript = Element.prototype.executeBrowserScript;
+  Element.prototype.executeBrowserScript = enhancedExecuteBrowserScript;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ClickType,
+  ClusteredBoundsEntry,
+  ClusteredFormattingResult,
+  Desktop,
+  Element,
+  ElementNotFoundError,
+  ElementSource,
+  InternalError,
+  InvalidArgumentError,
+  Locator,
+  PermissionDeniedError,
+  PlatformError,
+  PropertyLoadingMode,
+  Selector,
+  TextPosition,
+  TimeoutError,
+  TreeOutputFormat,
+  UnsupportedOperationError,
+  UnsupportedPlatformError,
+  VisionType,
+  WindowManager
+});