@skyramp/skyramp 2025.8.11 → 2025.12.19

package/src/classes/SmartPlaywright.js

@@ -0,0 +1,992 @@
+const { expect: playwrightExpect } = require('@playwright/test');
+const lib = require('../lib');
+const koffi = require('koffi');
+const fs = require('fs');
+const path = require('path');
+
+const responseType = koffi.struct({
+  response: 'char*',
+  error: 'char*',
+});
+
+const { checkForUpdate } = require('../utils');
+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 = {
+        "original_selector": originalSelector,
+        "error_message": errorMessage,
+        "dom_context": domContext,
+        "page_title": pageTitle,
+        "page_url": pageURL,
+        "language": "javascript"
+    };
+    const request = JSON.stringify(requestData);
+
+    return new Promise((resolve, reject) => {
+        improvePlaywrightSelectorWrapper.async(request, (err, res) => {
+            if (err) {
+                reject(err);
+            } else if (res) {
+                if (res.error != null) {
+                    reject(res.error);
+                } else if (res.response != null) {
+                    const response = JSON.parse(res.response);
+                    resolve(response["suggestions"] ?? null);
+                } else {
+                    reject(new Error('failed'));
+                }
+            } else {
+                reject(new Error('failed'));
+            }
+        });
+    });
+}
+
+function debug(...args) {
+    if (process.env.SKYRAMP_DEBUG == "true") {
+        console.log(...args);
+    }
+}
+
+/**
+ * Detect if we're running inside a Docker container.
+ *
+ * Checks the SKYRAMP_IN_DOCKER environment variable
+ *
+ * @returns {boolean} True if running in Docker, false otherwise
+ */
+function isRunningInDocker() {
+    const envValue = (process.env.SKYRAMP_IN_DOCKER || '').toLowerCase();
+    return envValue === 'true' || envValue === '1' || envValue === 'yes';
+}
+
+/**
+ * Transform localhost URLs to host.docker.internal when running in Docker.
+ *
+ * This helper function automatically detects if we're running inside a Docker
+ * container and transforms localhost URLs to use host.docker.internal, which
+ * allows containers to access services running on the host machine.
+ *
+ * @param {string} url - The URL to potentially transform
+ * @returns {string} The transformed URL if in Docker and URL contains localhost, otherwise the original URL
+ */
+function transformUrlForDocker(url) {
+    if (!url) {
+        return url;
+    }
+
+    // Auto-detect if we're running in Docker
+    if (!isRunningInDocker()) {
+        return url;
+    }
+
+    // Use proper URL parsing to only replace the hostname component
+    try {
+        const urlObj = new URL(url);
+        const hostname = urlObj.hostname;
+
+        // Only transform if hostname is exactly 'localhost' or '127.0.0.1'
+        if (hostname === 'localhost' || hostname === '127.0.0.1') {
+            urlObj.hostname = 'host.docker.internal';
+            const transformed = urlObj.toString();
+            debug(`Transformed URL: ${url} -> ${transformed}`);
+            return transformed;
+        }
+    } catch (error) {
+        debug(`Failed to parse URL: ${url}, returning original`);
+    }
+
+    return url;
+}
+
+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();
+
+    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 suggestions available, failing with original error");
+        throw error;
+    }
+
+    suggestions.sort((a, b) => (b.confidence ?? 0) - (a.confidence ?? 0))
+    debug(suggestions)
+
+    for (let suggestion of suggestions) {
+        try {
+            const newLocator = skyrampLocator.createLocatorFromString(suggestion.selector);
+            if (newLocator == null) {
+                continue
+            }
+
+            const locatorCount = await newLocator.count();
+
+            debug(`trying new Locator ${newLocator} instead of ${skyrampLocator._locator}, 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 => {
+                    // if it fails, move to the next one
+                    debug(`retrying with LLM failed at ${skyrampLocator._locator} replaced by {newLocator}`, error.name);
+                });
+            }
+        } catch {
+            continue
+        }
+    }
+
+    error.message = `Failed to find a good alternative for ${skyrampLocator._locator} with LLM.\n` +
+                    `Please add "data-testid" attribute for a more stable locator\n` + error.message;
+    throw error;
+}
+
+class SkyrampPlaywrightLocator {
+    constructor(skyrampPage, locator, prevLocator, args, options) {
+        this._skyrampPage = skyrampPage
+        this._locator = locator
+        this._previousLocator = prevLocator
+        this._args = args
+        this._options = options
+        return new Proxy(this, {
+          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._locator, prop, wrapper._locator);
+
+            // 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._locator);
+            }
+
+            return value;
+          }
+        });
+    }
+
+    async execute() {
+        debug(`    execute ${ this._locator}.${this.execFname} ${this.execParam ?? ''} ${this.execArgs ?? ''}`)
+        const func = this._locator[this.execFname];
+        if (this.execParam !== null && this.execParam !== undefined) {
+            return func.call(this._locator, this.execParam, ...this.execArgs);
+        } else {
+            return func.call(this._locator, ...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;
+    }
+
+    wrapError(msg, error) {
+        let newMsg = msg;
+        if (this._skyrampPage.hasLLMChoices()) {
+            newMsg += this.generateLLMErrors();
+        }
+
+        // Ensure error is an Error object, not a string
+        if (typeof error === 'string') {
+            error = new Error(error);
+        } else if (!(error instanceof Error)) {
+            error = new Error(String(error));
+        }
+
+        error.message = error.message + "\n" + newMsg
+
+        return error
+    }
+
+    hydrationErrorMsg = "Potentially a hydration issue. Please add enough waitForTimeout()"
+
+    newPrevHydrationErrorMsg() {
+        return `Cannot find locator ${this._locator} and likely a hydration issue on ${this._previousLocator._locator}.\n` +
+               `Please add enough waitForTimeout() on ${this._previoousLocator._locator}`;
+    }
+
+    newMultiLocatorErrorMsg() {
+        return `${this._locator} found ${this.locatorCount} locators. Please add "data-testid" attribute for a more stable locator`
+    }
+
+    async _retryWithLLM(error, msg1) {
+        // if API_KEY is not defined, throw an error here without trying
+        if (!process.env.API_KEY) {
+            error.message = msg1 + error.message;
+            throw error;
+        }
+
+        debug(`  try to get suggessions from LLM for ${this._locator}`);
+        return retryWithLLM(this, error).then(result => {
+            this.LLMselector = true;
+            return result;
+        }).catch(newError => {
+            throw this.wrapError("", newError)
+        });
+    }
+
+    async SmartRetryWithFallback(fname, param, ...args) {
+        this.execFname = fname;
+        this.execParam = param;
+        this.execArgs = args;
+
+        let locatorCount = await this._locator.count();
+        let currentUrl = this._skyrampPage._page.url();
+        debug(`handling ${ this._locator }.${ fname }, count = ${ locatorCount }, ${currentUrl}`);
+        this.locatorCount = locatorCount
+
+        //debug(`current url = ${currentUrl}`);
+
+        // if locator exists, DOM is available
+        if (locatorCount == 1) {
+            debug(`  single locator for ${this._locator} identified, ${currentUrl}`);
+            // we try action, this will most likely succeed
+            // if it fails, there could be potentially a hydration issue we can retry after a little wait time
+            try {
+                return await this.execute().then(result => {
+                    return this._skyrampPage.checkNavigation(currentUrl, result);
+                });
+            } catch (error) {
+                debug(`  first attempt of ${this._locator} failed, ${error.name}`);
+                if (error.name == "TimeoutError") {
+                    // this is likely a hydration issue
+                    // we wait a bit and retry
+                    debug(`  locator ${this._locator} exists, but execution failed, wait a bit and try again`);
+                    await this.wait(defaultWaitForTimeout);
+
+                    // Is this really necessary?
+                    await this.execute().then(result => {
+                        return this._skyrampPage.checkNavigation(currentUrl, result);
+                    }).catch(() => {
+                        debug(`  failed second time and execute previous locator ${this._previousLocator._locator} again`);
+                        this._previousLocator.execute();
+                    }).catch(() => {
+                        debug(`  failed to execute previous locator ${this._previousLocator._locator} again, continue`);
+                    });
+
+                    return this.execute().catch(newError => {
+                        debug(`  third attempt on ${this._locator} failed ${newError.name}`);
+                        if (newError.name == "TimeoutError") {
+                            // this hadn't happened yet. we need to validate if this is indeed hydration case
+                            return this._retryWithLLM(newError, this.hydrationErrorMsg)
+                        }
+                        if (newError.message.includes("strict mode violation")) {
+                            return this._retryWithLLM(newError, this.newMultiLocatorErrorMsg());
+                        }
+                        throw error;
+                    });
+                }
+                if (error.message.includes("strict mode violation")) {
+                    return this._retryWithLLM(error, this.newMultiLocatorErrorMsg());
+                }
+                if (error.message.includes("Unknown key")) {
+                    let msg = error.message.split("\n")[0];
+                    console.log(`${msg}, continue without execution`);
+                    return undefined
+                }
+                // we do not handle the rest of the error cases, but simply forward error
+                throw error;
+            }
+        } else if (locatorCount > 0) {
+            debug(`  multiple ${locatorCount} locators for ${this._locator} identified, ${currentUrl}`);
+            // wait a bit and retry before consulting with LLM
+            await this.wait(defaultWaitForTimeout);
+
+            locatorCount = await this._locator.count();
+            this.locatorCount = locatorCount
+
+            if (locatorCount > 5) {
+                // we fail even without trying
+                throw new Error(`${locatorCount} locators detected for ${this._locator}. Please add "data-testid" attribute for a more stable locator`);
+            }
+
+            // this will likely fail, but we try to get error message generated by playwright
+            return this.execute().then(result => {
+                return this._skyrampPage.checkNavigation(currentUrl, result);
+            }).catch(error => {
+                return this._retryWithLLM(error, this.newMultiLocatorErrorMsg());
+            });
+        } 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
+            // 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, ${currentUrl}`);
+                // 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}, new locator count = ${previousCount}, ${currentUrl}`);
+                // 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, continue`);
+                });
+
+                try {
+                    // then execute the current one
+                    return await this.execute().then(result => {
+                        return this._skyrampPage.checkNavigation(currentUrl, result);
+                    });
+                } 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().then(result => {
+                            return this._skyrampPage.checkNavigation(currentUrl, result);
+                        }).catch(newError => {
+                            return this._retryWithLLM(newError, this.newPrevHydrationErrorMsg());
+                        });
+                    }
+                    if (error.message.includes("strict mode violation")) {
+                        debug(`  a rare case when multiple locators are detected on ${this._locator}`);
+                        return this._retryWithLLM(error, this.newMultiLocatorErrorMsg());
+                    }
+                    throw error;
+                }
+            } else {
+                if (this._previousLocator && this._previousLocator.LLMselector) {
+                    debug(`  ${this._locator} locator count is zero, but previous locator was selected by LLM`);
+                } else {
+                    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 ${this._locator} count = ${this.locatorCount}, ${currentUrl}`);
+
+                try {
+                    return await this.execute().then(result => {
+                        return this._skyrampPage.checkNavigation(currentUrl, result);
+                    });
+                } 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().then(result=> {
+                            return this._skyrampPage.checkNavigation(currentUrl, result);
+                        }).catch(newError => {
+                            if (newError.name == "TimeoutError") {
+                                return this._retryWithLLM(newError, this.hydrationErrorMsg);
+                            }
+                            if (newError.message.includes("strict mode violation")) {
+                                return this._retryWithLLM(newError, this.newMultiLocatorErrorMsg());
+                            }
+                            throw newError;
+                        });
+                    }
+                    // if multiple locator found
+                    if (this.locatorCount > 1 || error.message.includes("strict mode violation")) {
+                        return this._retryWithLLM(error, this.newMultiLocatorErrorMsg());
+                    }
+                    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);
+    }
+
+    async fill(text, ...args) {
+        return this.SmartRetryWithFallback("fill", text, ...args);
+    }
+
+    async type(text, ...args) {
+        return this.SmartRetryWithFallback("type", text, ...args);
+    }
+
+    async press(key, ...args) {
+        return this.SmartRetryWithFallback("press", key, ...args);
+    }
+
+    async check(...args) {
+        return this.SmartRetryWithFallback("check", null, ...args);
+    }
+
+    async uncheck(...args) {
+        return this.SmartRetryWithFallback("uncheck", null, ...args);
+    }
+
+    async selectOption(value, ...args) {
+        return this.SmartRetryWithFallback("selectOption", value, ...args);
+    }
+
+    async hover(...args) {
+        return this.SmartRetryWithFallback("hover", null, ...args);
+    }
+
+    async textContent(...args) {
+        return this.SmartRetryWithFallback("textContent", null, ...args);
+    }
+
+    async isVisible(...args) {
+        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)
+        return this._skyrampPage.newSkyrampPlaywrightLocator(new_locator, index, null);
+    }
+
+    first() {
+        // get first element - return a new SkyrampPlaywrightLocator
+        let new_locator = this._locator.first()
+        return this._skyrampPage.newSkyrampPlaywrightLocator(new_locator, null, null);
+    }
+
+    last() {
+        // get last element - return a new 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, testInfo) {
+        checkForUpdate("npm")
+
+        this._page = page;
+        this._testInfo = testInfo; // Store testInfo for screenshot auto-baseline
+        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;
+            }
+        });
+    }
+
+    unwrap() {
+        return this._page;
+    }
+
+    pushLocator(locator) {
+        if (this.locators == undefined ) {
+            this.locators = [];
+        }
+        this.locators.push(locator);
+    }
+
+    getLastLocator() {
+        if (this.locators == undefined) {
+            return null
+        }
+
+        if (this.locators.length == 0) {
+            return null
+        }
+        return this.locators.at(-1)
+    }
+
+    newSkyrampPlaywrightLocator(originalLocator, param, options) {
+        let prevLocator = this.getLastLocator();
+        /*
+        if (prevLocator != null) {
+            debug(`handling ${originalLocator} prev ${prevLocator._locator}`);
+        } else {
+            debug(`handling ${originalLocator}`);
+        }
+        */
+
+        let newLocator = new SkyrampPlaywrightLocator(this, originalLocator, prevLocator, [param], options);
+        this.pushLocator(newLocator)
+        return newLocator
+    }
+
+    locator(selector, options) {
+        const originalLocator = this._page.locator(selector, options);
+        return this.newSkyrampPlaywrightLocator(originalLocator, selector, options);
+    }
+
+    getByRole(role, options) {
+        const originalLocator = this._page.getByRole(role, options);
+        return this.newSkyrampPlaywrightLocator(originalLocator, role, options);
+    }
+
+    getByText(text, options) {
+        const originalLocator = this._page.getByText(text, options);
+        return this.newSkyrampPlaywrightLocator(originalLocator, text, options);
+    }
+
+    getByLabel(label, options) {
+        const originalLocator = this._page.getByLabel(label, options);
+        return this.newSkyrampPlaywrightLocator(originalLocator, label, options);
+    }
+
+    getByTestId(testId, options) {
+        const originalLocator = this._page.getByTestId(testId);
+        return this.newSkyrampPlaywrightLocator(originalLocator, testId, options);
+    }
+
+    getByTitle(title, options) {
+        const originalLocator = this._page.getByTitle(title, options);
+        return this.newSkyrampPlaywrightLocator(originalLocator, title, options);
+    }
+
+    getByPlaceholder(placeholder, options) {
+        const originalLocator = this._page.getByPlaceholder(placeholder, options);
+        return this.newSkyrampPlaywrightLocator(originalLocator, placeholder, options);
+    }
+
+    getByAltText(alt, options) {
+        const originalLocator = this._page.getByAltText(alt, options);
+        return this.newSkyrampPlaywrightLocator(originalLocator, alt, options);
+    }
+
+    async goto(url, options) {
+        const transformedUrl = transformUrlForDocker(url);
+        const result = await this._page.goto(transformedUrl, 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()}`);
+        }
+        return result;
+    }
+
+    addLLMChoices(originalLocator, newLocator, stack) {
+        if (this.llmChoices == undefined) {
+            this.llmChoices = []
+        }
+
+        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;
+    }
+
+    async checkNavigation(original, result) {
+        const newURL = this._page.url()
+        if (newURL != original) {
+            debug(`page navigation to ${newURL} detected, wait a bit`);
+            await this._page.waitForTimeout(defaultWaitForTimeout);
+        }
+        return result;
+    }
+}
+
+function newSkyrampPlaywrightPage(page, testInfo) {
+    return new SkyrampPlaywrightPage(page, testInfo);
+}
+
+/**
+ * Wrapper class for Playwright's expect that provides auto-baseline generation for screenshots.
+ * Check if snapshot exists, create if missing, then compare. Enabling single-run screenshots
+ */
+class SkyrampPageAssertions {
+    constructor(playwrightExpectation, actualObject, testInfo, pageOrLocator) {
+        this._playwrightExpectation = playwrightExpectation;
+        this._actualObject = actualObject;
+        this._testInfo = testInfo;
+        this._pageOrLocator = pageOrLocator || actualObject;
+        this._autoBaseline = process.env.SKYRAMP_AUTO_BASELINE !== 'false';
+
+        // Proxy to forward all methods except toHaveScreenshot
+        return new Proxy(this, {
+            get(target, prop) {
+                if (prop in target) {
+                    return target[prop];
+                }
+                const playwrightValue = target._playwrightExpectation[prop];
+                if (typeof playwrightValue === 'function') {
+                    return playwrightValue.bind(target._playwrightExpectation);
+                }
+                return playwrightValue;
+            }
+        });
+    }
+
+    /**
+     * Auto-generates baseline screenshots if missing
+     */
+    async toHaveScreenshot(nameOrOptions, options) {
+        // wait for some time before taking snapshot
+        await this._pageOrLocator.waitForTimeout(2000);
+
+        // If auto-baseline disabled or no testInfo, use standard Playwright behavior
+        if (!this._autoBaseline || !this._testInfo) {
+            return await this._playwrightExpectation.toHaveScreenshot(nameOrOptions, options);
+        }
+
+        // Only handle string names (auto-generated names not supported)
+        if (typeof nameOrOptions !== 'string') {
+            return await this._playwrightExpectation.toHaveScreenshot(nameOrOptions, options);
+        }
+
+        // Use Playwright's official API to get snapshot path
+        // playwright.config.js
+        //export default {
+        //  1. Configure snapshot directory
+        //  snapshotDir: './my-snapshots',  // Default: next to test file, filename-snapshots
+        //  2. Configure snapshot path template
+        //  snapshotPathTemplate: '{testDir}/__screenshots__/{testFilePath}/{arg}{ext}',
+        //  3. Configure base snapshot directory
+        //  testDir: './tests',
+        //}
+        const snapshotPath = this._testInfo.snapshotPath(nameOrOptions);
+
+        if (!fs.existsSync(snapshotPath)) {
+            const snapshotDir = path.dirname(snapshotPath);
+            if (!fs.existsSync(snapshotDir)) {
+                fs.mkdirSync(snapshotDir, { recursive: true });
+            }
+            // Apply Playwright's toHaveScreenshot defaults for consistency
+            // User can override these defaults via options
+            await this._actualObject.screenshot({
+                animations: 'disabled',
+                caret: 'hide',
+                scale: 'css',
+                ...options,
+                path: snapshotPath  // Always use our computed path
+            });
+            debug(`Generated baseline: ${snapshotPath}`);
+        }
+
+        // Baseline exists (or just created): assert normally
+        return await this._playwrightExpectation.toHaveScreenshot(nameOrOptions, options);
+    }
+}
+
+/**
+ * Custom expect function with auto-baseline screenshot support.
+ * Automatically extracts testInfo from wrapped page.
+ *
+ * Usage:
+ *   // testInfo is automatically extracted from the wrapped page
+ *   await expect(page).toHaveScreenshot('page.png');
+ *   await expect(page.locator('h1')).toHaveScreenshot('heading.png');
+ */
+function expect(obj, testInfo) {
+    // Unwrap smart locators and pages, extract testInfo if not provided
+    let actualObject = obj;
+    let extractedTestInfo = testInfo;
+
+    if (obj instanceof SkyrampPlaywrightLocator) {
+        actualObject = obj.unwrap();
+        // Get testInfo from the locator's parent page
+        if (!extractedTestInfo && obj._skyrampPage && obj._skyrampPage._testInfo) {
+            extractedTestInfo = obj._skyrampPage._testInfo;
+        }
+        const playwrightExpectation = playwrightExpect(actualObject);
+        return new SkyrampPageAssertions(playwrightExpectation, actualObject, extractedTestInfo, actualObject.page());
+    }
+    if (obj instanceof SkyrampPlaywrightPage) {
+        actualObject = obj.unwrap();
+        // Get testInfo from the wrapped page
+        if (!extractedTestInfo && obj._testInfo) {
+            extractedTestInfo = obj._testInfo;
+        }
+        const playwrightExpectation = playwrightExpect(actualObject);
+        return new SkyrampPageAssertions(playwrightExpectation, actualObject, extractedTestInfo);
+    }
+    return playwrightExpect(obj);
+}
+
+module.exports = {
+    newSkyrampPlaywrightPage,
+    expect,
+};