@letitbexai_root/lexxit-automation-framework 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,282 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Playwright Test Execution Framework
+
+A Node.js + TypeScript framework that executes Playwright-based test sets defined entirely in JSON, exposed through a REST API, with a live polling dashboard to monitor execution in real time.
+
+## Tech Stack
+
+- Node.js 22, TypeScript
+- Express.js (REST API)
+- Playwright (Chromium, Firefox, Edge)
+- In-memory execution store (no database)
+
+## Setup
+
+```bash
+npm install
+npx playwright install
+npm run dev
+```
+
+The server starts on port `5501`. On startup, the console prints the API URL and a list of available endpoints.
+
+## Project Structure
+
+```
+new_Framework/
+├── src/
+│   ├── api/
+│   │   └── server.ts            # Express server, all routes
+│   ├── runner/
+│   │   └── testRunner.ts        # Orchestrates a full test set (sequential/parallel)
+│   ├── executor/
+│   │   ├── scriptExecutor.ts    # Runs one test script (all its steps)
+│   │   ├── stepExecutor.ts      # Runs one step, routes to the correct handler
+│   │   ├── mapping.ts           # Parses step_script strings into function + args
+│   │   └── functionMap.ts       # Maps step_script function names to handler methods
+│   ├── actions/
+│   │   ├── browserManager.ts    # openBrowser, closeBrowser, navigation, video
+│   │   ├── textHandler.ts       # enterText, getText, verifyText, etc.
+│   │   ├── clickHandler.ts      # click, doubleClick, rightClick, hover, etc.
+│   │   ├── checkboxHandler.ts   # check, uncheck, toggle, verifyChecked, etc.
+│   │   ├── radiobuttonHandler.ts# select, selectByValue, selectByLabel, etc.
+│   │   └── dropdownHandler.ts   # native/combobox/multiselect dropdown actions
+│   ├── utils/
+│   │   ├── locatorService.ts    # Resolves an element from a list of xpath locators
+│   │   └── waitConditions.ts    # waitForVisible, waitForTextChange, etc.
+│   ├── validator/
+│   │   └── validator.ts         # Validates testset/testscript/step payload shapes
+│   ├── store/
+│   │   └── executionStore.ts    # In-memory live execution state, keyed by execution_id
+│   └── types/
+│       └── types.ts             # All shared TypeScript interfaces
+├── public/
+│   └── dashboard.html           # Live polling dashboard UI
+├── videos/                      # Saved test recordings (when video_enabled)
+├── tsconfig.json
+└── package.json
+```
+
+## How a Request Flows
+
+1. `POST /execute` receives the full test set JSON.
+2. The payload is validated in three layers: testset, testscript, and step.
+3. If valid, an `execution_id` (UUID) is generated and the response is returned **immediately** — the test set runs in the background.
+4. If `open_dashboard: true`, the dashboard auto-opens in your default browser (only once per server session).
+5. The dashboard polls the server and shows live step-by-step progress.
+6. Once finished, the full result (same shape as a traditional synchronous response) becomes available under `final_result`.
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/` | Lists all available endpoints |
+| POST | `/execute` | Submit a test set for execution |
+| GET | `/status/:execution_id` | Live status + final result of one execution |
+| GET | `/executions` | List all executions, latest first |
+| GET | `/dashboard` | Live dashboard UI |
+
+### POST /execute
+
+Request body is the full test set JSON (see Request Format below).
+
+Response (returned immediately, before execution finishes):
+
+```json
+{
+  "status": "started",
+  "execution_id": "a1b2c3d4-...",
+  "dashboard_url": "http://localhost:5501/dashboard?execution_id=a1b2c3d4-...",
+  "result_url": "http://localhost:5501/status/a1b2c3d4-..."
+}
+```
+
+If validation fails, responds with `400` and an `errors` array describing every problem found, tagged by level (`testset`, `testscript`, or `step`).
+
+### GET /status/:execution_id
+
+Returns the live execution state. While running, `scripts[].steps[]` update in real time (`pending` → `running` → `pass`/`fail`/`skip`). Once finished, `final_result` is populated with the complete original-style response (status, full step results, summary).
+
+```json
+{
+  "execution_id": "a1b2c3d4-...",
+  "test_set_name": "E2E Smoke Suite",
+  "status": "pass",
+  "start_time": "2026-06-17 10:00:00",
+  "end_time": "2026-06-17 10:00:42",
+  "scripts": [
+    {
+      "test_script_uid": "d42bbbd5-...",
+      "test_case_name": "asdfasdf444",
+      "status": "pass",
+      "steps": [
+        {
+          "step_name": "Enter 'sdf' into 'First name'",
+          "status": "pass",
+          "expected_result": "'sdf' entered into 'First name' successfully",
+          "comments": "'sdf' entered into 'First name' successfully",
+          "duration": "0 seconds"
+        }
+      ]
+    }
+  ],
+  "final_result": {
+    "status": "pass",
+    "results": [ /* ... full TestScriptResult objects ... */ ],
+    "summary": {
+      "test_set_name": "E2E Smoke Suite",
+      "total_scripts": 1,
+      "passed": 1,
+      "failed": 0,
+      "duration": "12 seconds",
+      "start_time": "2026-06-17 10:00:00",
+      "end_time": "2026-06-17 10:00:12"
+    }
+  }
+}
+```
+
+## Request Format
+
+A test set request has three nested levels: testset, testscript, and step.
+
+```json
+{
+  "test_set_name": "E2E Smoke Suite",
+  "open_dashboard": true,
+  "parallel": false,
+  "stop_on_failure": true,
+  "video_enabled": true,
+  "exec_mode": { "mode": "medium", "delay_ms": 1000 },
+  "scripts": [
+    {
+      "test_script_uid": "d42bbbd5-f50f-4b71-a119-ef7294eab861",
+      "test_case_name": "asdfasdf444",
+      "voice_enabled": false,
+      "app_id": "1b040097-495d-4428-84d1-bd31ecc97e93",
+      "browser": "edge",
+      "headless": false,
+      "screenshot_mode": "on_failure",
+      "stop_on_failure": true,
+      "steps": [
+        {
+          "step_name": "Open edge",
+          "step_script": "tSetup.openBrowser('edge')",
+          "label": ""
+        },
+        {
+          "step_name": "Navigate to URL",
+          "step_script": "tSetup.navigateToURL('https://example.com')",
+          "label": ""
+        },
+        {
+          "label": "First name",
+          "locators": [
+            "//input[@id='fname']",
+            "//input[@id='fname' and @name='fname']"
+          ],
+          "obj_uid": "066d39cd-b378-40c0-aa7f-e80e6c55a530",
+          "page_uid": null,
+          "step_name": "Enter 'sdf' into 'First name'",
+          "step_script": "tSetup.enterText('xpath', '//input[@id=\"fname\"]', 'sdf')",
+          "value": "sdf"
+        },
+        {
+          "step_name": "Close Browser",
+          "step_script": "tSetup.closeBrowser()",
+          "label": ""
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Testset-level fields
+
+| Field | Type | Description |
+|-------|------|--------------|
+| `test_set_name` | string | Display name for the test set |
+| `open_dashboard` | boolean | Auto-opens the dashboard in your browser when execution starts |
+| `parallel` | boolean | Run scripts in parallel (max 10 concurrent) instead of sequentially |
+| `stop_on_failure` | boolean | Reserved for testset-level stop behavior |
+| `video_enabled` | boolean | Records a `.webm` video per script (forced `false` in `fast` exec mode) |
+| `exec_mode` | object, optional | `{ mode: 'fast' \| 'medium' \| 'slow', delay_ms?: number }`. Defaults to `fast` if omitted |
+| `scripts` | array | One or more test scripts |
+
+### Testscript-level fields
+
+| Field | Type | Description |
+|-------|------|--------------|
+| `test_script_uid` | string | Unique ID for this script |
+| `test_case_name` | string | Display name |
+| `app_id` | string | Application identifier |
+| `browser` | `chromium` \| `firefox` \| `edge` | Browser to launch |
+| `headless` | boolean | Run headless or headed |
+| `screenshot_mode` | `on_failure` \| `always` \| `never` | Reserved for screenshot behavior |
+| `stop_on_failure` | boolean | Skip remaining steps in this script once one fails |
+| `steps` | array | Ordered list of steps to execute |
+
+### Step-level fields
+
+| Field | Type | Description |
+|-------|------|--------------|
+| `step_name` | string | Display name for the step |
+| `step_script` | string | The action to run, e.g. `tSetup.enterText('id','fname','mahesh')` |
+| `label` | string | Human-readable name of the target element, used in result messages |
+| `locators` | string[] | List of xpath locators tried together (first visible match wins) |
+| `obj_uid`, `page_uid` | string \| null | Optional metadata passed through to results |
+
+## Execution Modes
+
+| Mode | Behavior |
+|------|----------|
+| `fast` (default) | No delay between steps. `video_enabled` is forced to `false` regardless of the request value |
+| `medium` | Waits `delay_ms` (default 1000ms if not provided) between steps. Respects `video_enabled` |
+| `slow` | Waits `delay_ms` (default 3000ms if not provided) between steps. Respects `video_enabled` |
+
+`delay_ms` can be passed explicitly inside `exec_mode` to override the defaults for `medium`/`slow`.
+
+## Step Script Reference
+
+Steps are written as `tSetup.<functionName>(args...)`. The framework parses this string and routes it to the matching handler. Currently mapped functions:
+
+| Function | Handler |
+|----------|---------|
+| `openBrowser`, `closeBrowser`, `navigateToURL`, `navigateBack`, `navigateForward`, `refreshPage`, `getTitle`, `getCurrentURL` | Browser Manager |
+| `enterText`, `typeText`, `clearText`, `getInputValue`, `appendText`, `setInputValue`, `verifyText`, `verifyValue`, `getText` | Text Handler |
+| `clickElement`, `doubleClick`, `rightClick`, `hover` | Click Handler |
+| `check_checkbox`, `uncheck_checkbox`, `verifyChecked`, `verifyUnchecked`, `verifyEnabled`, `verifyDisabled`, `verifyVisible`, `verifyHidden` | Checkbox Handler |
+| `selectRadioButton` | Radiobutton Handler |
+| `selectDropdown` | Dropdown Handler |
+
+Functions not yet mapped (e.g. `dragAndDrop`, `file_upload`, `enterTextInFrame`, `verifyElementCount`, `verifyAttribute`, `acceptAlert`, `dismissAlert`, `getAlertText`, `verifyTitle`, `verifyURL`, `clickByJS`) are documented as comments in `functionMap.ts` for future implementation.
+
+## Locator Resolution
+
+Each step can provide multiple xpath locators as fallbacks. They're combined into a single OR-expression and the first visible, attached match is used. If the first locator in the list wasn't the one that matched, the step's `comments` field notes which position and xpath actually resolved — useful for cleaning up brittle locators over time.
+
+## Live Dashboard
+
+Visit `http://localhost:5501/dashboard` (or let it auto-open via `open_dashboard: true`).
+
+- Left navigation lists all executions, most recent at the top.
+- Selecting an execution shows each script and its steps.
+- Steps show a spinner while running, then a pass/fail/skip badge.
+- Click any step row to expand and see its expected result and comments.
+- The dashboard polls `/executions` every 3 seconds and `/status/:execution_id` every 2 seconds — no manual refresh needed.
+
+## Step Statuses
+
+| Status | Meaning |
+|--------|---------|
+| `pending` | Not yet started (dashboard-only state) |
+| `running` | Currently executing (dashboard-only state) |
+| `pass` | Completed successfully |
+| `fail` | Failed |
+| `skip` | Skipped because an earlier step in the same script failed (when `stop_on_failure: true`) |
+
+## Notes
+
+- Videos are saved to the `videos/` folder, named `<test_script_uid>_<timestamp>.webm`.
+- Parallel execution runs scripts in batches of up to 10 concurrently; batches are processed one after another.
+- The execution store is in-memory only — restarting the server clears all execution history.