@skyramp/skyramp 1.2.20 → 1.2.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyramp/skyramp",
-  "version": "1.2.20",
+  "version": "1.2.22",
   "description": "module for leveraging skyramp cli functionality",
   "scripts": {
     "lint": "eslint 'src/**/*.js' 'src/**/*.ts' --fix",
@@ -17,6 +17,7 @@
     "src/classes/*.ts"
   ],
   "main": "src/index.js",
+  "types": "src/index.d.ts",
   "author": "",
   "license": "MIT",
   "dependencies": {
@@ -30,4 +31,4 @@
     "@typescript-eslint/parser": "^6.14.0",
     "eslint": "^8.55.0"
   }
-}
+}

package/src/classes/SkyrampClient.d.ts

@@ -1,16 +1,16 @@
-import { ResponseValue } from '..';
-import { Endpoint } from './Endpoint';
-import { Scenario } from './Scenario';
-import {TrafficConfig} from './TrafficConfig';
-import { Protocol } from './Protocol';
-import { AsyncScenario } from './AsyncScenario';
-import { LoadTestConfig } from './LoadTestConfig';
-import { AsyncTestStatus } from './AsyncTestStatus';
-import { MultipartParam } from './MultipartParam';
-import { MockV2 } from './MockV2';
+import { ResponseValue } from "..";
+import { Endpoint } from "./Endpoint";
+import { Scenario } from "./Scenario";
+import { TrafficConfig } from "./TrafficConfig";
+import { Protocol } from "./Protocol";
+import { AsyncScenario } from "./AsyncScenario";
+import { LoadTestConfig } from "./LoadTestConfig";
+import AsyncTestStatus = require("./AsyncTestStatus");
+import { MultipartParam } from "./MultipartParam";
+import { MockV2 } from "./MockV2";
 
 export enum Language {
-  PYTHON = 'python'
+  PYTHON = "python",
 }
 
 interface testerStartV1Options {
@@ -21,8 +21,8 @@ interface testerStartV1Options {
   address?: string;
   scenario: Scenario | [Scenario];
   testName: string;
-  globalHeaders?: {[headerName: string]: string};
-  globalVars?: {[variableName: string]: string};
+  globalHeaders?: { [headerName: string]: string };
+  globalVars?: { [variableName: string]: string };
   generateTestReport?: boolean;
   isDockerenv?: boolean;
 }
@@ -40,12 +40,20 @@ interface SendRequestV2Options {
   path: string;
   method: string;
   body?: string;
-  headers?: {[headerName: string]: string};
-  cookies?: {[cookieName: string]: string};
-  dataOverride?: {[dataName: string]: string | number | boolean | object | null};
-  pathParams?: {[pathName: string]: string | number | boolean | object | null};
-  queryParams?: {[queryName: string]: string | number | boolean | object | null};
-  formParams?: {[formParamName: string]: string | number | boolean | object | null};
+  headers?: { [headerName: string]: string };
+  cookies?: { [cookieName: string]: string };
+  dataOverride?: {
+    [dataName: string]: string | number | boolean | object | null;
+  };
+  pathParams?: {
+    [pathName: string]: string | number | boolean | object | null;
+  };
+  queryParams?: {
+    [queryName: string]: string | number | boolean | object | null;
+  };
+  formParams?: {
+    [formParamName: string]: string | number | boolean | object | null;
+  };
   multipartParams?: Array<MultipartParam>;
   expectedCode?: string;
   description?: string;
@@ -136,36 +144,97 @@ interface SendScenarioOptions {
 }
 
 export declare class SkyrampClient {
-  constructor(kubeconfigPath?: string, clusterName?: string, context?: string, userToken?: string);
+  constructor(
+    kubeconfigPath?: string,
+    clusterName?: string,
+    context?: string,
+    userToken?: string
+  );
   constructor(options: SkyrampClientOptions);
   login(): Promise<string>;
   logout(): Promise<string>;
   applyLocal(): Promise<void>;
-  addKubeconfig(context: string, clusterName: string, kubeconfigPath: string): Promise<void>;
+  addKubeconfig(
+    context: string,
+    clusterName: string,
+    kubeconfigPath: string
+  ): Promise<void>;
   removeLocal(): Promise<void>;
   removeCluster(clusterName?: string): Promise<void>;
-  mockerApply(namespace: string, kubePath: string, kubeContext: string, clusterName: string, address: string, endpoint: Endpoint): Promise<void>;
-  deploySkyrampWorker(namespace?: string, workerImage?: string, localImage?: boolean, kubePath?: string, kubeContext?: string, clusterName?: string): Promise<void>
-  deleteSkyrampWorker(namespace?: string, kubePath:string, kubeContext?: string, clusterName?: string): Promise<void>
-  runDockerSkyrampWorker(workerImage?:string, workerTag?:string, hostPost?:int, targetNetworkName?:string): Promise<void>
-  removeDockerSkyrampWorker() : Promise<void>
+  mockerApply(
+    namespace: string,
+    kubePath: string,
+    kubeContext: string,
+    clusterName: string,
+    address: string,
+    endpoint: Endpoint
+  ): Promise<void>;
+  deploySkyrampWorker(
+    namespace?: string,
+    workerImage?: string,
+    localImage?: boolean,
+    kubePath?: string,
+    kubeContext?: string,
+    clusterName?: string
+  ): Promise<void>;
+  deleteSkyrampWorker(
+    namespace?: string,
+    kubePath?: string,
+    kubeContext?: string,
+    clusterName?: string
+  ): Promise<void>;
+  runDockerSkyrampWorker(
+    workerImage?: string,
+    workerTag?: string,
+    hostPost?: number,
+    targetNetworkName?: string
+  ): Promise<void>;
+  removeDockerSkyrampWorker(): Promise<void>;
   mockerApplyV1(options: MockerApplyV1Options): Promise<void>;
-  mockerApplyV1(namespace: string, kubePath: string, kubeContext: string, clusterName: string, address: string, response: ResponseValue | ResponseValue[], trafficConfig: TrafficConfig): Promise<void>;
-  mockerApplyFromFile(namespace: string, kubePath: string, kubeContext: string, clusterName: string, address: string, filePath: string): Promise<void>;
-  applyMockDescription(namespace: string, address: string, mockYamlContent: string): Promise<void>;
+  mockerApplyV1(
+    namespace: string,
+    kubePath: string,
+    kubeContext: string,
+    clusterName: string,
+    address: string,
+    response: ResponseValue | ResponseValue[],
+    trafficConfig: TrafficConfig
+  ): Promise<void>;
+  mockerApplyFromFile(
+    namespace: string,
+    kubePath: string,
+    kubeContext: string,
+    clusterName: string,
+    address: string,
+    filePath: string
+  ): Promise<void>;
+  applyMockDescription(
+    namespace: string,
+    address: string,
+    mockYamlContent: string
+  ): Promise<void>;
   applyMock(mock: MockV2 | MockV2[]): Promise<void>;
-  testerStart(namespace: string, kubePath: string, kubeContext: string, clusterName: string, address: string, scenario: Scenario): Promise<void>;
-  testerStartV1(namespace: string,
+  testerStart(
+    namespace: string,
+    kubePath: string,
+    kubeContext: string,
+    clusterName: string,
+    address: string,
+    scenario: Scenario
+  ): Promise<void>;
+  testerStartV1(
+    namespace: string,
     kubePath: string,
     kubeContext: string,
     clusterName: string,
     address: string,
     scenario: Scenario,
     testName: string,
-    globalHeaders: {[headerName: string]: string},
+    globalHeaders: { [headerName: string]: string },
     generateTestReport: boolean,
-    isDockerenv: boolean): Promise<void>;
-  
+    isDockerenv: boolean
+  ): Promise<void>;
+
   testerStartV1(options: testerStartV1Options): Promise<void>;
 
   testerGenerate(
@@ -179,9 +248,10 @@ export declare class SkyrampClient {
     port: int,
     generateRobot: boolean,
     functionalScenario: boolean,
-    negativeScenario: boolean): Promise<string[]>; 
+    negativeScenario: boolean
+  ): Promise<string[]>;
 
-  sendRequest(options: SendRequestV2Options): Promise<void>;
+  sendRequest(options: SendRequestV2Options): Promise<ResponseV2>;
   deployDashboard(network: string): Promise<void>;
 
   generateRestTest(options: GenerateRestTestOptions): Promise<string>;
@@ -193,5 +263,8 @@ export declare class SkyrampClient {
    * @param scenario The scenario object or array of scenarios to run
    * @param options Additional options for the load test
    */
-  sendScenario(scenario: AsyncScenario | AsyncScenario[], options?: SendScenarioOptions): Promise<AsyncTestStatus>;
+  sendScenario(
+    scenario: AsyncScenario | AsyncScenario[],
+    options?: SendScenarioOptions
+  ): Promise<AsyncTestStatus>;
 }

package/src/classes/SmartPlaywright.d.ts

@@ -1,2 +1,5 @@
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function newSkyrampPlaywrightPage(page: any): any;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function expect(obj: any): any;

package/src/classes/SmartPlaywright.js

@@ -1,4 +1,4 @@
-/*
+const { expect: playwrightExpect } = require('@playwright/test');
 const lib = require('../lib');
 const koffi = require('koffi');
 
@@ -8,6 +8,9 @@ const responseType = koffi.struct({
 });
 
 const improvePlaywrightSelectorWrapper = lib.func('improvePlywrightSelectorWrapper', responseType, ['string']);
+const hasJavascriptWrapper = lib.func('hasJavascript', 'bool', ['string']);
+
+const defaultWaitForTimeout = 1500
 
 async function improvePlaywrightSelectorWithLlm(originalSelector, errorMessage, domContext, pageTitle, pageURL) {
     const requestData = {
@@ -15,7 +18,8 @@ async function improvePlaywrightSelectorWithLlm(originalSelector, errorMessage,
         "error_message": errorMessage,
         "dom_context": domContext,
         "page_title": pageTitle,
-        "page_url": pageURL
+        "page_url": pageURL,
+        "language": "javascript"
     };
     const request = JSON.stringify(requestData);
 
@@ -38,7 +42,6 @@ async function improvePlaywrightSelectorWithLlm(originalSelector, errorMessage,
         });
     });
 }
-*/
 
 function debug(...args) {
     if (process.env.SKYRAMP_DEBUG == "true") {
@@ -46,6 +49,165 @@ function debug(...args) {
     }
 }
 
+function shouldAttemptImprovement(errorMessage, errorName) {
+    const improvementKeywords = [
+        "timeout",
+        "not found",
+        "no element",
+        "not visible",
+        "not attached",
+        "selector resolved to hidden",
+        "element is not enabled",
+        "strict mode violation"
+    ];
+
+    if (errorName != "") {
+        const playwrightErrorTypes = [
+            "TimeoutError",
+            "Error",
+            "LocatorAssertionError"
+        ];
+        if (playwrightErrorTypes.some(e => e == errorName)) {
+            return true;
+        }
+    }
+
+    let errorLower = errorMessage.toLowerCase();
+    return improvementKeywords.some(keyword => errorLower.includes(keyword));
+}
+
+// for debugging only
+/*
+const sampleSuggestions = [
+  {
+    selector: "page.getByText('K', { exact: true})",
+    confidence: 0.9,
+    reasoning: "The 'L' appears to be within a user profile button that shows 'K' as the user initial, using semantic role for better reliability"
+  },
+  {
+    selector: "page.locator('#onyx-user-dropdown')",
+    confidence: 0.85,
+    reasoning: 'Targets the specific user dropdown container with unique ID that contains the user initial'
+  },
+  {
+    selector: "page.locator('.bg-background-900').filter({ hasText: 'K' })",
+    confidence: 0.8,
+    reasoning: 'Targets the specific styled element containing the user initial with background class'
+  },
+  {
+    selector: "page.locator('div').filter({ hasText: /^K$/ }).nth(0)",
+    confidence: 0.75,
+    reasoning: "Uses regex to find exact 'K' text match and takes first occurrence"
+  },
+  {
+    selector: "page.getByText('kolja').locator('..').getByText('K', { exact: true })",
+    confidence: 0.7,
+    reasoning: "Navigates to parent of username text and finds the exact 'K' text within that context"
+  }
+]
+*/
+
+function parseErrorStack(ori) {
+    const stackLines = ori.split('\n');
+    let prev = ""
+    for (let idx = stackLines.length - 1; idx >= 0 ; idx --) {
+        // this could be improved
+        if (stackLines[idx].includes("@skyramp/skyramp")) {
+            break;
+        }
+        prev = stackLines[idx];
+    }
+    return prev
+}
+
+async function retryWithLLM(skyrampLocator, error) {
+    // when API_KEY is not given, we return right away
+    if (!process.env.API_KEY) {
+        throw error
+    }
+
+    let errorMessage = error.toString();
+    let errorType = typeof error;
+
+    if (!(skyrampLocator instanceof SkyrampPlaywrightLocator)) {
+        throw error
+    }
+
+    let locatorStr = skyrampLocator._locator.toString();
+
+    if (!shouldAttemptImprovement(errorMessage, errorType)) {
+        debug("cannot improve", error.name);
+        throw error
+    }
+
+    let pageTitle = await skyrampLocator.page().title();
+    let pageUrl = skyrampLocator.page().url();
+
+    debug("retry with LLM", skyrampLocator._locator);
+
+    let newMsg = `${errorMessage} (while using selector: ${locatorStr})`;
+
+    let pageContent = await skyrampLocator.page().content();
+
+    // for debugging only
+    // let suggestions = sampleSuggestions;
+
+    var suggestions;
+    try {
+        suggestions = await improvePlaywrightSelectorWithLlm(
+            locatorStr,
+            newMsg,
+            pageContent,
+            pageTitle,
+            pageUrl
+        );
+    } catch (error) {
+        debug("failed to consult with llm", error)
+        throw error
+    }
+
+    if (suggestions == null || suggestions.length == 0) {
+        debug("No LLM suggestoins available, failing with original error");
+        throw error;
+    }
+
+    suggestions.sort((a, b) => (b.confidence ?? 0) - (a.confidence ?? 0))
+    debug(suggestions)
+
+    for (let suggestion of suggestions) {
+        debug(`try ${suggestion.selector} instead of ${skyrampLocator._locator}`);
+        try {
+            const newLocator = skyrampLocator.createLocatorFromString(suggestion.selector);
+            if (newLocator == null) {
+                continue
+            }
+
+            const locatorCount = await newLocator.count();
+
+            debug(` trying new Locator ${newLocator}, count = ${locatorCount}`);
+
+            if (locatorCount == 1) {
+                const func = newLocator[skyrampLocator.execFname];
+                return func.call(newLocator, skyrampLocator.execParam, skyrampLocator.execArgs).then(result => {
+                    console.log(`✅ SUCCESS! Used selector: ${newLocator} instead of ${skyrampLocator._locator}`);
+                    console.log(`  ${parseErrorStack(error.stack)}`);
+
+                    skyrampLocator.llmLocator = newLocator;
+                    skyrampLocator.locatorCount = 1;
+                    skyrampLocator._skyrampPage.addLLMChoices(skyrampLocator._locator, newLocator, error.stack);
+                    return result;
+                }).catch(error => {
+                    throw new Error(`retrying with LLM failed at ${skyrampLocator._locator} replacing ${newLocator}`, error);
+                });
+            }
+        } catch {
+            continue
+        }
+    }
+
+    throw new Error(`failed to find a working locator from LLM's suggestions`, error);
+}
+
 class SkyrampPlaywrightLocator {
     constructor(skyrampPage, locator, prevLocator, args, options, hydration) {
         this._skyrampPage = skyrampPage
@@ -83,49 +245,29 @@ class SkyrampPlaywrightLocator {
         return this._previousLocator && this._previousLocator.isHydration()
     }
 
-    shouldAttemptImprovement(errorMessage, errorType) {
-        const improvementKeywords = [
-            "timeout",
-            "not found",
-            "no element",
-            "not visible",
-            "not attached",
-            "selector resolved to hidden",
-            "element is not enabled",
-        ];
-
-        if (errorType != null) {
-            const playwrightErrorTypes = [
-                "TimeoutError",
-                "Error",
-                "LocatorAssertionError"
-            ];
-            if (playwrightErrorTypes.some(errType => errorType.name.endsWith(errType))) {
-                return true;
-            }
-        }
-
-        let errorLower = errorMessage.toLowerCase();
-        return improvementKeywords.some(keyword => errorLower.includes(keyword));
-    }
-
-    isSelectorMethod(methodName) {
-        // Check if a method uses selectors that can be improved.
-        const selectorMethods = [
-            'click', 'fill', 'type', 'press', 'check', 'uncheck', 'select_option',
-            'hover', 'focus', 'blur', 'scroll_into_view_if_needed', 'screenshot',
-            'text_content', 'inner_text', 'inner_html', 'get_attribute', 'is_visible',
-            'is_enabled', 'is_checked', 'is_disabled', 'is_editable', 'is_hidden'
-        ]
-        return selectorMethods.includes(methodName)
-    }
-
     async execute() {
-        debug(`execute ${ this._locator} with ${this.execParam} ${this.execArgs}`)
+        debug(`execute ${ this._locator}.${this.execFname} ${this.execParam ?? ''} ${this.execArgs ?? ''}`)
         const func = this._locator[this.execFname];
         return func.call(this._locator, this.execParam, this.execArgs);
     }
 
+    generateLLMErrors() {
+        let ret = "List of dynamic selectors that could be relevant to error:\n"
+
+        let choices = this._skyrampPage.getLLMChoices();
+        if (choices ==undefined || choices.length == 0) {
+            return ""
+        }
+        for (let i = 0 ; i < choices.length; i ++) {
+            const choice = choices[i];
+            ret += `${ i+1 }. original locator: ${choice.original}\n`
+            ret += `   selected locator: ${choice.new}\n`
+            ret += `   ${choice.at}\n`
+        }
+
+        return ret;
+    }
+
     // this is the function that does smart selector retry
     async SmartRetryWithFallback(fname, param, ...args) {
         this.execFname = fname;
@@ -133,9 +275,12 @@ class SkyrampPlaywrightLocator {
         this.execArgs = args;
 
         let locatorCount = await this._locator.count();
-        debug(`handling ${ fname } of ${ this._locator }, count = ${ locatorCount }`)
+        debug(`handling ${ this._locator }.${ fname }, count = ${ locatorCount }`)
         this.locatorCount = locatorCount
 
+        let currentUrl = this._skyrampPage._page.url();
+        debug(`current url = ${currentUrl}`);
+
         // if locator exists, DOM is available
         if (locatorCount == 1) {
             // we try action, this will most likely succeed
@@ -143,50 +288,219 @@ class SkyrampPlaywrightLocator {
             return this.execute()
             .catch(error => {
                 if (error.name == "TimeoutError") {
-                    return this.execute()
-                        .catch(error => {
-                            throw new Error("Potential hydration. Please add enough waitForTimeout() or use hydration flag", error);
-                        });
+                    debug(`locator ${this._locator} exists, but execution failed, wait a bit and retry`)
+                    this.wait(defaultWaitForTimeout)
+
+                    return this.execute().catch(newError => {
+                        debug(`second attempt on ${this._locator} failed`)
+                        debug(newError)
+                        if (this._skyrampPage.hasLLMChoices()) {
+                            newError.message += this.generateLLMErrors();
+                            throw newError;
+                        } else {
+                            throw new Error("Potentially a hydration issue. Please add enough waitForTimeout()", error);
+                        }
+                    });
                 }
                 throw error;
             });
         } else if (locatorCount > 0) {
             // TODO
-            debug("multiple locators identified")
-            return this.execute();
+            debug(`multiple ${locatorCount} locators identified`)
+
+            if (locatorCount > 5) {
+                throw new Error(`${locatorCount} locators detected for ${this._locator}. Please add "data-testid" attribute for a more stable locator`);
+            }
+
+            return this.execute().then(result => {
+                return result;
+            }).catch(error => {
+                if (!process.env.API_KEY) {
+                    throw new Error(`${locatorCount} locators detected for ${this._locator}. Please add "data-testid" attribute for a more stable locator`, error)
+                }
+
+                console.log(`${locatorCount} locators found for ${this._locator}`)
+                // this is the palce where we consult with LLM
+                return retryWithLLM(this, error).then(result => {
+                    this.multiLocatorLLM = true;
+                    return result;
+                }).catch(newError => {
+                    if (this._skyrampPage.hasLLMChoices()) {
+                        newError.message += this.generateLLMErrors();
+                        throw newError;
+                    }
+                    throw new Error(`failed to find a good alternative for ${this._locator}. Please add "data-testid" attribute for a more stable locator`, newError);
+                });
+            });
         } else {
             // if locator does not exist, we need to consider two cases
             // one is if any actions that required hydration did not work
             // second, if locator id is not correct
-            try {
-                // check if last step has potential hydration 
-                if (this._previousLocator && (this.isPrevHydration() || this._previousLocator.locatorCount == 0)) {
-                    debug(`previous action ${this._previousLocator} is potentially associated with hydration`);
-                    // wait for a short time to finish hydration
-                    await this._skyrampPage._page.waitForTimeout(1500);
-                    // then re-execute the previous locator
-                    await this._previousLocator.execute();
+            // check if last step has potential hydration 
+            if (this._previousLocator && this._previousLocator.locatorCount == 0) {
+                debug(`previous action ${this._previousLocator._locator} is potentially associated with hydration`);
+                // wait for a short time to finish hydration
+                await this.wait(defaultWaitForTimeout);
+
+                const previousCount = await this._previousLocator.count();
+                debug(` re-execute the previous one ${this._previousLocator._locator}, previous Locator count = ${previousCount}`);
+
+                // re-execute the previous locator
+                await this._previousLocator.execute().catch(() => {
+                    // log the failure but continues to the current one
+                    debug(`failed to execute previous locator ${this._previousLocator._locator} again`);
+                });
+
+                try {
                     // then execute the current one
-                    return this.execute();
-                }  else {
-                    // previous action may not be associated with hydration
-                    // but we still try
-                    return this.execute();
+                    return await this.execute();
+                } catch (error) {
+                    if (error.name == "TimeoutError") {
+                        debug(`${this._locator} failed at first try. attempting again with some timeout`);
+                        // wait for some time and re execute
+                        await this.wait(defaultWaitForTimeout);
+
+                        return this.execute().catch(newError => {
+                            if (!process.env.API_KEY) {
+                                throw new Error(`Cannot find locator ${this._locator} and likely a hydration issue on ${this._previousLocator._locator}. Please add enough waitForTimeout()`, newError);
+                            }
+                            // retry with llm
+                            return retryWithLLM(this, newError).then(result => {
+                                this.singleLocatorLLM = true;
+                                return result;
+                            }).catch(newError2 => {
+                                if (this._skyrampPage.hasLLMChoices()) {
+                                    newError2.message += this.generateLLMErrors();
+                                    throw newError2;
+                                }
+                                throw new Error(`Failed to find a good alternative of ${this._locator}. Please add "data-testid" attribute for a more stable locator`, newError2);
+                            });
+                        });
+                    }
+                    throw error;
                 }
-            } catch (error) {
-                if (error.name == "TimeoutError") {
-                    return this.execute()
-                    .catch(error => {
-                        throw new Error("Potential hydration. Please add enough waitForTimeout() or use hydration flag", error);
-                    });
+            } else {
+                if (this._previousLocator && this._previousLocator.multiLocatorLLM) {
+                    debug(`${this._locator} locator count is zero, but previous locator was selected by LLM from many candidates`);
+                } else if (this._previousLocator && this._previousLocator.singleLocatorLLM) {
+                    debug(`${this._locator} locator count is zero, but previous locator was selected by LLM from zero candidate`);
                 } else {
-                    // TODO
+                    debug(`${this._locator} locator count is zero, but previous locator seems not related to hydration`);
+                }
+                // previous action may not be associated with hydration
+                // then we just try current locator. could be a locator with a wrong id
+                // wait for a short time just in case
+                await this.wait(defaultWaitForTimeout);
+
+                this.locatorCount = await this._locator.count();
+                debug(` after waiting locator count = ${this.locatorCount}, url = ${this._skyrampPage._page.url()}`);
+
+                try {
+                    return await this.execute();
+                } catch (error) {
+                    if (error.name == "TimeoutError") {
+                        debug(`${this._locator} failed at first try. attempting again with some timeout`);
+                        await this.wait(defaultWaitForTimeout);
+
+                        return this.execute().catch(newError => {
+                            if (newError.name == "TimeoutError") {
+                                if (!process.env.API_KEY) {
+                                    throw new Error(`Cannot find locator ${this._locator} and most likely not a hydration issue. Please add "data-testid" attribute for a more stable locator`, newError);
+                                }
+                                // retry with llm
+                                return retryWithLLM(this, newError).then(result => {
+                                    this.singleLocatorLLM = true;
+                                    return result;
+                                }).catch(newError2 => {
+                                    if (this._skyrampPage.hasLLMChoices()) {
+                                        newError2.message += this.generateLLMErrors();
+                                        throw newError2;
+                                    }
+                                    throw new Error(`Failed to find a good alternative of ${this._locator}. Please add "data-testid" attribute for a more stable locator`, newError2);
+                                });
+                            } else {
+                                throw newError;
+                            }
+                        });
+                    }
                     throw error;
                 }
             }
         }
     }
 
+    parseFunctionChain(chainStr) {
+        // Remove any object prefix like "page."
+        chainStr = chainStr.replace(/^[a-zA-Z_][a-zA-Z0-9_]*\./, '');
+
+        // Match function calls: funcName(args)
+        const regex = /([a-zA-Z_][a-zA-Z0-9_]*)\s*\(([^)]*)\)/g;
+        let result = [];
+        let match;
+        while ((match = regex.exec(chainStr)) !== null) {
+            const funcName = match[1];
+            const argsStr = match[2].trim();
+            let args = [];
+            if (argsStr.length > 0) {
+                // Split arguments by comma, but keep objects and strings together
+                // This is a simple approach, for more complex cases use a parser
+                let argMatches = [];
+                let depth = 0, current = '', inString = false, stringChar = '';
+                for (let i = 0; i < argsStr.length; i++) {
+                    const c = argsStr[i];
+                    if ((c === "'" || c === '"') && !inString) {
+                        inString = true;
+                        stringChar = c;
+                        current += c;
+                    } else if (inString && c === stringChar) {
+                        inString = false;
+                        current += c;
+                    } else if (!inString && (c === '{' || c === '[')) {
+                        depth++;
+                        current += c;
+                    } else if (!inString && (c === '}' || c === ']')) {
+                        depth--;
+                        current += c;
+                    } else if (!inString && c === ',' && depth === 0) {
+                        argMatches.push(current.trim());
+                        current = '';
+                    } else {
+                        current += c;
+                    }
+                }
+                if (current.trim().length > 0) {
+                    argMatches.push(current.trim());
+                }
+                args = argMatches;
+            }
+            result.push({ function: funcName, arguments: args });
+        }
+        return result;
+    }
+
+    createLocatorFromString(suggested) {
+        suggested = suggested.trim();
+        if (suggested.startsWith("page.")) {
+            suggested = suggested.substring(5);
+        }
+
+        let chains = this.parseFunctionChain(suggested);
+
+        let cur = this.page();
+        // find locator per function chain
+        for (let i = 0; i < chains.length; i ++) {
+            const chain = chains[i];
+            let f = cur[chain.function];
+            let args = [];
+            for (const a of chain.arguments) {
+                let arg = Function('"use strict";return (' + a + ')')();
+                args.push(arg);
+            }
+            cur = f.call(cur, ...args);
+        }
+        return cur;
+    }
+
     async click(...args) {
         return this.SmartRetryWithFallback("click", null, ...args);
     }
@@ -227,6 +541,55 @@ class SkyrampPlaywrightLocator {
         return this.SmartRetryWithFallback("isVisible", null, ...args);
     }
 
+    filter(options) {
+        const originalLocator = this._locator.filter(options);
+        return this._skyrampPage.newSkyrampPlaywrightLocator(originalLocator, null, options);
+    }
+
+    locator(selector, options) {
+        const originalLocator = this._locator.locator(selector, options);
+        return this._skyrampPage.newSkyrampPlaywrightLocator(originalLocator, selector, options);
+    }
+
+    getByRole(role, options) {
+        const originalLocator = this._locator.getByRole(role, options);
+        return this._skyrampPage.newSkyrampPlaywrightLocator(originalLocator, role, options);
+    }
+
+    getByText(text, options) {
+        const originalLocator = this._locator.getByText(text, options);
+        return this._skyrampPage.newSkyrampPlaywrightLocator(originalLocator, text, options);
+    }
+
+    getByLabel(label, options) {
+        const originalLocator = this._locator.getByLabel(label, options);
+        return this._skyrampPage.newSkyrampPlaywrightLocator(originalLocator, label, options);
+    }
+
+    getByTestId(testId, options) {
+        const originalLocator = this._locator.getByTestId(testId);
+        return this._skyrampPage.newSkyrampPlaywrightLocator(originalLocator, testId, options);
+    }
+
+    getByTitle(title, options) {
+        const originalLocator = this._locator.getByTitle(title, options);
+        return this._skyrampPage.newSkyrampPlaywrightLocator(originalLocator, title, options);
+    }
+
+    getByPlaceholder(placeholder, options) {
+        const originalLocator = this._locator.getByPlaceholder(placeholder, options);
+        return this._skyrampPage.newSkyrampPlaywrightLocator(originalLocator, placeholder, options);
+    }
+
+    getByAltText(alt, options) {
+        const originalLocator = this._locator.getByAltText(alt, options);
+        return this._skyrampPage.newSkyrampPlaywrightLocator(originalLocator, alt, options);
+    }
+
+    unwrap() {
+        return this._locator
+    }
+
     nth(index) {
         // get nth element - return a new SkyrampPlaywrightLocator
         let new_locator = this._locator.nth(index)
@@ -244,107 +607,173 @@ class SkyrampPlaywrightLocator {
         let new_locator = this._locator.last()
         return this._skyrampPage.newSkyrampPlaywrightLocator(new_locator, null, null);
     }
+
+    page() {
+        return this._skyrampPage._page;
+    }
+
+    async wait(t) {
+        debug(`wait for ${t}`);
+        return this._skyrampPage._page.waitForTimeout(t);
+    }
 }
 
 class SkyrampPlaywrightPage {
-  constructor(page) {
-    this._page = page;
-    return new Proxy(this, {
-      // The `get` trap is the key to forwarding.
-      // This will foraward any methods not implemented in this struct
-      // to be handled by the original class (i.e., playwright page object)
-      get(wrapper, prop, receiver) {
-        // First, check if the property exists on the wrapper.
-        if (Reflect.has(wrapper, prop)) {
-          return Reflect.get(wrapper, prop, receiver);
+    constructor(page) {
+        this._page = page;
+        this._curUrl = "";
+        return new Proxy(this, {
+            // The `get` trap is the key to forwarding.
+            // This will foraward any methods not implemented in this struct
+            // to be handled by the original class (i.e., playwright page object)
+            get(wrapper, prop, receiver) {
+                // First, check if the property exists on the wrapper.
+                if (Reflect.has(wrapper, prop)) {
+                    return Reflect.get(wrapper, prop, receiver);
+                }
+
+                // Otherwise, forward the call to the original object (`target`).
+                const value = Reflect.get(wrapper._page, prop, wrapper._page);
+
+                // If the property is a function, bind it to the original object.
+                // This ensures the correct `this` context is used when the method is called.
+                if (typeof value === 'function') {
+                    return value.bind(wrapper._page);
+                }
+
+                return value;
+            }
+        });
+    }
+
+    getCurUrl() {
+        return this._curUrl;
+    }
+
+    pushLocator(locator) {
+        if (this.locators == undefined ) {
+            this.locators = [];
         }
+        this.locators.push(locator);
+    }
 
-        // Otherwise, forward the call to the original object (`target`).
-        const value = Reflect.get(wrapper._page, prop, wrapper._page);
+    getLastLocator() {
+        if (this.locators == undefined) {
+            return null
+        }
 
-        // If the property is a function, bind it to the original object.
-        // This ensures the correct `this` context is used when the method is called.
-        if (typeof value === 'function') {
-          return value.bind(wrapper._page);
+        if (this.locators.length == 0) {
+            return null
         }
+        return this.locators.at(-1)
+    }
 
-        return value;
-      }
-    });
-  }
+    newSkyrampPlaywrightLocator(originalLocator, param, options) {
+        let prevLocator = this.getLastLocator();
+        const hydration = options && (options.hydration || false);
+        /*
+        if (prevLocator != null) {
+            debug(`handling ${originalLocator} prev ${prevLocator._locator}`);
+        } else {
+            debug(`handling ${originalLocator}`);
+        }
+        */
 
-  pushLocator(locator) {
-      if (this.locators == undefined ) {
-        this.locators = [];
-      }
-      this.locators.push(locator);
-  }
+        let newLocator = new SkyrampPlaywrightLocator(this, originalLocator, prevLocator, [param], options, hydration);
+        this.pushLocator(newLocator)
+        return newLocator
+    }
 
-  getLastLocator() {
-      if (this.locators == undefined) {
-          return null
-      }
+    locator(selector, options) {
+        const originalLocator = this._page.locator(selector, options);
+        return this.newSkyrampPlaywrightLocator(originalLocator, selector, options);
+    }
 
-      if (this.locators.length == 0) {
-          return null
-      }
-      return this.locators.at(-1)
-  }
+    getByRole(role, options) {
+        const originalLocator = this._page.getByRole(role, options);
+        return this.newSkyrampPlaywrightLocator(originalLocator, role, options);
+    }
 
-  newSkyrampPlaywrightLocator(originalLocator, param, options) {
-      let prevLocator = this.getLastLocator()
-      const hydration = options && (options.hydration || false)
-      debug("intercepting", originalLocator)
-      let newLocator = new SkyrampPlaywrightLocator(this, originalLocator, prevLocator, [param], options, hydration);
-      this.pushLocator(newLocator)
-      return newLocator
-  }
+    getByText(text, options) {
+        const originalLocator = this._page.getByText(text, options);
+        return this.newSkyrampPlaywrightLocator(originalLocator, text, options);
+    }
 
-  locator(selector, options) {
-      const originalLocator = this._page.locator(selector, options);
-      return this.newSkyrampPlaywrightLocator(originalLocator, selector, options)
-  }
+    getByLabel(label, options) {
+        const originalLocator = this._page.getByLabel(label, options);
+        return this.newSkyrampPlaywrightLocator(originalLocator, label, options);
+    }
 
-  getByRole(role, options) {
-      const originalLocator = this._page.getByRole(role, options);
-      return this.newSkyrampPlaywrightLocator(originalLocator, role, options)
-  }
+    getByTestId(testId, options) {
+        const originalLocator = this._page.getByTestId(testId);
+        return this.newSkyrampPlaywrightLocator(originalLocator, testId, options);
+    }
 
-  getByText(text, options) {
-      const originalLocator = this._page.getByText(text, options);
-      return this.newSkyrampPlaywrightLocator(originalLocator, text, options)
-  }
+    getByTitle(title, options) {
+        const originalLocator = this._page.getByTitle(title, options);
+        return this.newSkyrampPlaywrightLocator(originalLocator, title, options);
+    }
 
-  getByLabel(label, options) {
-      const originalLocator = this._page.getByLabel(label, options);
-      return this.newSkyrampPlaywrightLocator(originalLocator, label, options)
-  }
+    getByPlaceholder(placeholder, options) {
+        const originalLocator = this._page.getByPlaceholder(placeholder, options);
+        return this.newSkyrampPlaywrightLocator(originalLocator, placeholder, options);
+    }
 
-  getByTestId(testId, options) {
-      const originalLocator = this._page.getByTestId(testId);
-      return this.newSkyrampPlaywrightLocator(originalLocator, testId, options)
-  }
+    getByAltText(alt, options) {
+        const originalLocator = this._page.getByAltText(alt, options);
+        return this.newSkyrampPlaywrightLocator(originalLocator, alt, options);
+    }
 
-  getByTitle(title, options) {
-      const originalLocator = this._page.getByTitle(title, options);
-      return this.newSkyrampPlaywrightLocator(originalLocator, title, options)
-  }
+    async goto(url, options) {
+        const result = await this._page.goto(url, options);
+        const content = await this._page.content();
+        if (hasJavascriptWrapper(content)) {
+            debug(`javascript download detected when visiting ${this._page.url()}`);
+            debug(`  wait for sometime for potential hydration`);
+            await this._page.waitForTimeout(defaultWaitForTimeout);
+        } else {
+            debug(`javascript not detected when visiting ${this._page.url()}`);
+        }
+        this._curUrl = this._page.url();
+        return result;
+    }
 
-  getByPlaceholder(placeholder, options) {
-      const originalLocator = this._page.getByPlaceholder(placeholder, options);
-      return this.newSkyrampPlaywrightLocator(originalLocator, placeholder, options)
-  }
+    addLLMChoices(originalLocator, newLocator, stack) {
+        if (this.llmChoices == undefined) {
+            this.llmChoices = []
+        }
 
-  getByAltText(alt, options) {
-      const originalLocator = this._page.getByAltText(alt, options);
-      return this.newSkyrampPlaywrightLocator(originalLocator, alt, options)
-  }
+        this.llmChoices.push({
+            "original": originalLocator.toString(),
+            "new": newLocator.toString(),
+            "at": parseErrorStack(stack),
+        });
+    }
+
+    getLLMChoices() {
+        return this.llmChoices
+    }
+
+    hasLLMChoices() {
+        if (this.llmChoices == undefined || this.llmChoices.length == 0) {
+            return false;
+        }
+        return true;
+    }
 }
 
 function newSkyrampPlaywrightPage(page) {
     return new SkyrampPlaywrightPage(page);
 }
 
+function expect(obj) {
+    if (obj instanceof SkyrampPlaywrightLocator) {
+        return playwrightExpect(obj.unwrap());
+    }
+    return playwrightExpect(obj);
+}
+
 module.exports = {
     newSkyrampPlaywrightPage,
+    expect,
 };

package/src/function.d.ts

@@ -0,0 +1,20 @@
+import { ResponseV2 } from "./classes/ResponseV2";
+
+/**
+ * Checks if the response's status code matches the expected status code (with support for wildcards).
+ *
+ * The expected status can include 'x' as a wildcard for a single digit.
+ * Examples:
+ *   - "200" matches exactly 200
+ *   - "20x" matches any status code in the range 200 to 209
+ *   - "2xx" matches any status code in the range 200 to 299
+ *
+ * @param response - The response object containing a `status_code` attribute.
+ * @param expectedStatus - The expected status code as a string with optional 'x' wildcards.
+ * @returns True if the status code matches, false otherwise.
+ * @throws Error if the response object lacks a 'status_code' attribute.
+ */
+export function checkStatusCode(
+  response: ResponseV2,
+  expectedStatus: string
+): boolean;

package/src/index.d.ts

@@ -1,21 +1,21 @@
-export * from './classes/Endpoint';
-export * from './classes/GrpcEndpoint';
-export * from './classes/RestEndpoint';
-export * from './classes/Scenario';
-export * from './classes/SkyrampClient';
-export * from './classes/RequestValue';
-export * from './classes/ResponseValue';
-export * from './classes/RestParam';
-export * from './classes/MultipartParam';
-export * from './classes/TrafficConfig';
-export * from './classes/DelayConfig';
-export * from './classes/Protocol';
-export * from './classes/RequestV2';
-export * from './classes/ResponseV2';
-export * from './classes/MockV2';
-export * from './classes/AsyncScenario';
-export * from './classes/LoadTestConfig';
-export * from './classes/AsyncTestStatus';
-export * from './utils';
-export * from './function';
-export * from './classes/SmartPlaywright';
+export * from "./classes/Endpoint";
+export * from "./classes/GrpcEndpoint";
+export * from "./classes/RestEndpoint";
+export * from "./classes/Scenario";
+export * from "./classes/SkyrampClient";
+export * from "./classes/RequestValue";
+export * from "./classes/ResponseValue";
+export * from "./classes/RestParam";
+export * from "./classes/MultipartParam";
+export * from "./classes/TrafficConfig";
+export * from "./classes/DelayConfig";
+export * from "./classes/Protocol";
+export * from "./classes/RequestV2";
+export * from "./classes/ResponseV2";
+export * from "./classes/MockV2";
+export * from "./classes/AsyncScenario";
+export * from "./classes/LoadTestConfig";
+export * from "./classes/AsyncTestStatus";
+export * from "./utils";
+export * from "./function";
+export * from "./classes/SmartPlaywright";

package/src/index.js

@@ -19,7 +19,7 @@ const AsyncTestStatus = require('./classes/AsyncTestStatus');
 const MockV2 = require('./classes/MockV2');
 const { getValue, checkSchema, iterate } = require('./utils');
 const { checkStatusCode } = require('./function');
-const { newSkyrampPlaywrightPage } = require('./classes/SmartPlaywright');
+const { newSkyrampPlaywrightPage, expect } = require('./classes/SmartPlaywright');
 
 module.exports = {
   SkyrampClient,
@@ -47,4 +47,5 @@ module.exports = {
   checkSchema,
   iterate,
   newSkyrampPlaywrightPage,
+  expect,
 }

package/src/utils.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Checks if the given value is a JSON string.
+ * @param value - The value to check
+ * @returns True if the value is a JSON string, false otherwise
+ */
+export function isJSONString(value: string): boolean;
+
+/**
+ * Safely converts a value to a JSON string.
+ * @param value - The value to stringify
+ * @returns The JSON string representation
+ */
+export function safeStringify(value: string): string;
+
+/**
+ * Creates a test description from a scenario.
+ * @param scenario - The scenario object
+ * @returns The test description
+ */
+export function createTestDescriptionFromScenario(scenario: object): object;
+
+/**
+ * Gets YAML bytes from a configuration.
+ * @param config - The configuration object
+ * @returns The YAML bytes
+ */
+export function getYamlBytes(config: object): string;
+
+/**
+ * Reads data from a file.
+ * @param filePath - The path to the file
+ * @returns The file data
+ */
+export function readDataFromFile(
+  filename: string
+): [string, false] | [string, true];
+
+/**
+ * Extracts a value from JSON using JSONPath syntax.
+ * @param jsonInput - The JSON object or string to extract from
+ * @param path - The JSONPath expression (e.g., "$.value", "$.data[0].name")
+ * @returns The extracted value or null if not found
+ */
+export function getValue(
+  jsonInput: object,
+  path: string
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+): any;
+
+/**
+ * Validates JSON against a schema.
+ * @param jsonInput - The JSON to validate
+ * @param schema - The schema to validate against
+ * @returns The validation result
+ */
+export function checkSchema(jsonInput: object, schema: object): boolean;
+
+/**
+ * Iterates over JSON data structure.
+ * @param jsonInput - The JSON data to iterate
+ * @returns The iteration result
+ */
+export function iterate(jsonInput: object): object;
+
+/**
+ * The Skyramp YAML version constant.
+ */
+export const SKYRAMP_YAML_VERSION: string;