assuremind 1.1.1 → 1.2.0

package/CONTRIBUTING.md

@@ -36,9 +36,10 @@ cd ui && npm install && cd ..
 assuremind/
 ├── src/
 │   ├── cli/          # CLI entry point and commands (init, run, generate, …)
-│   ├── engine/       # Test runner, executor, self-healing, Allure reporter
+│   ├── engine/       # Test runner, executor, self-healing, Allure reporter, recorder
 │   ├── ai/           # Smart router, provider adapters, prompts, code cache
 │   ├── mcp/          # Playwright MCP integration (accessibility snapshots, action mapper)
+│   ├── rag/          # RAG memory — TF-IDF embedder, vector store, code/healing/error corpora
 │   ├── storage/      # File-based JSON stores (suites, cases, results, healing)
 │   ├── server/       # Fastify API server + WebSocket
 │   ├── types/        # Zod schemas and TypeScript types
@@ -226,7 +227,12 @@ Everything is stored as plain JSON files in the user's project directory — no
 │   ├── videos/
 │   ├── traces/
 │   ├── reports/
-│   └── healing/
+│   ├── healing/
+│   └── .rag/              # RAG semantic memory (auto-generated)
+│       ├── idf-vocab.json
+│       ├── code-corpus.json
+│       ├── healing-corpus.json
+│       └── error-catalog.json
 └── autotest.config.json   # written by writeConfig()
 ```
 
@@ -250,6 +256,8 @@ Healed steps are saved as `pending` events in `results/healing/pending.json` for
 
 1. **Template engine** — recognises common patterns (navigate, click, fill, etc.) and uses zero-cost templates.
 2. **Code cache** — SHA-based cache keyed on `(normalised instruction, url pattern)`. Cache persists to `results/code-cache.json`.
-3. **MCP enrichment** — when enabled, the SmartRouter takes a live accessibility snapshot and feeds real page elements to the AI, boosting selector accuracy to ~90-95%.
-4. **Complexity classifier** — routes simple steps to cheap/fast models (tiered mode) and complex steps to capable models.
-5. **Batch generation** — multiple empty steps sent in one API call.
+3. **RAG memory** — semantic retrieval from past runs. Code Corpus matches >= 0.90 are used directly as fuzzy cache hits ($0). Lower matches (0.65-0.90) enrich the AI prompt. Healing Corpus injects proven past fixes into self-healing prompts. Error Catalog warns the AI about known-bad patterns.
+4. **MCP enrichment** — when enabled, the SmartRouter takes a live accessibility snapshot and feeds real page elements to the AI, boosting selector accuracy to ~90-95%.
+5. **Complexity classifier** — routes simple steps to cheap/fast models (tiered mode) and complex steps to capable models.
+6. **Batch generation** — multiple empty steps sent in one API call.
+7. **Test Recorder** — deterministic code from browser interactions, zero AI calls. Uses Playwright's accessibility tree to resolve locators with 6 strategies, verified with `count() === 1`.

package/README.md

@@ -22,7 +22,9 @@ Describe tests in plain English. AI generates Playwright code. Run anywhere.
 | **12 AI providers** | Anthropic · OpenAI · Gemini · Groq · DeepSeek · Together · Qwen · Perplexity · Ollama · Bedrock · Azure OpenAI · Custom |
 | **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 |
-| **Cost-optimised** | Template engine + code cache handle ~80% of steps with zero AI calls |
+| **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 |
+| **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 |
 
@@ -108,6 +110,92 @@ AI sees **real page elements** during code generation via the official `@playwri
 
 ---
 
+## Test Recorder
+
+Record tests by interacting with your application in a real browser — **zero AI, zero cost, zero guesswork**.
+
+Click **Record** in the Test Editor, perform your actions, and stop. Each interaction becomes a step with verified Playwright code, ready to run.
+
+### How it works
+
+1. A headed Chromium browser opens your app's URL
+2. Every click, fill, and navigation is captured in real time — **including inside iframes**
+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
+
+### What makes it stand out vs other recorders
+
+| Feature | Selenium IDE | Playwright Codegen | Assuremind Recorder |
+|---------|-------------|-------------------|---------------------|
+| 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 |
+| 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 |
+| RAG memory | No | No | Yes — recorded steps feed the learning loop |
+| Cost | Free | Free | Free |
+
+### Biggest pain points in test automation — solved
+
+| Pain Point | How the Recorder Solves It |
+|-----------|---------------------------|
+| Writing tests is slow | Record a full test in 30 seconds |
+| Selectors break constantly | Locators verified against Playwright's accessibility tree in real time |
+| AI costs money | Recording + code generation = $0, zero AI calls |
+| Non-technical testers can't write tests | Anyone who can click a browser can create tests |
+| 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 |
+
+---
+
+## RAG Memory (Retrieval-Augmented Generation)
+
+The AI learns from every test run, building semantic memory that improves accuracy over time — **zero setup required**:
+
+| Corpus | What it stores | When it's used |
+|--------|---------------|----------------|
+| **Code Corpus** | Instruction-to-code mappings from successful runs | During generation — similar past steps are retrieved as AI examples or used directly (score >= 0.90) |
+| **Healing Corpus** | Past healing events (error + fix pairs) | During self-healing — proven past fixes are injected into the repair prompt |
+| **Error Catalog** | Recurring error patterns per URL | During generation — the AI is warned about known-bad selectors to avoid |
+
+**Zero cost, zero database** — uses local TF-IDF embeddings and file-based JSON storage (`results/.rag/`). Enabled by default — works automatically from the very first run.
+
+### How it improves over time
+
+- **Run 1** — memory is empty, AI generates code normally
+- **Run 2+** — RAG kicks in silently: similar instructions are retrieved instead of making API calls (free + faster), healing uses proven past fixes
+- **Run 10+** — most common steps are served from RAG memory at zero cost, self-healing resolves issues on the first attempt
+
+### Consumer FAQ
+
+| Question | Answer |
+|----------|--------|
+| Do I need to configure anything? | No. RAG is ON by default with zero setup. |
+| Does it cost anything? | No. TF-IDF embedder runs locally. RAG direct hits replace paid AI calls. |
+| Does it slow down my tests? | No. RAG lookup is <1ms. It actually speeds up generation. |
+| Does it work in CI/CD? | Yes. Cache `results/.rag/` between CI runs to persist memory. |
+| How do I share memory across team? | Commit `results/.rag/` to Git or use a CI cache step. |
+| How do I reset memory? | Delete the `results/.rag/` folder. |
+
+### When to use Settings → RAG Memory
+
+Most users never need to touch RAG settings. The Settings card exists for power-user scenarios:
+
+| Scenario | Action |
+|----------|--------|
+| Debugging a flaky test | Turn OFF Code Corpus — forces fresh AI generation |
+| Healing keeps suggesting a bad fix | Turn OFF Healing Corpus — clears bad fix influence |
+| Major app redesign | Turn OFF RAG entirely — old memory is now misleading |
+| Error warnings are outdated | Turn OFF Error Catalog — stops avoiding selectors that are fine now |
+| Want deterministic CI runs | Disable RAG in CI config, keep ON locally |
+
+---
+
 ## Self-Healing
 
 When your app's UI changes (button renamed, element moved, DOM restructured), tests break. Instead of failing immediately, Assuremind automatically attempts to fix the broken selector through a 5-level cascade — **fully automated, no manual intervention needed**: