assuremind 1.2.3 → 1.4.0

package/README.md

@@ -9,6 +9,10 @@
 
 Describe tests in plain English. AI generates Playwright code. Run anywhere.
 
+> ### 🌐 [AssureMind Community Hub → https://assuremind.in/](https://assuremind.in/)
+> Report bugs · request features · share ideas & feedback · ask questions.
+> 📧 Contact: [assuremind.contact@gmail.com](mailto:assuremind.contact@gmail.com)
+
 ---
 
 ## Why Assuremind?
@@ -28,6 +32,7 @@ Describe tests in plain English. AI generates Playwright code. Run anywhere.
 | **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 |
+| **File upload & download** | Upload fixtures from the Studio and insert as `{{FILE:…}}` tokens; downloads auto-captured per run and viewable in Reports |
 | **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,10 +43,23 @@ Describe tests in plain English. AI generates Playwright code. Run anywhere.
 ```bash
 npm install assuremind
 npx assuremind init        # folders, config, Playwright browsers
+npx playwright install     # if browser install was skipped or failed during init
 npx assuremind studio      # opens http://localhost:4400
 ```
 
-> **Requirements:** Node.js >= 18 · macOS / Linux / Windows
+> **First-time setup:** `npx assuremind init` installs the Playwright browsers automatically. If that step is skipped (`--skip-playwright`) or fails (network/permissions), install them manually with `npx playwright install` (add `--with-deps` on Linux to pull OS libraries). Run `npx assuremind doctor` to verify your setup.
+
+### 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 |
+
+`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
 
@@ -56,6 +74,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
@@ -253,6 +310,12 @@ If all 5 levels fail, the step is marked **failed** and saved to the healing rep
 
 Also supports **GitLab CI** and **Jenkins** — or use the built-in **CI Config Generator** in Studio (Run Config → Generate CI Config).
 
+**CI Config Generator** (Run Config → Generate CI Config):
+- Generates a workflow for **GitHub Actions**, **GitLab CI**, or **Jenkins** from your current run config.
+- The YAML is shown in a **preview**; click **✎ Edit** to customise it (branches, Node version, extra steps…). Your edits apply to Copy, Download, and Write to repo. Use **↺ Reset** to regenerate.
+- **Copy** / **Download** are always available.
+- **Write to repo** (opt-in) writes the file into your project at its standard path (`.github/workflows/assuremind.yml`, `.gitlab-ci.yml`, or `Jenkinsfile`). Enable it in **Settings → CI/CD Integration → "Write CI files to repo"**. It only **writes the file** — it does **not** commit or push. Review the change and commit it from the **Git Control Center** when ready.
+
 Exit code `0` = all passed · `1` = failures.
 
 ---
@@ -274,6 +337,40 @@ Exit code `0` = all passed · `1` = failures.
 
 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.
 
+### File Upload & Download
+
+**Upload** — In the Test Editor, click the **Files** button (next to *Fake Data*) to upload a fixture file. It's saved in the repo at `fixtures/uploads/` (so it's committed and works in CI) and inserted into your step as a **`{{FILE:name}}`** token. The token resolves to the file's path at runtime:
+
+```
+Step:  Upload {{FILE:resume.pdf}} to the Resume field
+Code:  await page.getByLabel('Resume').setInputFiles('{{FILE:resume.pdf}}');
+```
+
+For a file-chooser button, register the listener before the click (in one step):
+```js
+const fileChooserPromise = page.waitForEvent('filechooser');
+await page.getByRole('button', { name: 'Choose File' }).click();
+(await fileChooserPromise).setFiles('{{FILE:resume.pdf}}');
+```
+
+**Download** — Downloads are **captured automatically** during a run (no `saveAs`, no `fs` needed) and saved to `results/downloads/<runId>/`. The step waits until the file finishes downloading. After the run, open **Reports → Run Reports**, expand the run, and the **Downloads** panel lists every captured file — click any to save it to your machine.
+
+**Example steps** (type these in plain English):
+
+```text
+# Upload
+Upload {{FILE:resume.pdf}} to the Resume field
+Upload {{FILE:resume.pdf}} to the Resume field and wait for 'Upload complete'   # most reliable
+Upload {{FILE:photo.png}}                                                       # page's file input
+
+# Download (file finishes downloading before the step passes)
+Download the "Export CSV" link
+Click the "Export" button to download
+Download the file by clicking "Report PDF"
+```
+
+Tip: for uploads, the `…and wait for '<success text>'` form is the most reliable (uploads have no completion event); otherwise the step waits for the network to settle.
+
 ### 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.
@@ -322,6 +419,7 @@ Quality gates, PR comments, and notifications — configured from Studio, execut
 | Resource | Location |
 |----------|----------|
 | Getting started | [docs/GETTING-STARTED.md](docs/GETTING-STARTED.md) |
+| Writing test steps (UI & API examples) | [docs/WRITING-STEPS.md](docs/WRITING-STEPS.md) |
 | Studio walkthrough | [docs/STUDIO.md](docs/STUDIO.md) |
 | CLI reference | [docs/CLI-REFERENCE.md](docs/CLI-REFERENCE.md) |
 | Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) |
@@ -331,6 +429,19 @@ Quality gates, PR comments, and notifications — configured from Studio, execut
 
 ---
 
+## Community & Support
+
+Have a question, found a bug, or want to shape what comes next? Join the **[AssureMind Community Hub](https://assuremind.in/)**:
+
+- 🐞 **Report bugs**
+- ✨ **Request new features**
+- 💡 **Share ideas and feedback**
+- ❓ **Ask questions**
+
+👉 Visit **[https://assuremind.in/](https://assuremind.in/)** &nbsp;|&nbsp; 📧 **[assuremind.contact@gmail.com](mailto:assuremind.contact@gmail.com)**
+
+---
+
 ## License
 
 MIT — see [LICENSE](LICENSE) for details.