@flash-ai-team/flash-test-framework 0.0.1

package/dist/keywords/AIWebUI.js

@@ -0,0 +1,276 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AIWeb = void 0;
+const Keyword_1 = require("../core/Keyword");
+const WebUI_1 = require("./WebUI");
+const ObjectRepository_1 = require("../core/ObjectRepository");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const openai_1 = __importDefault(require("openai"));
+/**
+ * AIWeb: Uses LLM to locate elements based on natural language descriptions.
+ */
+class AIWeb {
+    static get page() {
+        return Keyword_1.KeywordContext.page;
+    }
+    static get config() {
+        try {
+            const configPath = path_1.default.resolve(process.cwd(), 'ai.config.json');
+            if (fs_1.default.existsSync(configPath)) {
+                return JSON.parse(fs_1.default.readFileSync(configPath, 'utf-8'));
+            }
+        }
+        catch (e) {
+            console.error('Failed to load ai.config.json', e);
+        }
+        return {};
+    }
+    static async getOpenAIClient() {
+        const config = this.config;
+        if (!config.enabled || !config.apiKey || config.apiKey === 'YOUR_OPENAI_API_KEY') {
+            console.warn('AI functionality is disabled or API key is missing in ai.config.json');
+            return null;
+        }
+        return new openai_1.default({ apiKey: config.apiKey });
+    }
+    /**
+     * Finds a locator using AI based on a natural language description.
+     */
+    static async findElement(description) {
+        const client = await this.getOpenAIClient();
+        if (!client) {
+            throw new Error('AI is not configured. Please check ai.config.json.');
+        }
+        // 1. Get simplified DOM snapshot
+        // We strip non-interactive elements to save tokens and reduce noise
+        const snapshot = await this.page.evaluate(() => {
+            function getSimplifiedDOM(node) {
+                const relevantTags = ['BUTTON', 'INPUT', 'A', 'SELECT', 'TEXTAREA', 'LABEL', 'DIV', 'SPAN', 'IMG', 'H1', 'H2', 'H3', 'P'];
+                if (!relevantTags.includes(node.tagName))
+                    return null;
+                const interactable = node.tagName === 'A' || node.tagName === 'BUTTON' || node.tagName === 'INPUT' ||
+                    node.tagName === 'SELECT' || node.tagName === 'TEXTAREA' ||
+                    node.hasAttribute('onclick') || node.getAttribute('role') === 'button';
+                // Skip invisible elements (basic check)
+                const rect = node.getBoundingClientRect();
+                if (rect.width === 0 || rect.height === 0)
+                    return null;
+                // Generate a unique selector path
+                // This is a naive implementation; for production, use a robust unique selector generator
+                let selector = node.tagName.toLowerCase();
+                if (node.id)
+                    selector += `#${node.id}`;
+                else if (node.className)
+                    selector += `.${node.className.split(' ').join('.')}`;
+                // If it's deeper, we might need a path, but let's try strict attributes first
+                const attributes = {};
+                if (node.id)
+                    attributes.id = node.id;
+                if (node.getAttribute('name'))
+                    attributes.name = node.getAttribute('name');
+                if (node.getAttribute('placeholder'))
+                    attributes.placeholder = node.getAttribute('placeholder');
+                if (node.getAttribute('aria-label'))
+                    attributes['aria-label'] = node.getAttribute('aria-label');
+                if (node.textContent)
+                    attributes.text = node.textContent.trim().substring(0, 50);
+                return {
+                    tag: node.tagName,
+                    ...attributes,
+                    // We need a way to target this back. 
+                    // Let's assign a temporary data-ai-id if it doesn't have a good selector?
+                    // Or just trust the attributes.
+                    // Let's stick with best-effort selector generation on the client side validation?
+                    // Actually, let's inject a data-ai-id to be safe.
+                };
+            }
+            // Inject temporary IDs for robust targeting
+            let counter = 0;
+            const elements = [];
+            document.querySelectorAll('*').forEach(el => {
+                const simple = getSimplifiedDOM(el);
+                if (simple) {
+                    const aiId = `ai-${counter++}`;
+                    el.setAttribute('data-ai-id', aiId);
+                    simple['data-ai-id'] = aiId;
+                    elements.push(simple);
+                }
+            });
+            return elements;
+        });
+        // 2. Query LLM
+        const prompt = `
+            You are a test automation assistant.
+            I will provide a simplified JSON list of DOM elements.
+            Find the element that best matches this description: "${description}".
+            
+            Return ONLY the 'data-ai-id' of the best matching element.
+            If no match found, return "NOT_FOUND".
+            
+            Elements:
+            ${JSON.stringify(snapshot).substring(0, 15000)} // Truncate to avoid context limit
+        `;
+        const completion = await client.chat.completions.create({
+            messages: [{ role: 'user', content: prompt }],
+            model: this.config.model || 'gpt-4o',
+        });
+        const aiId = completion.choices[0].message.content?.trim();
+        if (!aiId || aiId === 'NOT_FOUND') {
+            throw new Error(`AI could not locate element for description: "${description}"`);
+        }
+        // 3. Return Locator
+        // We clean up the attribute afterwards? Or just leave it for debug?
+        // Let's leave it for now.
+        return this.page.locator(`[data-ai-id="${aiId}"]`);
+    }
+    static async click(description) {
+        const locator = await this.findElement(description);
+        await locator.click();
+    }
+    static async setText(description, text) {
+        const locator = await this.findElement(description);
+        await locator.fill(text);
+    }
+    static async verifyText(description, expectedText) {
+        const locator = await this.findElement(description);
+        await locator.waitFor();
+        const text = await locator.innerText();
+        if (!text.includes(expectedText)) {
+            throw new Error(`Expected text "${expectedText}" not found in element "${description}". Found: "${text}"`);
+        }
+    }
+    /**
+     * Executes manual test steps by converting them to WebUI keyword calls using AI.
+     * @param steps - Natural language test steps (one per line or paragraph).
+     */
+    static async executeManualSteps(steps) {
+        // Split steps by newlines and filter empty lines
+        const stepLines = steps.split('\n').map(s => s.trim()).filter(s => s.length > 0);
+        let lastContextText = "";
+        for (const line of stepLines) {
+            // Remove numbering (e.g., "1. ")
+            const cleanLine = line.replace(/^\d+\.\s*/, '').trim();
+            console.log(`Processing step: "${cleanLine}"`);
+            // 1. Navigate to "url"
+            const navigateMatch = cleanLine.match(/^Navigate to "([^"]+)"$/i);
+            if (navigateMatch) {
+                await WebUI_1.Web.navigateToUrl(navigateMatch[1]);
+                continue;
+            }
+            // 2. Enter "text" into ...
+            const enterMatch = cleanLine.match(/^Enter "([^"]+)" into (?:the )?(.+)$/i);
+            if (enterMatch) {
+                const text = enterMatch[1];
+                let targetDesc = enterMatch[2];
+                lastContextText = text;
+                // Clean up target description
+                targetDesc = targetDesc.replace(/ field$/i, '').replace(/ input$/i, '').trim();
+                const selector = `internal:label="${targetDesc}"`;
+                await WebUI_1.Web.setText((0, ObjectRepository_1.el)(selector, targetDesc), text);
+                continue;
+            }
+            // Search "text"
+            const searchMatch = cleanLine.match(/^Search "([^"]+)"$/i);
+            if (searchMatch) {
+                const text = searchMatch[1];
+                lastContextText = text;
+                await WebUI_1.Web.search(text);
+                continue;
+            }
+            // 3. Click ...
+            const quotedClickRound = cleanLine.match(/^Click (?:on )?(?:the )?"([^"]+)"/i);
+            const clickMatch = cleanLine.match(/^Click (?:on )?(?:the )?(.+)$/i);
+            if (quotedClickRound || clickMatch) {
+                let targetDesc = quotedClickRound ? quotedClickRound[1] : clickMatch[1];
+                // Existing cleanup (irrelevant for quoted match usually, but good for safety)
+                targetDesc = targetDesc.replace(/ button$/i, '').replace(/ link$/i, '').replace(/ marker$/i, '').replace(/ image$/i, '').trim();
+                if ((targetDesc === "" || targetDesc.toLowerCase() === "marker") && lastContextText) {
+                    targetDesc = lastContextText;
+                }
+                // Check if image exists for targetDesc
+                // Assume assets folder is tests/assets
+                const imageExtensions = ['png', 'jpg', 'jpeg'];
+                let imagePath = null;
+                for (const ext of imageExtensions) {
+                    const checkPath = path_1.default.resolve(process.cwd(), 'tests/assets', `${targetDesc}.${ext}`);
+                    if (fs_1.default.existsSync(checkPath)) {
+                        imagePath = checkPath;
+                        break;
+                    }
+                }
+                if (imagePath) {
+                    await WebUI_1.Web.clickImage(imagePath);
+                    continue;
+                }
+                // For buttons, use button role if possible, or similar text
+                // Fallback to simple text selector to avoid invalid selector errors
+                // Use nth=0 to avoid strict mode violations if multiple elements match (common in search results)
+                const selector = `text="${targetDesc}" >> nth=0`;
+                await WebUI_1.Web.click((0, ObjectRepository_1.el)(selector, targetDesc));
+                continue;
+            }
+            // 4. Press ...
+            const pressMatch = cleanLine.match(/^Press (?:key )?"?([^"]+)"?$/i);
+            if (pressMatch) {
+                const key = pressMatch[1];
+                await WebUI_1.Web.pressKey(key);
+                continue;
+            }
+            // 5. Scroll to ...
+            const scrollMatch = cleanLine.match(/^Scroll to (?:the )?(.+)$/i);
+            if (scrollMatch) {
+                let targetDesc = scrollMatch[1];
+                targetDesc = targetDesc.replace(/ button$/i, '').replace(/ link$/i, '').replace(/ marker$/i, '').trim();
+                const selector = `text="${targetDesc}" >> nth=0`;
+                await WebUI_1.Web.scrollToElement((0, ObjectRepository_1.el)(selector, targetDesc));
+                continue;
+            }
+            // 6. Verify that the text "text" is present
+            const verifyTextMatch = cleanLine.match(/^Verify that the text "([^"]+)" is present$/i);
+            if (verifyTextMatch) {
+                const expectedText = verifyTextMatch[1];
+                await WebUI_1.Web.verifyElementPresent((0, ObjectRepository_1.el)(`text="${expectedText}"`, `Text '${expectedText}'`));
+                continue;
+            }
+            console.warn(`Could not parse step: "${cleanLine}"`);
+        }
+    }
+}
+exports.AIWeb = AIWeb;
+__decorate([
+    (0, Keyword_1.Keyword)("AI Click"),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], AIWeb, "click", null);
+__decorate([
+    (0, Keyword_1.Keyword)("AI Set Text"),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String]),
+    __metadata("design:returntype", Promise)
+], AIWeb, "setText", null);
+__decorate([
+    (0, Keyword_1.Keyword)("AI Verify Text"),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String]),
+    __metadata("design:returntype", Promise)
+], AIWeb, "verifyText", null);
+__decorate([
+    (0, Keyword_1.Keyword)("Execute Manual Steps"),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], AIWeb, "executeManualSteps", null);

package/dist/keywords/WebUI.d.ts

@@ -0,0 +1,166 @@
+import { TestObject } from '../core/ObjectRepository';
+export declare class Web {
+    private static get page();
+    private static getLocator;
+    /**
+     * Navigates to the specified URL.
+     * @param url - The URL to navigate to.
+     */
+    static navigateToUrl(url: string): Promise<void>;
+    /**
+     * Clicks on the specified element.
+     * @param to - The TestObject representing the element.
+     */
+    static click(to: TestObject): Promise<void>;
+    /**
+     * Sets the text of an input element.
+     * @param to - The TestObject representing the input element.
+     * @param text - The text to set.
+     */
+    static setText(to: TestObject, text: string): Promise<void>;
+    /**
+     * Searches for the specified text using heuristic selectors.
+     * @param text - The text to search for.
+     */
+    static search(text: string): Promise<void>;
+    /**
+     * Verifies that the specified element is present (visible) on the page.
+     * @param to - The TestObject representing the element.
+     * @param timeout - The maximum time to wait in milliseconds (default: 5000).
+     */
+    static verifyElementPresent(to: TestObject, timeout?: number): Promise<void>;
+    /**
+     * Gets the visible text of the specified element.
+     * @param to - The TestObject representing the element.
+     * @returns The text content of the element.
+     */
+    static getText(to: TestObject): Promise<string>;
+    /**
+     * Closes the current browser context/page.
+     */
+    static closeBrowser(): Promise<void>;
+    /**
+     * Double clicks on the specified element.
+     * @param to - The TestObject representing the element.
+     */
+    static doubleClick(to: TestObject): Promise<void>;
+    /**
+     * Right clicks (context click) on the specified element.
+     * @param to - The TestObject representing the element.
+     */
+    static rightClick(to: TestObject): Promise<void>;
+    /**
+     * Hovers over the specified element.
+     * @param to - The TestObject representing the element.
+     */
+    static mouseOver(to: TestObject): Promise<void>;
+    /**
+     * Drags the source element and drops it onto the target element.
+     * @param source - The TestObject representing the source element.
+     * @param target - The TestObject representing the target element.
+     */
+    static dragAndDrop(source: TestObject, target: TestObject): Promise<void>;
+    /**
+     * Checks (selects) the specified checkbox or radio button.
+     * @param to - The TestObject representing the element.
+     */
+    static check(to: TestObject): Promise<void>;
+    /**
+     * Unchecks (deselects) the specified checkbox.
+     * @param to - The TestObject representing the element.
+     */
+    static uncheck(to: TestObject): Promise<void>;
+    /**
+     * Selects an option by its value.
+     * @param to - The TestObject representing the dropdown.
+     * @param value - The value of the option to select.
+     */
+    static selectOptionByValue(to: TestObject, value: string): Promise<void>;
+    /**
+     * Selects an option by its label (visible text).
+     * @param to - The TestObject representing the dropdown.
+     * @param label - The label of the option to select.
+     */
+    static selectOptionByLabel(to: TestObject, label: string): Promise<void>;
+    /**
+     * Sends keys to the specified element (sequentially).
+     * @param to - The TestObject representing the element.
+     * @param key - The key(s) to send.
+     */
+    static sendKeys(to: TestObject, key: string): Promise<void>;
+    /**
+     * Presses a specific key on the keyboard.
+     * @param key - The name of the key to press (e.g., "Enter", "Tab", "ArrowDown").
+     */
+    static pressKey(key: string): Promise<void>;
+    /**
+     * Uploads a file to the specified file input element.
+     * @param to - The TestObject representing the file input.
+     * @param absolutePath - The absolute path to the file.
+     */
+    static uploadFile(to: TestObject, absolutePath: string): Promise<void>;
+    /**
+     * Clicks on an image template found on the screen.
+     * @param imagePath - The absolute path to the template image.
+     */
+    static clickImage(imagePath: string): Promise<void>;
+    /**
+     * Verifies that the specified element is NOT present (hidden) on the page.
+     * @param to - The TestObject representing the element.
+     * @param timeout - The maximum time to wait in milliseconds (default: 5000).
+     */
+    static verifyElementNotPresent(to: TestObject, timeout?: number): Promise<void>;
+    /**
+     * Verifies that the element's text matches the expected text.
+     * @param to - The TestObject representing the element.
+     * @param expectedText - The expected text.
+     */
+    static verifyElementText(to: TestObject, expectedText: string): Promise<void>;
+    /**
+     * Verifies that the element's attribute matches the expected value.
+     * @param to - The TestObject representing the element.
+     * @param attribute - The attribute name.
+     * @param expectedValue - The expected attribute value.
+     */
+    static verifyElementAttributeValue(to: TestObject, attribute: string, expectedValue: string): Promise<void>;
+    /**
+     * Waits for the specified element to be visible.
+     * @param to - The TestObject representing the element.
+     * @param timeout - The maximum time to wait in milliseconds (default: 5000).
+     */
+    static waitForElementVisible(to: TestObject, timeout?: number): Promise<void>;
+    /**
+     * Waits for the specified element to be clickable.
+     * @param to - The TestObject representing the element.
+     * @param timeout - The maximum time to wait in milliseconds (default: 5000).
+     */
+    static waitForElementClickable(to: TestObject, timeout?: number): Promise<void>;
+    /**
+     * Waits for the specified element to be not visible (hidden).
+     * @param to - The TestObject representing the element.
+     * @param timeout - The maximum time to wait in milliseconds (default: 5000).
+     */
+    static waitForElementNotVisible(to: TestObject, timeout?: number): Promise<void>;
+    /**
+     * Delays execution for a specified number of seconds.
+     * @param seconds - The number of seconds to wait.
+     */
+    static delay(seconds: number): Promise<void>;
+    /**
+     * Takes a screenshot and saves it to the reports folder.
+     * @param filename - The name of the screenshot file (optional).
+     */
+    static takeScreenshot(filename?: string): Promise<void>;
+    /**
+     * Gets the value of the specified attribute.
+     * @param to - The TestObject representing the element.
+     * @param attribute - The name of the attribute.
+     * @returns The attribute value or null.
+     */
+    static getAttribute(to: TestObject, attribute: string): Promise<string | null>;
+    /**
+     * Scrolls the element into view.
+     * @param to - The TestObject representing the element.
+     */
+    static scrollToElement(to: TestObject): Promise<void>;
+}