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

package/README.md

@@ -0,0 +1,110 @@
+# Flash Test Framework
+
+A powerful, keyword-driven automation framework built on top of Playwright and TypeScript, featuring AI-powered capabilities.
+
+## Installation
+
+```bash
+npm install flash-test-framework
+```
+
+## Setup
+
+1.  **Initialize Playwright** (if not already done):
+    ```bash
+    npx playwright install
+    ```
+
+2.  **Configuration**:
+    *   **Email Reporting**: Create `email.config.json` in your project root if you want email reports.
+    *   **AI Features**: Create `ai.config.json` with your OpenAI API key to use `AIWebUI`.
+    ```json
+    {
+        "enabled": true,
+        "provider": "openai",
+        "apiKey": "sk-...",
+        "model": "gpt-4o"
+    }
+    ```
+
+## Usage
+
+### 1. Basic Web Automation (`web`)
+
+Use `web` for standard, deterministic interactions using selectors.
+
+```typescript
+import { test } from '@playwright/test';
+import { web, findTestObject, KeywordContext } from 'flash-test-framework';
+
+test.describe('My Test Suite', () => {
+    test.beforeEach(async ({ page }, testInfo) => {
+        // Initialize Context
+        KeywordContext.page = page;
+        KeywordContext.testInfo = testInfo;
+    });
+
+    test('Login Test', async () => {
+        await web.navigateToUrl('https://example.com/login');
+        
+        const usernameInput = findTestObject('#username', 'Username Field');
+        const passwordInput = findTestObject('#password', 'Password Field');
+        const loginButton = findTestObject('button[type="submit"]', 'Login Button');
+
+        await web.setText(usernameInput, 'myuser');
+        await web.setText(passwordInput, 'mypassword');
+        await web.click(loginButton);
+        
+        // precise search using heuristics
+        await web.search("Specific Item");
+    });
+});
+```
+
+### 2. AI & Manual Steps (`aiWeb`)
+
+Use `aiWeb` to write tests in plain English or to click elements that are hard to target (like map markers) using images.
+
+**Example: `AIManualSteps.spec.ts`**
+
+```typescript
+import { test } from '@playwright/test';
+import { aiWeb, KeywordContext } from 'flash-test-framework';
+
+test.describe('AI Scenario', () => {
+    test.beforeEach(async ({ page }, testInfo) => {
+        KeywordContext.page = page;
+        KeywordContext.testInfo = testInfo;
+    });
+
+    test('Google Maps Flow', async () => {
+        await aiWeb.executeManualSteps(`
+            1. Navigate to "https://www.google.com/maps"
+            2. Click on "Accept all"
+            3. Search "KFC"
+            4. Press Enter
+            5. Click on the marker image
+        `);
+    });
+});
+```
+
+**Key Features:**
+*   **Natural Language Parsing**: "Click", "Navigate", "Search", "Press Key".
+*   **Image Matching**: Place an image (e.g., `marker.png`) in `tests/assets/`. If you write `Click on "marker image"`, the framework will look for `tests/assets/marker.png` and click it on the screen.
+*   **Heuristic Search**: `Search "text"` automatically finds search bars.
+
+## Keywords
+
+### web
+*   `navigateToUrl(url)`
+*   `click(testObject)`
+*   `setText(testObject, text)`
+*   `search(text)` - Smart search input targeting.
+*   `clickImage(imagePath)` - Visual testing.
+*   `pressKey(key)` - Keyboard interactions.
+*   `verifyElementPresent(testObject)`
+*   ...and more.
+
+### aiWeb
+*   `executeManualSteps(steps: string)` - Parses multi-line natural language steps.

package/dist/core/Keyword.d.ts

@@ -0,0 +1,19 @@
+import { Page, TestInfo } from '@playwright/test';
+export declare const KeywordRegistry: Record<string, Function>;
+/**
+ * Decorator to register a function as a Keyword and wrap it in a Playwright Step
+ * Supports both Stage 3 (Standard) and Stage 2 (Legacy/Experimental) decorators.
+ * @param name Custom name for the keyword (optional)
+ */
+export declare function Keyword(name?: string): (targetOrValue: any, contextOrKey: any, descriptor?: PropertyDescriptor) => any;
+/**
+ * Context holder to share Page and TestInfo across keywords
+ */
+export declare class KeywordContext {
+    private static _page;
+    private static _testInfo;
+    static set page(p: Page);
+    static get page(): Page;
+    static set testInfo(t: TestInfo);
+    static get testInfo(): TestInfo;
+}

package/dist/core/Keyword.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeywordContext = exports.KeywordRegistry = void 0;
+exports.Keyword = Keyword;
+const test_1 = require("@playwright/test");
+const ObjectRepository_1 = require("./ObjectRepository");
+// Registry to store keyword metadata
+exports.KeywordRegistry = {};
+/**
+ * Helper to format arguments for display in reports
+ */
+function formatArg(arg) {
+    if (arg === null)
+        return 'null';
+    if (arg === undefined)
+        return 'undefined';
+    if (typeof arg === 'string')
+        return `"${arg}"`;
+    if (typeof arg === 'number' || typeof arg === 'boolean')
+        return String(arg);
+    if (arg instanceof ObjectRepository_1.TestObject) {
+        return `[Object: ${arg.description || arg.selector}]`;
+    }
+    try {
+        return JSON.stringify(arg);
+    }
+    catch {
+        return String(arg);
+    }
+}
+/**
+ * Decorator to register a function as a Keyword and wrap it in a Playwright Step
+ * Supports both Stage 3 (Standard) and Stage 2 (Legacy/Experimental) decorators.
+ * @param name Custom name for the keyword (optional)
+ */
+function Keyword(name) {
+    return function (targetOrValue, contextOrKey, descriptor) {
+        // Stage 3: (value, context) where context is an object
+        if (typeof contextOrKey === 'object' && contextOrKey !== null && 'kind' in contextOrKey) {
+            const originalMethod = targetOrValue;
+            const context = contextOrKey;
+            const keywordName = name || String(context.name);
+            // Registry
+            exports.KeywordRegistry[keywordName] = originalMethod;
+            return async function (...args) {
+                const argString = args.map(formatArg).join(', ');
+                const stepName = argString ? `${keywordName} (${argString})` : keywordName;
+                return await test_1.test.step(stepName, async () => {
+                    return await originalMethod.apply(this, args);
+                });
+            };
+        }
+        // Legacy: (target, propertyKey, descriptor)
+        // Note: For static methods in legacy, target is the Constructor.
+        let legacyDescriptor = descriptor;
+        if (!legacyDescriptor && typeof contextOrKey === 'string') {
+            legacyDescriptor = Object.getOwnPropertyDescriptor(targetOrValue, contextOrKey);
+        }
+        if (legacyDescriptor) {
+            const originalMethod = legacyDescriptor.value;
+            const keywordName = name || contextOrKey;
+            legacyDescriptor.value = async function (...args) {
+                const argString = args.map(formatArg).join(', ');
+                const stepName = argString ? `${keywordName} (${argString})` : keywordName;
+                return await test_1.test.step(stepName, async () => {
+                    return await originalMethod.apply(this, args);
+                });
+            };
+            exports.KeywordRegistry[keywordName] = legacyDescriptor.value;
+            return legacyDescriptor;
+        }
+        console.warn(`@Keyword decorator failed to apply for ${name || 'unknown'}`);
+    };
+}
+/**
+ * Context holder to share Page and TestInfo across keywords
+ */
+class KeywordContext {
+    static set page(p) {
+        this._page = p;
+    }
+    static get page() {
+        if (!this._page) {
+            throw new Error("Page not initialized. Ensure 'TestBase' setup is called.");
+        }
+        return this._page;
+    }
+    static set testInfo(t) {
+        this._testInfo = t;
+    }
+    static get testInfo() {
+        return this._testInfo;
+    }
+}
+exports.KeywordContext = KeywordContext;

package/dist/core/ObjectRepository.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Represents a Test Object wrapper around Playwright Locators
+ */
+export declare class TestObject {
+    selector: string;
+    description: string;
+    constructor(selector: string, description?: string);
+}
+/**
+ * Helper to create Test Objects easily
+ */
+export declare function el(selector: string, description?: string): TestObject;

package/dist/core/ObjectRepository.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestObject = void 0;
+exports.el = el;
+/**
+ * Represents a Test Object wrapper around Playwright Locators
+ */
+class TestObject {
+    constructor(selector, description = "") {
+        this.selector = selector;
+        this.description = description;
+    }
+}
+exports.TestObject = TestObject;
+/**
+ * Helper to create Test Objects easily
+ */
+function el(selector, description) {
+    return new TestObject(selector, description);
+}

package/dist/core/TestBase.d.ts

@@ -0,0 +1,5 @@
+type FrameworkFixtures = {
+    contextSetup: void;
+};
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & FrameworkFixtures, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
+export { expect } from '@playwright/test';

package/dist/core/TestBase.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expect = exports.test = void 0;
+const test_1 = require("@playwright/test");
+const Keyword_1 = require("./Keyword");
+exports.test = test_1.test.extend({
+    contextSetup: [async ({ page }, use, testInfo) => {
+            // Initialize the Keyword Context before every test
+            Keyword_1.KeywordContext.page = page;
+            Keyword_1.KeywordContext.testInfo = testInfo;
+            await use();
+        }, { auto: true }],
+});
+var test_2 = require("@playwright/test");
+Object.defineProperty(exports, "expect", { enumerable: true, get: function () { return test_2.expect; } });

package/dist/core/TestDecorators.d.ts

@@ -0,0 +1,2 @@
+export declare function TestCase(target: any, propertyKey: string, descriptor: PropertyDescriptor): void | PropertyDescriptor;
+export declare function TestCase(value: Function, context: ClassMethodDecoratorContext): Function;

package/dist/core/TestDecorators.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestCase = TestCase;
+const test_1 = require("@playwright/test");
+/**
+ * Decorator to register a method as a Test Case.
+ * Automatically adds the MethodName annotation to the test info.
+ *
+ * Usage:
+ * class MyTests {
+ *   @TestCase()
+ *   static async MyTest() { ... }
+ * }
+ */
+/**
+ * Decorator to register a method as a Test Case.
+ * Automatically adds the MethodName annotation to the test info.
+ *
+ * Usage:
+ * class MyTests {
+ *   @TestCase
+ *   static async MyTest() { ... }
+ * }
+ */
+/**
+ * Helper to extract the caller file from the stack trace
+ */
+function getCallerFile() {
+    const originalPrepare = Error.prepareStackTrace;
+    Error.prepareStackTrace = (_, stack) => stack;
+    const err = new Error();
+    const stack = err.stack;
+    Error.prepareStackTrace = originalPrepare;
+    if (!stack)
+        return '';
+    const currentFile = __filename;
+    // Find the first frame that is NOT this file
+    for (const frame of stack) {
+        const fileName = frame.getFileName();
+        if (fileName && fileName !== currentFile && !fileName.includes('node_modules') && !fileName.includes('internal/')) {
+            return fileName;
+        }
+    }
+    return '';
+}
+function TestCase(targetOrValue, contextOrKey, descriptor) {
+    // Stage 3: (value, context)
+    if (typeof contextOrKey === 'object' && contextOrKey !== null && 'kind' in contextOrKey) {
+        const originalMethod = targetOrValue;
+        const context = contextOrKey;
+        const methodName = String(context.name);
+        // Capture at definition time
+        const definitionFile = getCallerFile();
+        return async function (...args) {
+            test_1.test.info().annotations.push({ type: 'MethodName', description: methodName });
+            if (definitionFile) {
+                test_1.test.info().annotations.push({ type: 'SourceFile', description: definitionFile });
+            }
+            return await originalMethod.apply(this, args);
+        };
+    }
+    // Legacy: (target, propertyKey, descriptor)
+    let legacyDescriptor = descriptor;
+    if (!legacyDescriptor && typeof contextOrKey === 'string') {
+        legacyDescriptor = Object.getOwnPropertyDescriptor(targetOrValue, contextOrKey);
+    }
+    if (legacyDescriptor) {
+        const originalMethod = legacyDescriptor.value;
+        const methodName = contextOrKey;
+        // Capture at definition time
+        const definitionFile = getCallerFile();
+        legacyDescriptor.value = async function (...args) {
+            test_1.test.info().annotations.push({ type: 'MethodName', description: methodName });
+            if (definitionFile) {
+                test_1.test.info().annotations.push({ type: 'SourceFile', description: definitionFile });
+            }
+            return await originalMethod.apply(this, args);
+        };
+        return legacyDescriptor;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { Web } from './keywords/WebUI';
+export { AIWeb } from './keywords/AIWebUI';
+export { Keyword, KeywordContext } from './core/Keyword';
+export { TestObject, el } from './core/ObjectRepository';

package/dist/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.el = exports.TestObject = exports.KeywordContext = exports.Keyword = exports.AIWeb = exports.Web = void 0;
+var WebUI_1 = require("./keywords/WebUI");
+Object.defineProperty(exports, "Web", { enumerable: true, get: function () { return WebUI_1.Web; } });
+var AIWebUI_1 = require("./keywords/AIWebUI");
+Object.defineProperty(exports, "AIWeb", { enumerable: true, get: function () { return AIWebUI_1.AIWeb; } });
+var Keyword_1 = require("./core/Keyword");
+Object.defineProperty(exports, "Keyword", { enumerable: true, get: function () { return Keyword_1.Keyword; } });
+Object.defineProperty(exports, "KeywordContext", { enumerable: true, get: function () { return Keyword_1.KeywordContext; } });
+var ObjectRepository_1 = require("./core/ObjectRepository");
+Object.defineProperty(exports, "TestObject", { enumerable: true, get: function () { return ObjectRepository_1.TestObject; } });
+Object.defineProperty(exports, "el", { enumerable: true, get: function () { return ObjectRepository_1.el; } });

package/dist/keywords/AIWebUI.d.ts

@@ -0,0 +1,20 @@
+/**
+ * AIWeb: Uses LLM to locate elements based on natural language descriptions.
+ */
+export declare class AIWeb {
+    private static get page();
+    private static get config();
+    private static getOpenAIClient;
+    /**
+     * Finds a locator using AI based on a natural language description.
+     */
+    private static findElement;
+    static click(description: string): Promise<void>;
+    static setText(description: string, text: string): Promise<void>;
+    static verifyText(description: string, expectedText: string): Promise<void>;
+    /**
+     * 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 executeManualSteps(steps: string): Promise<void>;
+}