assuremind 1.0.0

package/docs/STUDIO.md

@@ -0,0 +1,390 @@
+# Assuremind Studio Guide
+
+Assuremind Studio is a browser-based UI for writing tests, running them, reviewing results, and managing self-healing suggestions — all without touching the command line.
+
+---
+
+## Starting the Studio
+
+```bash
+npx assuremind studio
+```
+
+The server starts and your default browser opens at `http://localhost:4400`.
+
+To use a different port:
+
+```bash
+npx assuremind studio --port 5000
+```
+
+To start the server without opening the browser (e.g., on a remote machine):
+
+```bash
+npx assuremind studio --no-open
+```
+
+The Studio port can also be set permanently in `autotest.config.ts`:
+
+```typescript
+export default defineConfig({
+  studioPort: 4400,
+  // ...
+});
+```
+
+---
+
+## Navigation
+
+The sidebar on the left has these pages:
+
+| Icon | Page | Purpose |
+|------|------|---------|
+| 📊 | Dashboard | Run summary, recent results, quick-action links |
+| ✨ | Smart Tests | Generate test suites from user stories or Jira links |
+| ✏️ | Test Editor | Create and manage suites, cases, and steps |
+| ▶️ | Run Config | Configure and launch a test run |
+| 📋 | Reports | Browse historical run results |
+| 🔧 | Variables | Manage test variables and secrets |
+| 🩺 | Self-Healing | Review and apply AI-generated selector fixes |
+| ⚙️ | Settings | Environment, browsers, healing, capture settings |
+| 🌿 | Git Control Center | Branch management, AI commits, push/pull, conflict resolution |
+
+---
+
+## Dashboard
+
+The Dashboard shows at a glance:
+
+- **Pass rate** — percentage of tests passing in the most recent run
+- **Total tests** — suite and case counts
+- **Last run** — time, duration, and status of the most recent run
+- **Healing queue** — number of pending self-healing suggestions
+
+**Quick actions:**
+
+- **Run All** — starts a full run immediately
+- **Open Studio** — returns to this page
+- **Apply Healing** — jumps to the Self-Healing page
+
+While data is loading, animated skeleton cards are shown so the layout never jumps.
+
+---
+
+## Test Editor
+
+### Suite Types
+
+Assuremind supports three suite types:
+
+| Type | Description |
+|------|-------------|
+| **UI** | Standard Playwright browser automation tests. Steps show a blue "UI" badge. |
+| **API** | API-only tests using HTTP request/assertion steps. |
+| **Audit** | Full Playwright automation with built-in Lighthouse non-functional checks. Steps show an amber "Audit" badge. Screenshot, video, and trace are disabled by default. Test files stored in `tests/audit/`. |
+
+### Audit Suites
+
+Audit suites run exactly like UI suites (full Playwright automation) but add non-functional quality checks via Google Lighthouse.
+
+**Audit Flag on Steps**
+
+In Audit suites, each step has a `⚡ Audit` button. Clicking it marks that step as a Lighthouse checkpoint:
+- When a marked step runs, Lighthouse audits `page.url()` at that point in the test
+- Click `⚡ Audit` to mark, then confirm with **✓** to save or **✗** to cancel
+- If no steps are marked, Lighthouse is skipped entirely even in Audit suites
+
+**Non-Functional Checks**
+
+Each test case in an Audit suite has a **Non-Functional Checks** section with three checkboxes:
+- **⚡ Performance** — Lighthouse Performance score
+- **♿ Accessibility** — Lighthouse Accessibility score
+- **🔍 SEO** — Lighthouse SEO score
+
+If all three are unchecked, Lighthouse is skipped for that case. A warning is shown if none are selected.
+
+**Lighthouse Score Thresholds**
+
+| Range | Rating | Effect |
+|-------|--------|--------|
+| 0–49 | Poor (red) | Test case **FAILS** |
+| 50–89 | Needs Work (amber) | Warning only |
+| 90–100 | Good (green) | Pass |
+
+### Creating a Suite
+
+1. Click the **+ New Suite** button (top right)
+2. Enter a **name** — this becomes the folder name under `tests/` (e.g., "Login Tests" → `tests/login-tests/`); Audit suites use `tests/audit/`
+3. Choose a **suite type**: UI, API, or Audit
+4. Optionally add a **description** and **tags**
+5. Click **Create**
+
+### Creating a Test Case
+
+1. Select a suite from the left panel
+2. Click **+ New Case**
+3. Enter a **name**, **priority** (`critical`, `high`, `medium`, `low`), and optional **tags**
+4. Click **Create**
+
+### Adding Steps
+
+1. Open a case by clicking it
+2. Click **+ Add Step** at the bottom of the step list
+3. Type a plain-English instruction, e.g.:
+   - `Go to the login page`
+   - `Enter "admin@example.com" in the email field`
+   - `Click the Login button`
+   - `Verify the page title contains "Dashboard"`
+4. Press **Enter** or click the checkmark
+
+**Tips for writing good instructions:**
+- Be specific about what to interact with: `Click the blue Submit button` rather than just `Submit`
+- Use quotes for literal values: `Enter "admin@example.com" in the email field`
+- Reference variables with double-braces: `Enter "{{ADMIN_EMAIL}}" in the email field`
+- Include assertions: `Verify that the success banner is visible`
+
+### Generating Code
+
+After adding steps, click **Generate Code** (or **Generate** on an individual step) to have the AI write the Playwright code.
+
+- Steps with **green code** icons have generated code
+- Steps with **grey code** icons are pending generation
+- Click any step's code icon to see or edit the generated code
+
+**The AI only runs once per unique (instruction, URL pattern) pair.** Subsequent runs use the cached code, making them free and instant.
+
+### Reordering Steps
+
+Drag the ≡ handle on the left of any step to reorder it. The order numbers update automatically.
+
+### Deleting
+
+- Delete a step: click the **×** on the right of the step row
+- Delete a case: open the case, click **⋮** → **Delete Case**
+- Delete a suite: select the suite, click **⋮** → **Delete Suite**
+
+Deletions are permanent. There is no undo in the Studio — use Git to recover.
+
+---
+
+## Story Generator
+
+Generate an entire test suite from a plain-English user story:
+
+1. Navigate to **Story Generator**
+2. Type your story in the text area:
+   ```
+   As a user I want to reset my password so I can regain access to my account.
+   Steps:
+   - I click "Forgot password" on the login page
+   - I enter my email address
+   - I receive a reset email
+   - I click the reset link
+   - I enter a new password and confirm it
+   - I am redirected to the login page with a success message
+   ```
+3. Optionally provide a **Suite Name** (AI generates one if blank)
+4. Click **Generate Suite**
+
+The AI creates:
+- A suite directory with `suite.json`
+- One or more test case files with steps
+- Playwright code for each step
+
+The generated files appear in the Test Editor immediately.
+
+---
+
+## Run Config
+
+Configure and start a test run without the command line:
+
+1. Navigate to **Run Config**
+2. Choose a **scope**:
+   - All suites
+   - Specific suite (dropdown)
+   - By tag (text input)
+   - Specific test (text input)
+3. Select **browsers**: Chromium, Firefox, WebKit (multi-select)
+4. Set **parallel workers** (slider, 1–8)
+5. Toggle **Headed mode** to watch the browser during the run
+6. Toggle **Self-Healing** on/off for this run
+7. Optionally select a **Device** for emulation (see below)
+8. Click **Start Run**
+
+A live progress panel shows test results as they complete. The WebSocket connection streams updates in real time — no page refresh needed.
+
+When the run finishes, you are offered a link to the full report.
+
+### Device Emulation
+
+The **Device Emulation** card appears below the Browsers card. It lets you emulate a real mobile or tablet device using Playwright's built-in device descriptors. No manual viewport configuration needed — selecting a device automatically applies the correct viewport, user-agent, device pixel ratio, and touch/mobile flags.
+
+**Categories:**
+
+| Tab | What it shows |
+|-----|---------------|
+| **All** | All presets |
+| **Desktop** | Viewport-only presets: 1920×1080, 1440×900, 1366×768, 1280×720, 1024×768 |
+| **Mobile** | iPhone 15 Pro/15/14/SE, Pixel 7/5, Galaxy S9+/S8 |
+| **Tablet** | iPad Pro 11″, iPad (gen 7), iPad Mini, Galaxy Tab S4 |
+
+**How to use:**
+1. Click a device card — it highlights in teal and shows a device pill in the card header
+2. Click the **×** in the header or click **No Emulation** to clear
+3. An amber warning appears if a mobile/tablet device is selected without Chromium — mobile emulation works best on Chromium
+
+**In Reports:** each case row shows a teal device badge (📱 / 🖥️ / tablet icon) when the run used device emulation.
+
+**Equivalent CLI flag:** `--device "iPhone 15 Pro"`
+
+---
+
+## Reports
+
+Browse all historical run results:
+
+- Each run shows: status badge (✅ / ❌), date/time, duration, pass/fail/skip counts
+- Click a run to see the **full result tree**: Suite → Case → Step
+- Each step shows: status, duration, generated code, and screenshot (on failure)
+- Failed steps show the error message and a screenshot thumbnail
+
+### Lighthouse Results (Audit Suites)
+
+For Audit suite cases that have Lighthouse data, three tab buttons appear on the case row:
+- **⚡ Speed** — Performance score
+- **♿ A11y** — Accessibility score
+- **🔍 SEO** — SEO score
+
+Score colors follow the threshold rules: red for Poor (< 50), amber for Needs Work (50–89), green for Good (90+). A case row is highlighted red when any score is Poor (< 50).
+
+**Allure Integration**: Audit cases produce three separate HTML report attachments per category — Performance Report, Accessibility Report, and SEO Report. The Allure test status is set to FAILED if any Lighthouse score is below 50.
+
+**Filter and sort:**
+- Use the search box to filter by run ID or date
+- Use the **Status** filter to show only failed runs
+- Use **Limit** to control how many runs are displayed (default: 20)
+
+---
+
+## Variables
+
+Manage variables that can be referenced in step instructions:
+
+### Global variables
+
+Available in all test runs regardless of environment.
+
+1. Click **+ Add Variable**
+2. Enter a **key** (e.g., `ADMIN_EMAIL`) and **value**
+3. Toggle **Secret** to mask the value in logs and UI
+4. Click **Save**
+
+### Environment-specific variables
+
+Variables can be overridden per environment (`dev`, `staging`, `prod`).
+
+1. Select the environment tab
+2. Add variables that override globals for that environment
+3. Use `--env <name>` when running to load the overrides
+
+### Using variables in steps
+
+Reference any variable in a step instruction using double-braces:
+
+```
+Enter "{{ADMIN_EMAIL}}" in the email field
+Navigate to "{{BASE_URL}}/login"
+```
+
+Variables are interpolated into the generated Playwright code at run time.
+
+---
+
+## Self-Healing
+
+When a test step fails and the AI generates a healed selector, it appears here for review.
+
+### Healing event list
+
+Each event shows:
+- **Suite / Case / Step** — where the failure occurred
+- **Original code** — the code that failed
+- **Healed code** — the AI's suggested fix
+- **Healing level** — 1–6 (higher = more aggressive strategy)
+- **Status** — `pending`, `accepted`, or `rejected`
+
+### Reviewing suggestions
+
+- Click **Accept** to apply the healed code to the `.test.json` file
+- Click **Reject** to dismiss the suggestion (original code is kept)
+- Click **Accept All** to accept every pending suggestion in one click
+
+Accepted changes are written immediately to the test files. The next run will use the healed code.
+
+### Healing statistics
+
+The top of the page shows:
+- Total heals applied this month
+- Daily budget remaining (based on `healing.dailyBudget` in config)
+- Most healed suite and case
+
+---
+
+## Settings
+
+Edit `autotest.config.ts` from the browser:
+
+| Setting | Description |
+|---------|-------------|
+| Base URL | The URL of the application under test |
+| Browsers | Which browsers to use by default |
+| Headless | Run headless by default |
+| Timeout | Step timeout in milliseconds |
+| Retries | Number of retries on failure |
+| Parallel | Number of parallel workers |
+| Screenshot | `on`, `off`, or `on-failure` |
+| Video | `on`, `off`, or `on-failure` |
+| Trace | `on`, `off`, or `on-failure` |
+| Healing enabled | Master switch for self-healing |
+| Healing max level | Maximum healing cascade level (1–6) |
+| Daily budget | Maximum AI spend on healing per day (USD) |
+| Studio port | Port for the Studio server |
+
+Changes are saved immediately to both `autotest.config.json` and `autotest.config.ts`.
+
+---
+
+## WebSocket Live Updates
+
+The Studio uses a WebSocket connection (`ws://localhost:<port>/ws`) to receive live updates:
+
+| Event | Description |
+|-------|-------------|
+| `run:complete` | A run has finished — results available |
+| `run:error` | A run failed to start |
+
+The connection indicator in the top bar shows:
+- **Green dot** — connected
+- **Grey dot** — disconnected (Studio server not running)
+
+---
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl+S` | Save current changes |
+| `Ctrl+Enter` | Generate code for selected step |
+| `Ctrl+R` | Run all tests |
+| `Esc` | Close modal / cancel edit |
+
+---
+
+## Tips
+
+- **Browser auto-refresh** — the Studio does not auto-refresh when test files are edited externally (e.g., by `apply-healing`). Click the refresh icon or press `F5`.
+- **Multiple windows** — you can open the Studio in multiple browser tabs. All tabs receive WebSocket events simultaneously.
+- **Remote access** — start with `--no-open` on the server and open `http://<server-ip>:4400` in your local browser. Make sure the port is reachable.
+- **Stopping the server** — press `Ctrl+C` in the terminal where `studio` is running.

package/package.json

@@ -0,0 +1,118 @@
+{
+  "name": "assuremind",
+  "version": "1.0.0",
+  "description": "AI-powered codeless UI & API automation framework",
+  "author": "Deepak Hiremath",
+  "license": "MIT",
+  "bin": {
+    "assuremind": "./dist/cli/index.js"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "templates/",
+    "ui/dist/",
+    "docs/",
+    "README.md",
+    "CONTRIBUTING.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "keywords": [
+    "testing",
+    "automation",
+    "playwright",
+    "ai",
+    "codeless",
+    "no-code",
+    "test-automation",
+    "qa",
+    "self-healing",
+    "claude",
+    "openai",
+    "gemini",
+    "ui-testing"
+  ],
+  "scripts": {
+    "prepare": "npm run build",
+    "build": "npm run build:lib && npm run build:ui",
+    "build:lib": "tsup",
+    "build:ui": "cd ui && npm install --ignore-scripts && npm run build",
+    "dev": "tsup --watch",
+    "dev:ui": "cd ui && npm run dev",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.30.0",
+    "@aws-sdk/client-bedrock-runtime": "^3.679.0",
+    "@fastify/cors": "^11.2.0",
+    "@fastify/static": "^9.0.0",
+    "@fastify/websocket": "^11.2.0",
+    "@google/generative-ai": "^0.21.0",
+    "@playwright/test": "^1.47.0",
+    "allure-commandline": "^2.38.1",
+    "allure-js-commons": "^3.0.0",
+    "allure-playwright": "^3.0.0",
+    "chalk": "^5.3.0",
+    "chokidar": "^4.0.0",
+    "commander": "^12.1.0",
+    "date-fns": "^4.1.0",
+    "dotenv": "^16.4.0",
+    "fast-glob": "^3.3.0",
+    "fastify": "^5.8.4",
+    "fs-extra": "^11.2.0",
+    "inquirer": "^9.3.0",
+    "js-yaml": "^4.1.1",
+    "lighthouse": "^13.0.3",
+    "lodash-es": "^4.17.21",
+    "nanoid": "^5.0.0",
+    "open": "^10.1.0",
+    "openai": "^4.67.0",
+    "ora": "^8.0.1",
+    "pino": "^9.4.0",
+    "pino-pretty": "^11.2.0",
+    "playwright": "^1.47.0",
+    "simple-git": "^3.33.0",
+    "uuid": "^10.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/lodash-es": "^4.17.0",
+    "@types/node": "^22.7.0",
+    "@types/uuid": "^10.0.0",
+    "@types/ws": "^8.5.0",
+    "@typescript-eslint/eslint-plugin": "^8.8.0",
+    "@typescript-eslint/parser": "^8.8.0",
+    "@vitest/coverage-v8": "^2.1.0",
+    "docx": "^9.6.1",
+    "eslint": "^9.12.0",
+    "prettier": "^3.3.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}