gpt-driver-node 1.0.1 → 1.0.2

package/dist/index.cjs

@@ -160,6 +160,14 @@ const SavableTestStoreSchema = zod.z.object({
   steps: zod.z.array(SavableStepSchema),
   params: zod.z.record(zod.z.string(), zod.z.string()).optional()
 });
+const VariablesSchema = zod.z.record(zod.z.string(), zod.z.string()).optional().default({});
+const ConfigSchema = zod.z.object({
+  testDir: zod.z.string(),
+  driver: zod.z.string(),
+  port: zod.z.number(),
+  apiKey: zod.z.string(),
+  variables: VariablesSchema
+});
 
 const CACHE_SERVER_URL = "https://cache.mobileboost.io";
 const GPT_DRIVER_BASE_URL = "https://api.mobileboost.io";
@@ -604,7 +612,6 @@ class GptDriver {
     });
   }
   apiKey;
-  organisationId;
   gptDriverSessionId;
   gptDriverBaseUrl;
   appiumSessionConfig;
@@ -616,6 +623,8 @@ class GptDriver {
   buildId;
   testId;
   step_number = 1;
+  organisationId;
+  configFilePath;
   // Smart loop state - maintains action history across steps for context
   globalActionHistory = [];
   /**
@@ -640,11 +649,12 @@ class GptDriver {
   constructor(config) {
     this.testId = config.testId;
     this.apiKey = config.apiKey;
-    this.organisationId = config.organisationId;
     this.buildId = config.buildId;
     this.useGptDriverCloud = config.useGptDriverCloud;
     this.gptDriverBaseUrl = GPT_DRIVER_BASE_URL;
     this.cachingMode = config.cachingMode ?? "NONE";
+    this.organisationId = config.organisationId;
+    this.configFilePath = config.configFilePath;
     if (config.useGptDriverCloud) {
       if (config.serverConfig.device?.platform == null) {
         throw new Error("Platform is missing. Please specify the platform when using GPTDriver Cloud.");
@@ -1005,86 +1015,12 @@ class GptDriver {
       await this.gptHandler(command);
     }
   }
-  /**
-   * Executes a specified command within the WebDriver session with configurable caching options.
-   *
-   * This is the recommended method for executing commands. It provides fine-grained control over
-   * caching behavior, allowing you to optimize performance and costs for repetitive test scenarios.
-   *
-   * If an `appiumHandler` is provided, it will be invoked with the WebDriver instance to perform
-   * the command-specific operations. After executing the handler, the executed commands get logged
-   * on the GPTDriver servers. If the handler execution fails or no handler is provided, the command
-   * gets executed by the GPTDriver using natural language processing.
-   *
-   * @param {Object} params - The execution parameters
-   * @param {string} params.command - The natural language command to be executed by the GPTDriver.
-   *                                  Examples: "Click the login button", "Enter 'test@example.com' in the email field"
-   * @param {AppiumHandler} [params.appiumHandler] - An optional function that processes Appium-specific commands.
-   *                                                  If provided, this handler is executed instead of calling
-   *                                                  the GPTDriver API. Useful for performance optimization when
-   *                                                  you know the exact Appium commands to execute.
-   * @param {CachingMode} [params.cachingMode] - Controls how the GPTDriver caches this command execution.
-   *                                             If not specified, uses the global caching mode set in the constructor.
-   *                                             Options:
-   *                                             - "NONE"
-   *                                             - "FULL_SCREEN"
-   *                                             - "INTERACTION_REGION"
-   * @param {boolean} [params.useSmartLoop] - If true, uses the smart loop execution (Cache -> AI -> Execute -> Populate)
-   *                                          which optimizes execution by checking cache first and populating it after.
-   *                                          Default: false (uses legacy gptHandler)
-   *
-   * @returns {Promise<void>} A promise that resolves when the command execution is complete.
-   *
-   * @throws {Error} If an error occurs during the execution of the Appium handler or while processing
-   *                 the command by the GPTDriver.
-   *
-   * @example
-   * // Basic usage with natural language (no caching)
-   * await driver.aiExecute({
-   *   command: "Click the submit button"
-   * });
-   *
-   * @example
-   * // Full screen caching for repetitive navigation on similar screens
-   * await driver.aiExecute({
-   *   command: "Navigate to the settings page",
-   *   cachingMode: "FULL_SCREEN"
-   * });
-   *
-   * @example
-   * // Interaction region caching for repeated actions on the same button
-   * await driver.aiExecute({
-   *   command: "Click the login button",
-   *   cachingMode: "INTERACTION_REGION"
-   * });
-   *
-   * @example
-   * // With custom Appium handler as fallback
-   * await driver.aiExecute({
-   *   command: "Click the login button",
-   *   appiumHandler: async (driver) => {
-   *     const loginBtn = await driver.$('~loginButton');
-   *     await loginBtn.click();
-   *   },
-   *   cachingMode: "INTERACTION_REGION"
-   * });
-   *
-   * @example
-   * // Force fresh execution for dynamic content
-   * await driver.aiExecute({
-   *   command: "Verify the current timestamp",
-   *   cachingMode: "NONE"
-   * });
-   *
-   * @example
-   * // Using smart loop for optimized caching
-   * await driver.aiExecute({
-   *   command: "Click the login button",
-   *   useSmartLoop: true,
-   *   cachingMode: "FULL_SCREEN"
-   * });
-   */
-  async aiExecute({ command, appiumHandler, cachingMode, useSmartLoop = false }) {
+  async aiExecute(commandOrOptions, options) {
+    const command = typeof commandOrOptions === "string" ? commandOrOptions : commandOrOptions.command;
+    const opts = typeof commandOrOptions === "string" ? options : commandOrOptions;
+    const appiumHandler = opts?.appiumHandler;
+    const cachingMode = opts?.cachingMode;
+    const useSmartLoop = opts?.useSmartLoop ?? false;
     if (!this.appiumSessionStarted) {
       await this.startSession();
     }
@@ -1337,9 +1273,42 @@ class GptDriver {
    */
   async executeFlow(filePath, options) {
     const useSmartLoop = options?.useSmartLoop ?? false;
+    const configFilePath = this.configFilePath;
+    let baseDir;
+    let absolutePath;
+    if (configFilePath) {
+      let raw2;
+      try {
+        raw2 = await node_fs.promises.readFile(configFilePath, "utf-8");
+      } catch (e) {
+        const msg = `Failed to read file at ${configFilePath}: ${e?.message ?? e}`;
+        globalLogger.error(msg);
+        throw new Error(msg);
+      }
+      let json2;
+      try {
+        json2 = JSON.parse(raw2);
+      } catch (e) {
+        const msg = `Invalid JSON in flow file ${configFilePath}: ${e?.message ?? e}`;
+        globalLogger.error(msg);
+        throw new Error(msg);
+      }
+      const parsedConfigFile = ConfigSchema.parse(json2);
+      if (path.isAbsolute(parsedConfigFile.testDir)) {
+        baseDir = parsedConfigFile.testDir;
+      } else {
+        baseDir = path.resolve(path.dirname(configFilePath), parsedConfigFile.testDir);
+      }
+      absolutePath = path.isAbsolute(filePath) ? filePath : path.resolve(baseDir, filePath);
+    } else {
+      if (useSmartLoop) {
+        throw new Error("Config file is required when using SmartLoop, please provide the path in the constructor");
+      } else {
+        absolutePath = path.resolve(filePath);
+        baseDir = path.dirname(absolutePath);
+      }
+    }
     globalLogger.info(`Loading flow from file: ${filePath}`);
-    const absolutePath = path.resolve(filePath);
-    const baseDir = path.dirname(absolutePath);
     let raw;
     try {
       raw = await node_fs.promises.readFile(absolutePath, "utf-8");
@@ -1578,10 +1547,7 @@ ${issues}`);
         for (const appiumCommand of executeResponse.commands) {
           await this.executeCommand(appiumCommand);
         }
-        if (!conditionSucceeded) {
-          globalLogger.debug("Command still in progress, waiting...");
-          await delay(1500);
-        }
+        await delay(1500);
       }
       this.step_number = this.step_number + 1;
       globalLogger.info("Command execution completed successfully");
@@ -1594,8 +1560,7 @@ ${issues}`);
   async executeCommand(command) {
     const firstAction = command.data?.actions?.at(0);
     if (firstAction?.type === "pause" && firstAction.duration != null) {
-      globalLogger.debug(`Pausing for ${firstAction.duration} seconds`);
-      await delay(firstAction * 1e3);
+      await delay(firstAction.duration * 1e3);
     } else if (!this.useGptDriverCloud) {
       const parsedUrl = new URL(command.url);
       parsedUrl.protocol = this.appiumSessionConfig.serverUrl.protocol;

package/dist/index.d.cts

@@ -14,7 +14,6 @@ interface ServerSessionInitConfig {
 interface GptDriverConfig {
     testId?: string;
     apiKey: string;
-    organisationId?: string;
     driver?: WebDriver | Browser;
     serverConfig: {
         device?: ServerSessionInitConfig;
@@ -23,6 +22,8 @@ interface GptDriverConfig {
     useGptDriverCloud?: boolean;
     buildId?: string;
     cachingMode?: CachingMode;
+    organisationId?: string;
+    configFilePath?: string;
 }
 /**
  * Parameters for opening a deep link url in the Appium session.
@@ -386,7 +387,6 @@ type SavableTestStore = z.infer<typeof SavableTestStoreSchema>;
 declare class GptDriver {
     private interpolateTemplate;
     private apiKey;
-    private organisationId?;
     private gptDriverSessionId?;
     private gptDriverBaseUrl;
     private appiumSessionConfig?;
@@ -398,6 +398,8 @@ declare class GptDriver {
     private buildId?;
     private testId?;
     private step_number;
+    private organisationId?;
+    private configFilePath?;
     private globalActionHistory;
     /**
      * Creates an instance of the GptDriver class.
@@ -495,22 +497,26 @@ declare class GptDriver {
      * on the GPTDriver servers. If the handler execution fails or no handler is provided, the command
      * gets executed by the GPTDriver using natural language processing.
      *
-     * @param {Object} params - The execution parameters
-     * @param {string} params.command - The natural language command to be executed by the GPTDriver.
-     *                                  Examples: "Click the login button", "Enter 'test@example.com' in the email field"
-     * @param {AppiumHandler} [params.appiumHandler] - An optional function that processes Appium-specific commands.
+     * @param {string | Object} commandOrOptions - Either a command string or an options object
+     * @param {string} commandOrOptions.command - The natural language command to be executed by the GPTDriver.
+     *                                            Examples: "Click the login button", "Enter 'test@example.com' in the email field"
+     * @param {AppiumHandler} [commandOrOptions.appiumHandler] - An optional function that processes Appium-specific commands.
+     * @param {CachingMode} [commandOrOptions.cachingMode] - Controls how the GPTDriver caches this command execution.
+     * @param {boolean} [commandOrOptions.useSmartLoop] - If true, uses the smart loop execution. Default: false
+     * @param {Object} [options] - Additional options when first parameter is a command string
+     * @param {AppiumHandler} [options.appiumHandler] - An optional function that processes Appium-specific commands.
      *                                                  If provided, this handler is executed instead of calling
      *                                                  the GPTDriver API. Useful for performance optimization when
      *                                                  you know the exact Appium commands to execute.
-     * @param {CachingMode} [params.cachingMode] - Controls how the GPTDriver caches this command execution.
-     *                                             If not specified, uses the global caching mode set in the constructor.
-     *                                             Options:
-     *                                             - "NONE"
-     *                                             - "FULL_SCREEN"
-     *                                             - "INTERACTION_REGION"
-     * @param {boolean} [params.useSmartLoop] - If true, uses the smart loop execution (Cache -> AI -> Execute -> Populate)
-     *                                          which optimizes execution by checking cache first and populating it after.
-     *                                          Default: false (uses legacy gptHandler)
+     * @param {CachingMode} [options.cachingMode] - Controls how the GPTDriver caches this command execution.
+     *                                              If not specified, uses the global caching mode set in the constructor.
+     *                                              Options:
+     *                                              - "NONE"
+     *                                              - "FULL_SCREEN"
+     *                                              - "INTERACTION_REGION"
+     * @param {boolean} [options.useSmartLoop] - If true, uses the smart loop execution (Cache -> AI -> Execute -> Populate)
+     *                                           which optimizes execution by checking cache first and populating it after.
+     *                                           Default: false (uses legacy gptHandler)
      *
      * @returns {Promise<void>} A promise that resolves when the command execution is complete.
      *
@@ -518,27 +524,30 @@ declare class GptDriver {
      *                 the command by the GPTDriver.
      *
      * @example
-     * // Basic usage with natural language (no caching)
+     * // Basic usage with command string
+     * await driver.aiExecute("Click the submit button");
+     *
+     * @example
+     * // Basic usage with options object
      * await driver.aiExecute({
      *   command: "Click the submit button"
      * });
      *
      * @example
-     * // Full screen caching for repetitive navigation on similar screens
-     * await driver.aiExecute({
-     *   command: "Navigate to the settings page",
+     * // Command string with options
+     * await driver.aiExecute("Navigate to settings", {
      *   cachingMode: "FULL_SCREEN"
      * });
      *
      * @example
-     * // Interaction region caching for repeated actions on the same button
+     * // Full screen caching using options object
      * await driver.aiExecute({
-     *   command: "Click the login button",
-     *   cachingMode: "INTERACTION_REGION"
+     *   command: "Navigate to the settings page",
+     *   cachingMode: "FULL_SCREEN"
      * });
      *
      * @example
-     * // With custom Appium handler as fallback
+     * // With custom Appium handler
      * await driver.aiExecute({
      *   command: "Click the login button",
      *   appiumHandler: async (driver) => {
@@ -549,13 +558,6 @@ declare class GptDriver {
      * });
      *
      * @example
-     * // Force fresh execution for dynamic content
-     * await driver.aiExecute({
-     *   command: "Verify the current timestamp",
-     *   cachingMode: "NONE"
-     * });
-     *
-     * @example
      * // Using smart loop for optimized caching
      * await driver.aiExecute({
      *   command: "Click the login button",
@@ -563,12 +565,17 @@ declare class GptDriver {
      *   cachingMode: "FULL_SCREEN"
      * });
      */
-    aiExecute({ command, appiumHandler, cachingMode, useSmartLoop }: {
+    aiExecute(options: {
         command: string;
         appiumHandler?: AppiumHandler;
         cachingMode?: CachingMode;
         useSmartLoop?: boolean;
     }): Promise<void>;
+    aiExecute(command: string, options?: {
+        appiumHandler?: AppiumHandler;
+        cachingMode?: CachingMode;
+        useSmartLoop?: boolean;
+    }): Promise<void>;
     /**
      * Asserts a single condition using the GPTDriver.
      *

package/dist/index.mjs

@@ -158,6 +158,14 @@ const SavableTestStoreSchema = z.object({
   steps: z.array(SavableStepSchema),
   params: z.record(z.string(), z.string()).optional()
 });
+const VariablesSchema = z.record(z.string(), z.string()).optional().default({});
+const ConfigSchema = z.object({
+  testDir: z.string(),
+  driver: z.string(),
+  port: z.number(),
+  apiKey: z.string(),
+  variables: VariablesSchema
+});
 
 const CACHE_SERVER_URL = "https://cache.mobileboost.io";
 const GPT_DRIVER_BASE_URL = "https://api.mobileboost.io";
@@ -602,7 +610,6 @@ class GptDriver {
     });
   }
   apiKey;
-  organisationId;
   gptDriverSessionId;
   gptDriverBaseUrl;
   appiumSessionConfig;
@@ -614,6 +621,8 @@ class GptDriver {
   buildId;
   testId;
   step_number = 1;
+  organisationId;
+  configFilePath;
   // Smart loop state - maintains action history across steps for context
   globalActionHistory = [];
   /**
@@ -638,11 +647,12 @@ class GptDriver {
   constructor(config) {
     this.testId = config.testId;
     this.apiKey = config.apiKey;
-    this.organisationId = config.organisationId;
     this.buildId = config.buildId;
     this.useGptDriverCloud = config.useGptDriverCloud;
     this.gptDriverBaseUrl = GPT_DRIVER_BASE_URL;
     this.cachingMode = config.cachingMode ?? "NONE";
+    this.organisationId = config.organisationId;
+    this.configFilePath = config.configFilePath;
     if (config.useGptDriverCloud) {
       if (config.serverConfig.device?.platform == null) {
         throw new Error("Platform is missing. Please specify the platform when using GPTDriver Cloud.");
@@ -1003,86 +1013,12 @@ class GptDriver {
       await this.gptHandler(command);
     }
   }
-  /**
-   * Executes a specified command within the WebDriver session with configurable caching options.
-   *
-   * This is the recommended method for executing commands. It provides fine-grained control over
-   * caching behavior, allowing you to optimize performance and costs for repetitive test scenarios.
-   *
-   * If an `appiumHandler` is provided, it will be invoked with the WebDriver instance to perform
-   * the command-specific operations. After executing the handler, the executed commands get logged
-   * on the GPTDriver servers. If the handler execution fails or no handler is provided, the command
-   * gets executed by the GPTDriver using natural language processing.
-   *
-   * @param {Object} params - The execution parameters
-   * @param {string} params.command - The natural language command to be executed by the GPTDriver.
-   *                                  Examples: "Click the login button", "Enter 'test@example.com' in the email field"
-   * @param {AppiumHandler} [params.appiumHandler] - An optional function that processes Appium-specific commands.
-   *                                                  If provided, this handler is executed instead of calling
-   *                                                  the GPTDriver API. Useful for performance optimization when
-   *                                                  you know the exact Appium commands to execute.
-   * @param {CachingMode} [params.cachingMode] - Controls how the GPTDriver caches this command execution.
-   *                                             If not specified, uses the global caching mode set in the constructor.
-   *                                             Options:
-   *                                             - "NONE"
-   *                                             - "FULL_SCREEN"
-   *                                             - "INTERACTION_REGION"
-   * @param {boolean} [params.useSmartLoop] - If true, uses the smart loop execution (Cache -> AI -> Execute -> Populate)
-   *                                          which optimizes execution by checking cache first and populating it after.
-   *                                          Default: false (uses legacy gptHandler)
-   *
-   * @returns {Promise<void>} A promise that resolves when the command execution is complete.
-   *
-   * @throws {Error} If an error occurs during the execution of the Appium handler or while processing
-   *                 the command by the GPTDriver.
-   *
-   * @example
-   * // Basic usage with natural language (no caching)
-   * await driver.aiExecute({
-   *   command: "Click the submit button"
-   * });
-   *
-   * @example
-   * // Full screen caching for repetitive navigation on similar screens
-   * await driver.aiExecute({
-   *   command: "Navigate to the settings page",
-   *   cachingMode: "FULL_SCREEN"
-   * });
-   *
-   * @example
-   * // Interaction region caching for repeated actions on the same button
-   * await driver.aiExecute({
-   *   command: "Click the login button",
-   *   cachingMode: "INTERACTION_REGION"
-   * });
-   *
-   * @example
-   * // With custom Appium handler as fallback
-   * await driver.aiExecute({
-   *   command: "Click the login button",
-   *   appiumHandler: async (driver) => {
-   *     const loginBtn = await driver.$('~loginButton');
-   *     await loginBtn.click();
-   *   },
-   *   cachingMode: "INTERACTION_REGION"
-   * });
-   *
-   * @example
-   * // Force fresh execution for dynamic content
-   * await driver.aiExecute({
-   *   command: "Verify the current timestamp",
-   *   cachingMode: "NONE"
-   * });
-   *
-   * @example
-   * // Using smart loop for optimized caching
-   * await driver.aiExecute({
-   *   command: "Click the login button",
-   *   useSmartLoop: true,
-   *   cachingMode: "FULL_SCREEN"
-   * });
-   */
-  async aiExecute({ command, appiumHandler, cachingMode, useSmartLoop = false }) {
+  async aiExecute(commandOrOptions, options) {
+    const command = typeof commandOrOptions === "string" ? commandOrOptions : commandOrOptions.command;
+    const opts = typeof commandOrOptions === "string" ? options : commandOrOptions;
+    const appiumHandler = opts?.appiumHandler;
+    const cachingMode = opts?.cachingMode;
+    const useSmartLoop = opts?.useSmartLoop ?? false;
     if (!this.appiumSessionStarted) {
       await this.startSession();
     }
@@ -1335,9 +1271,42 @@ class GptDriver {
    */
   async executeFlow(filePath, options) {
     const useSmartLoop = options?.useSmartLoop ?? false;
+    const configFilePath = this.configFilePath;
+    let baseDir;
+    let absolutePath;
+    if (configFilePath) {
+      let raw2;
+      try {
+        raw2 = await promises.readFile(configFilePath, "utf-8");
+      } catch (e) {
+        const msg = `Failed to read file at ${configFilePath}: ${e?.message ?? e}`;
+        globalLogger.error(msg);
+        throw new Error(msg);
+      }
+      let json2;
+      try {
+        json2 = JSON.parse(raw2);
+      } catch (e) {
+        const msg = `Invalid JSON in flow file ${configFilePath}: ${e?.message ?? e}`;
+        globalLogger.error(msg);
+        throw new Error(msg);
+      }
+      const parsedConfigFile = ConfigSchema.parse(json2);
+      if (path.isAbsolute(parsedConfigFile.testDir)) {
+        baseDir = parsedConfigFile.testDir;
+      } else {
+        baseDir = path.resolve(path.dirname(configFilePath), parsedConfigFile.testDir);
+      }
+      absolutePath = path.isAbsolute(filePath) ? filePath : path.resolve(baseDir, filePath);
+    } else {
+      if (useSmartLoop) {
+        throw new Error("Config file is required when using SmartLoop, please provide the path in the constructor");
+      } else {
+        absolutePath = path.resolve(filePath);
+        baseDir = path.dirname(absolutePath);
+      }
+    }
     globalLogger.info(`Loading flow from file: ${filePath}`);
-    const absolutePath = path.resolve(filePath);
-    const baseDir = path.dirname(absolutePath);
     let raw;
     try {
       raw = await promises.readFile(absolutePath, "utf-8");
@@ -1576,10 +1545,7 @@ ${issues}`);
         for (const appiumCommand of executeResponse.commands) {
           await this.executeCommand(appiumCommand);
         }
-        if (!conditionSucceeded) {
-          globalLogger.debug("Command still in progress, waiting...");
-          await delay(1500);
-        }
+        await delay(1500);
       }
       this.step_number = this.step_number + 1;
       globalLogger.info("Command execution completed successfully");
@@ -1592,8 +1558,7 @@ ${issues}`);
   async executeCommand(command) {
     const firstAction = command.data?.actions?.at(0);
     if (firstAction?.type === "pause" && firstAction.duration != null) {
-      globalLogger.debug(`Pausing for ${firstAction.duration} seconds`);
-      await delay(firstAction * 1e3);
+      await delay(firstAction.duration * 1e3);
     } else if (!this.useGptDriverCloud) {
       const parsedUrl = new URL(command.url);
       parsedUrl.protocol = this.appiumSessionConfig.serverUrl.protocol;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gpt-driver-node",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.cts",