assuremind 1.2.1 → 1.3.0

package/README.md

@@ -23,10 +23,13 @@ Describe tests in plain English. AI generates Playwright code. Run anywhere.
 | **Device emulation** | iPhone, Pixel, iPad, Galaxy — full Playwright device descriptors from UI or `--device` CLI flag |
 | **Studio UI** | Browser-based editor, run dashboard, reports, healing review, git control center — with dark mode |
 | **RAG memory** | AI learns from every run — retrieves similar past steps & healing fixes for smarter generation |
-| **Test Recorder** | Record tests by clicking in a real browser — locators verified against Playwright's accessibility tree, zero AI cost |
+| **Test Recorder** | Record tests by clicking in a real browser — locators verified against Playwright's accessibility tree, zero AI cost. Recorder + AI both handle iframes (click & fill), Shadow DOM, JS alerts, and keyboard actions |
 | **Cost-optimised** | Template engine + code cache + RAG handle ~80% of steps with zero AI calls |
 | **CI-ready** | `npx assuremind run --all --ci` — exit code 0/1, works with any pipeline |
 | **File-based** | Plain JSON storage, fully Git-friendly, no database |
+| **Faker Data** | 100+ @faker-js/faker generators across 16 categories — random emails, names, addresses, sequences — no code, no stale data |
+| **Visual regression** | Pixel-diff screenshot comparison with baselines — approve/reject visual changes in Studio |
+| **CI/CD integration** | Quality gates, PR comments (GitHub/GitLab), Slack/Teams notifications |
 
 ---
 
@@ -38,7 +41,17 @@ npx assuremind init        # folders, config, Playwright browsers
 npx assuremind studio      # opens http://localhost:4400
 ```
 
-> **Requirements:** Node.js >= 18 · macOS / Linux / Windows
+### System Requirements
+
+| | Minimum | Recommended |
+|---|---|---|
+| **Node.js** | 18 LTS | 20 LTS or newer |
+| **OS** | macOS / Linux / Windows 10+ | — |
+| **RAM** | 4 GB | 8 GB+ |
+| **Disk** | ~2 GB (app + Playwright browsers) | 5 GB+ |
+| **Java** | — | JDK 17+ — only for Allure HTML reports ([adoptium.net](https://adoptium.net)) |
+
+`npx assuremind init` installs the Playwright browsers. Using a **cloud AI provider** (Anthropic, OpenAI, Gemini, …) needs only an API key and the specs above. Running a **local model via Ollama** has heavier requirements — see below.
 
 ### Configure AI Provider
 
@@ -53,6 +66,45 @@ ANTHROPIC_MODEL=claude-sonnet..   OPENAI_MODEL=gpt-4o              GOOGLE_MODEL=
 
 See `.env.example` for all 12 providers including Gemini, OpenAI, Anthropic, Ollama (local/free), etc.
 
+### Local & Free — Ollama
+
+Run models entirely on your own machine (no API key, no cost). AssureMind uses the model to turn
+plain-English steps into Playwright code, so a **code-tuned model with strong instruction-following**
+works best.
+
+```bash
+# 1. Install Ollama → https://ollama.com/download
+ollama serve                       # starts the server on http://localhost:11434
+ollama pull qwen2.5-coder:7b       # 2. pull the recommended model
+```
+
+```bash
+# 3. .env
+AI_PROVIDER=ollama
+OLLAMA_MODEL=qwen2.5-coder:7b
+OLLAMA_BASE_URL=http://localhost:11434
+AI_TIMEOUT=120                     # local inference is slower than cloud APIs
+```
+
+**Recommended models (by hardware):**
+
+| Hardware | Model | Notes |
+|----------|-------|-------|
+| 16 GB+ RAM, GPU 8 GB+ VRAM | `qwen2.5-coder:14b` | Highest accuracy — best for complex steps / iframes |
+| 16 GB RAM (GPU optional) ⭐ | `qwen2.5-coder:7b` | **Best balance** of quality & speed for this task |
+| 8 GB RAM, no GPU | `llama3.2` (3B) / `qwen2.5-coder:3b` | Usable; good for simpler steps |
+| ≤4–6 GB RAM | `llama3.2:1b` / `phi3:mini` | Lightweight; navigation & clicks only |
+
+**Ollama system requirements:**
+
+- **RAM is the floor** — a model needs roughly its file size **+ ≈2 GB free**. A 7B model (≈4.7 GB)
+  wants **8 GB free RAM minimum, 16 GB comfortable**; a 14B model wants **≈16 GB+**.
+- **GPU is optional but transformative** — CPU-only works (hence `AI_TIMEOUT=120`), but a GPU with
+  **8 GB+ VRAM** (NVIDIA CUDA / Apple Silicon / modern AMD) makes 7B models fast. Apple Silicon (M-series) is excellent thanks to unified memory.
+- **Disk** — a few GB per model; keep **10–20 GB free** if trying several.
+- **Tips** — enable **MCP** (Settings → live page snapshots) for far more accurate locators with local
+  models. Avoid `deepseek-r1` here: its `<think>` reasoning output is slow and pollutes generated code.
+
 ---
 
 ## CLI
@@ -88,7 +140,7 @@ Full reference → [docs/CLI-REFERENCE.md](docs/CLI-REFERENCE.md)
 
 Start with `npx assuremind studio` — opens at `http://localhost:4400`.
 
-**Dashboard** · **Smart Tests** · **Test Editor** · **Run Config** · **Reports** · **Variables** · **Self-Healing** · **Step Library** · **Git Control** · **Settings** · **Docs**
+**Dashboard** · **Smart Tests** · **Test Editor** · **Run Config** · **Reports** · **Variables** · **Self-Healing** · **Step Library** · **Faker Data** · **CI/CD** · **Git Control** · **Settings** · **Docs**
 
 Full walkthrough → [docs/STUDIO.md](docs/STUDIO.md)
 
@@ -118,12 +170,17 @@ Click **Record** in the Test Editor, perform your actions, and stop. Each intera
 
 ### How it works
 
+> Available for **UI** and **Audit** suites only (not API suites).
+
 1. A headed Chromium browser opens your app's URL
-2. Every click, fill, and navigation is captured in real time — **including inside iframes**
+2. Every click, fill, navigation, and keyboard action is captured in real time — **including inside iframes and shadow roots**
 3. Locators are resolved against Playwright's **accessibility tree** — the recorder tries 6 strategies (data-testid, getByRole, getByLabel, getByPlaceholder, getByText, CSS) and verifies each with `count() === 1`
 4. **Iframe-aware** — elements inside iframes automatically generate `page.frameLocator('#iframe').getByRole(...)` code with the correct frame chain
-5. Assertions via keyboard shortcuts: **Shift+Click** (element visible), **Ctrl+Shift+U** (URL), **Ctrl+Shift+T** (page title)
-6. On stop, each action is added as a step with **pre-generated Playwright code** — no AI call needed
+5. **Shadow DOM** — `composedPath()[0]` pierces shadow roots; generates `host >> inner` pierce locators automatically
+6. **JS dialogs** — alerts/confirms are auto-accepted during recording; `page.once('dialog', ...)` is prepended to the triggering step's code
+7. **Keyboard** — Tab, Shift+Tab, arrows, Enter, Escape, Ctrl+A, and Space on buttons are all captured
+8. Assertions via keyboard shortcuts: **Shift+Click** (element visible), **Ctrl+Shift+U** (URL), **Ctrl+Shift+T** (page title)
+9. On stop, each action is added as a step with **pre-generated Playwright code** — no AI call needed
 
 ### What makes it stand out vs other recorders
 
@@ -131,7 +188,10 @@ Click **Record** in the Test Editor, perform your actions, and stop. Each intera
 |---------|-------------|-------------------|---------------------|
 | Locator quality | CSS/XPath | Good | Best — 6 strategies, verified against live page |
 | Accessibility tree | No | Partial | Full — every locator checked via Playwright API |
-| **Iframe support** | Partial | Manual | **Auto** — detects iframes, generates `frameLocator()` code |
+| **Iframe support** | Partial | Manual | **Full** — detects iframes, generates `frameLocator()` code — click **and** fill both work |
+| **Shadow DOM** | No | Limited | `>>` pierce combinator — elements inside shadow roots are reachable |
+| **JS Alert handling** | No | No | `page.once('dialog', ...)` registered automatically before triggering action |
+| **Keyboard actions** | No | No | `page.keyboard.press()` / `.type()` for keys, shortcuts, and character input |
 | Assertions | Manual | Manual | Shift+Click (hard), Ctrl+Shift+Click (soft), URL & title shortcuts |
 | Plain-English steps | No | No | Yes — human-readable instructions auto-generated |
 | Self-healing after | No | No | Yes — 5-level AI healing cascade |
@@ -149,7 +209,10 @@ Click **Record** in the Test Editor, perform your actions, and stop. Each intera
 | Assertions are hard to write | Shift+Click for hard, Ctrl+Shift+Click for soft, Ctrl+Shift+U for URL, Ctrl+Shift+T for title |
 | Hard vs soft assertions | Soft assertions (`expect.soft()`) let the test continue — all failures reported at end |
 | Recorded tests are fragile | 6-strategy locator resolution + post-run 5-level self-healing |
-| Apps use iframes (SAP, Salesforce) | Auto-detects iframe context, generates `frameLocator()` chains — no manual frame handling |
+| Apps use iframes (SAP, Salesforce) | Recorder auto-detects iframe context, generates `frameLocator()` chains — **click and fill** both work |
+| Shadow DOM / Web Components | Recorder pierces shadow roots via `composedPath()`, generates `>>` locators automatically |
+| JavaScript alerts & popups | Recorder auto-accepts dialogs; `page.once('dialog', ...)` prepended to triggering step |
+| Keyboard interactions | Recorder captures Tab, Shift+Tab, arrows, Ctrl+A, Enter, Escape, and Space |
 
 ---
 
@@ -243,6 +306,66 @@ Exit code `0` = all passed · `1` = failures.
 
 ---
 
+## Enterprise Features
+
+### Faker Data
+
+100+ @faker-js/faker generators across 16 categories — generate realistic random data without code.
+
+| Generator | Example output |
+|-----------|---------------|
+| `person.fullName` | Sarah Johnson |
+| `internet.email` | sarah.johnson@gmail.com |
+| `phone.number` | +1-555-123-4567 |
+| `finance.amount` | 249.99 |
+| `location.city` | San Francisco |
+| Sequence `USER-{n}` | USER-001, USER-002, USER-003 |
+
+Browse by category or search, select multiple tokens at once — selected tokens appear as removable chips, and clicking "Insert N tokens" inserts them all comma-separated (e.g. `{{FAKE_PERSON_FIRSTNAME}}, {{FAKE_PERSON_LASTNAME}}, {{FAKE_INTERNET_EMAIL}}`). Great for form filling. Tokens resolve to fresh random values on every test run — no more "email already exists" failures.
+
+### Visual Regression
+
+Pixel-perfect screenshot comparison — catch UI changes that functional tests miss. Configure in **Settings** → Visual Regression. Review diffs in **Reports** → Visual Diffs tab.
+
+1. Enable in **Settings** → Visual Regression, then toggle the **Eye icon** on any step in the Test Editor
+2. First run captures **baseline** screenshots (committed to git)
+3. Subsequent runs **compare** pixel-by-pixel using `pixelmatch`
+4. Diff > threshold → step **fails** with highlighted diff image
+5. Review in **Reports** → Visual Diffs → **Approve** (update baseline) or **Reject** (it's a bug)
+
+```
+baselines/                          # committed to git
+├── login-suite/login-test/
+│   ├── step-3-chromium-1920x1080.png
+│   └── step-3-firefox-1920x1080.png
+results/visual-diffs/{runId}/       # gitignored, per-run
+├── step-3-baseline.png
+├── step-3-actual.png
+└── step-3-diff.png                 # red highlights
+```
+
+### CI/CD Integration
+
+Quality gates, PR comments, and notifications — configured from Studio, executed in pipelines.
+
+| Feature | What it does |
+|---------|-------------|
+| **Quality gates** | Set min pass rate (95%), max duration, required tags — pipeline fails if gate fails |
+| **PR comments** | Auto-post test results as GitHub PR comment or GitLab MR note |
+| **Notifications** | Slack, Teams, Email, custom webhook — trigger on failure, every run, or healing events |
+
+```yaml
+# GitHub Actions — full integration
+- name: Run tests
+  env:
+    AI_PROVIDER: anthropic
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+  run: npx assuremind run --all --ci
+  # Quality gate auto-evaluates, PR comment auto-posts, Slack notifies on failure
+```
+
+---
+
 ## Documentation
 
 | Resource | Location |
@@ -253,6 +376,7 @@ Exit code `0` = all passed · `1` = failures.
 | Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) |
 | All AI providers | `.env.example` |
 | Built-in docs | Studio → **Docs** page |
+| Enterprise features | Studio → **Faker Data**, **CI/CD** pages; Visual Regression in **Settings** + **Reports** |
 
 ---
 
@@ -262,4 +386,4 @@ MIT — see [LICENSE](LICENSE) for details.
 
 ---
 
-*Built by DVH*
+*Built by [Deepak Hiremath](https://www.linkedin.com/in/deepak-hiremath-0017937a/)*