assuremind 1.0.0

package/templates/AUTOMIND.md

@@ -0,0 +1,275 @@
+# Assuremind — Quick Reference
+
+> AI-powered codeless UI test automation. Write steps in plain English, AI writes Playwright code once, tests run forever.
+
+---
+
+## Daily Commands
+
+```bash
+# Start the Studio (browser UI)
+npx assuremind studio
+
+# Run all tests
+npx assuremind run --all
+
+# Run by suite type (ui | api | audit)
+npx assuremind run --type ui
+npx assuremind run --type api
+npx assuremind run --type audit
+
+# Run a specific suite (partial name match)
+npx assuremind run --suite "Login Tests"
+
+# Run tests by tag
+npx assuremind run --tag smoke
+
+# Run a single test (partial name match)
+npx assuremind run --test "User can log in"
+
+# Combine filters (AND logic)
+npx assuremind run --type audit --tag regression
+npx assuremind run --suite "Orange HRM" --tag smoke
+npx assuremind run --type audit --test "Login Page"
+
+# Device emulation — mobile & tablet
+npx assuremind run --all --device "iPhone 15 Pro" --browser chromium
+npx assuremind run --tag smoke --device "Pixel 7" --browser chromium
+npx assuremind run --all --device "iPad Pro 11" --browser webkit
+
+# Run in CI (exit code = pass/fail)
+npx assuremind run --all --ci
+npx assuremind run --all --device "iPhone 15 Pro" --browser chromium --ci
+
+# Watch the browser while running
+npx assuremind run --all --headed
+
+# Review + apply self-healing suggestions
+npx assuremind apply-healing
+
+# Accept all healing suggestions silently
+npx assuremind apply-healing --yes
+
+# Generate tests from a user story
+npx assuremind generate --story "As a user I want to..."
+
+# Check config and environment
+npx assuremind validate
+npx assuremind doctor
+```
+
+---
+
+## Project Structure
+
+```
+.
+├── .env                          ← AI provider credentials (never commit)
+├── .env.example                  ← Provider reference (safe to commit)
+├── autotest.config.ts            ← Framework configuration
+├── TESTAUTOMIND.md               ← This file
+│
+├── tests/
+│   ├── <suite-slug>/             ← UI and API suites
+│   │   ├── suite.json            ← Suite metadata
+│   │   └── <case-slug>.test.json ← Test case with steps
+│   └── audit/                    ← Audit suites (Lighthouse)
+│       ├── suite.json
+│       └── <case-slug>.test.json
+│
+├── variables/
+│   ├── global.json               ← Variables available in all environments
+│   ├── dev.env.json              ← Variables for --env dev
+│   ├── staging.env.json          ← Variables for --env staging
+│   └── prod.env.json             ← Variables for --env prod
+│
+├── fixtures/
+│   ├── auth/                     ← Auth state files (Playwright storageState)
+│   └── data/                     ← Test data files
+│
+└── results/
+    ├── runs/                     ← Run result JSON files
+    ├── screenshots/              ← Failure screenshots
+    ├── videos/                   ← Video recordings
+    ├── traces/                   ← Playwright trace files
+    ├── reports/                  ← HTML / Allure reports
+    └── healing/                  ← Healing report + pending suggestions
+```
+
+---
+
+## Writing Step Instructions
+
+| Pattern | Example |
+|---------|---------|
+| Navigate | `Go to the login page` |
+| Click | `Click the Login button` |
+| Fill | `Enter "admin@example.com" in the email field` |
+| Select | `Select "United States" from the country dropdown` |
+| Assert visible | `Verify the success message is visible` |
+| Assert text | `Verify the heading contains "Dashboard"` |
+| Assert URL | `Verify the URL contains "/dashboard"` |
+| Wait | `Wait for the loading spinner to disappear` |
+| Upload | `Upload the file "fixtures/data/avatar.png" to the photo field` |
+| Variable | `Enter "{{ADMIN_EMAIL}}" in the email field` |
+
+---
+
+## Variables
+
+Reference variables in instructions with `{{KEY}}`:
+
+```
+Enter "{{BASE_URL}}" in the address bar
+Enter "{{ADMIN_EMAIL}}" in the email field
+Enter "{{ADMIN_PASSWORD}}" in the password field
+```
+
+Define them in `variables/global.json`:
+
+```json
+{
+  "BASE_URL": "http://localhost:3000",
+  "ADMIN_EMAIL": "admin@example.com",
+  "ADMIN_PASSWORD": { "value": "supersecret", "secret": true }
+}
+```
+
+---
+
+## .env — AI Provider Setup
+
+Edit `.env` in this directory. Pick one provider block:
+
+```bash
+# Anthropic (Claude) — recommended
+AI_PROVIDER=anthropic
+ANTHROPIC_API_KEY=sk-ant-xxxxxxxx
+
+# OpenAI (GPT-4o)
+AI_PROVIDER=openai
+OPENAI_API_KEY=sk-xxxxxxxx
+
+# Google (Gemini)
+AI_PROVIDER=google
+GOOGLE_API_KEY=AIzaxxxxxxxx
+
+# Groq (fast + free tier)
+AI_PROVIDER=groq
+GROQ_API_KEY=gsk_xxxxxxxx
+
+# Ollama (local, free)
+AI_PROVIDER=ollama
+OLLAMA_BASE_URL=http://localhost:11434
+OLLAMA_MODEL=llama3.3
+```
+
+See `.env.example` for all 12 supported providers.
+
+---
+
+## autotest.config.ts — Key Settings
+
+```typescript
+export default defineConfig({
+  baseUrl: 'http://localhost:3000',  // Your app URL
+  browsers: ['chromium'],            // chromium | firefox | webkit
+  headless: true,                    // false = watch browser
+  timeout: 30000,                    // Step timeout (ms)
+  retries: 1,                        // Retries on failure
+  parallel: 2,                       // Parallel workers
+  screenshot: 'on-failure',          // on | off | on-failure
+  video: 'off',                      // on | off | on-failure
+  trace: 'on-failure',               // on | off | on-failure
+  device: 'iPhone 15 Pro',           // optional — Playwright device descriptor
+  healing: {
+    enabled: true,
+    maxLevel: 5,                     // 1–6
+    dailyBudget: 5.0,                // Max USD/day on healing
+  },
+  studioPort: 4400,
+});
+```
+
+---
+
+## Self-Healing Levels
+
+| Level | Strategy |
+|-------|---------|
+| 1 | Smart Retry — wait + retry with backoff |
+| 2 | AI Regeneration — AI rewrites Playwright code |
+| 3 | Multi-Selector — try alternate selectors (ID, text, role, aria) |
+| 4 | Visual/SoM — screenshot + AI visual analysis |
+| 5 | Decompose — break step into smaller sub-actions |
+| 6 | Manual — flag for human review |
+
+Healed steps are saved as pending suggestions. Review with:
+
+```bash
+npx assuremind apply-healing
+```
+
+Or in the Studio → **Self-Healing** page.
+
+---
+
+## Device Emulation
+
+Emulate real devices using Playwright's built-in device descriptors. Select in Studio UI or use `--device` CLI flag.
+
+| Device | Category | Viewport | Browser |
+|--------|----------|----------|---------|
+| `iPhone 15 Pro` | Mobile | 393×852 | webkit / chromium |
+| `iPhone 15` | Mobile | 390×844 | webkit / chromium |
+| `iPhone 14` | Mobile | 390×844 | webkit / chromium |
+| `iPhone SE` | Mobile | 375×667 | webkit / chromium |
+| `Pixel 7` | Mobile | 412×915 | chromium |
+| `Pixel 5` | Mobile | 393×851 | chromium |
+| `Galaxy S9+` | Mobile | 320×658 | chromium |
+| `Galaxy S8` | Mobile | 360×740 | chromium |
+| `iPad Pro 11` | Tablet | 834×1194 | webkit / chromium |
+| `iPad (gen 7)` | Tablet | 810×1080 | webkit / chromium |
+| `iPad Mini` | Tablet | 768×1024 | webkit / chromium |
+| `Galaxy Tab S4` | Tablet | 712×1138 | chromium |
+
+> **Tip:** Always pair mobile/tablet devices with `--browser chromium` for full touch event support.
+
+---
+
+## CI/CD (GitHub Actions)
+
+```yaml
+# Standard run
+- name: Run tests
+  env:
+    AI_PROVIDER: anthropic
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+  run: |
+    npx playwright install --with-deps chromium
+    npx assuremind run --all --ci
+
+# Mobile run
+- name: Run mobile tests
+  env:
+    AI_PROVIDER: anthropic
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+  run: |
+    npx playwright install --with-deps chromium
+    npx assuremind run --all --device "iPhone 15 Pro" --browser chromium --ci
+
+- name: Apply healing (if tests failed)
+  if: failure()
+  run: npx assuremind apply-healing --yes
+```
+
+---
+
+## Getting Help
+
+| Resource | Location |
+|----------|----------|
+| Full getting-started guide | `docs/GETTING-STARTED.md` |
+| CLI reference | `docs/CLI-REFERENCE.md` |
+| Studio UI walkthrough | `docs/STUDIO.md` |
+| All AI providers | `.env.example` |

package/templates/autotest.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from 'assuremind';
+
+export default defineConfig({
+  baseUrl: 'http://localhost:3000',
+  browsers: ['chromium', 'firefox'],
+  headless: true,
+  timeout: 30000,
+  retries: 1,
+  parallel: 2,
+  screenshot: 'on-failure',    // 'on' | 'off' | 'on-failure'
+  video: 'off',                // 'on' | 'off' | 'on-failure'
+  trace: 'on-failure',         // 'on' | 'off' | 'on-failure'
+  healing: {
+    enabled: true,
+    maxLevel: 5,
+    dailyBudget: 5.0,
+    autoPR: false,
+  },
+  reporting: {
+    allure: true,
+    html: true,
+    json: true,
+  },
+  studioPort: 4400,
+});

package/templates/docs/CLI-REFERENCE.md

@@ -0,0 +1,413 @@
+# Assuremind CLI Reference
+
+Complete reference for all `assuremind` CLI commands.
+
+---
+
+## Global Usage
+
+```bash
+npx assuremind <command> [options]
+# or if installed globally:
+assuremind <command> [options]
+```
+
+```bash
+assuremind --version    # Print version
+assuremind --help       # List all commands
+assuremind <cmd> --help # Help for a specific command
+```
+
+---
+
+## Commands
+
+### `init`
+
+Initialise Assuremind in the current directory.
+
+```bash
+npx assuremind init [options]
+```
+
+**What it does:**
+- Creates the directory structure (`tests/`, `variables/`, `results/`, `fixtures/`, `docs/`)
+- Copies starter files (`.env`, `autotest.config.ts`, `TESTAUTOMIND.md`, docs)
+- Writes `autotest.config.json` with defaults
+- Installs Playwright browsers (Chromium, Firefox, WebKit)
+
+**Requirements:** A `package.json` must exist in the current directory.
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--skip-playwright` | Skip Playwright browser installation (useful in CI where browsers are pre-installed) |
+
+**Examples:**
+
+```bash
+# Standard init
+npx assuremind init
+
+# Skip browser download (CI)
+npx assuremind init --skip-playwright
+```
+
+---
+
+### `studio`
+
+Launch the Assuremind web UI (Studio).
+
+```bash
+npx assuremind studio [options]
+```
+
+**What it does:**
+- Starts the Fastify API server
+- Serves the React Studio UI
+- Opens the browser at `http://localhost:<port>`
+
+**Options:**
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-p, --port <number>` | Override the studio port | `4400` (from config) |
+| `--no-open` | Do not auto-open the browser | Auto-opens by default |
+
+**Examples:**
+
+```bash
+# Start studio on default port
+npx assuremind studio
+
+# Use a custom port
+npx assuremind studio --port 5000
+
+# Start without opening browser
+npx assuremind studio --no-open
+```
+
+---
+
+### `run`
+
+Run tests from the command line (no Studio required).
+
+```bash
+npx assuremind run [options]
+```
+
+**Scope options (pick one or combine):**
+
+| Flag | Description |
+|------|-------------|
+| `--all` | Run all test suites |
+| `--suite <name>` | Run a specific suite by name |
+| `--tag <tag>` | Run all tests matching a tag |
+| `--test <name>` | Run a specific test case by name |
+
+**Browser options:**
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--browser <list...>` | Space-separated list of browsers | From config |
+| `--headed` | Run in headed (visible) mode | Headless |
+
+**Execution options:**
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--parallel <n>` | Number of parallel workers | From config |
+| `--env <name>` | Environment to use (`dev`, `staging`, `prod`) | None |
+| `--ci` | CI mode — no prompts, exit code = pass/fail | Off |
+| `--no-healing` | Disable self-healing for this run | Healing enabled |
+
+**Reporting options:**
+
+| Flag | Description |
+|------|-------------|
+| `--reporter <list...>` | Space-separated reporters: `allure`, `html`, `json` |
+
+**Examples:**
+
+```bash
+# Run everything
+npx assuremind run --all
+
+# Run a specific suite
+npx assuremind run --suite "Login Tests"
+
+# Run by tag
+npx assuremind run --tag smoke
+
+# Run a single test case
+npx assuremind run --test "User can log in with valid credentials"
+
+# Run with visible browser on Firefox
+npx assuremind run --all --headed --browser firefox
+
+# Run against staging environment
+npx assuremind run --all --env staging
+
+# CI pipeline (exit 0 = all pass, exit 1 = any fail)
+npx assuremind run --all --ci
+
+# Run without healing (saves AI costs)
+npx assuremind run --all --no-healing
+
+# Run with specific reporters
+npx assuremind run --all --reporter allure html
+
+# Parallel run with 3 workers
+npx assuremind run --all --parallel 3
+```
+
+**Exit codes (CI mode):**
+
+| Code | Meaning |
+|------|---------|
+| 0 | All tests passed |
+| 1 | One or more tests failed |
+| 2 | Configuration or setup error |
+
+---
+
+### `generate`
+
+Generate test cases from a user story using AI.
+
+```bash
+npx assuremind generate [options]
+```
+
+**What it does:**
+- Reads a plain-English user story (from argument or file)
+- Uses AI to generate a complete test suite with test cases and steps
+- Saves the generated suite to the `tests/` directory
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--story <text>` | User story text inline |
+| `--story-file <path>` | Path to a `.txt` or `.md` file containing the story |
+| `--suite <name>` | Name for the generated suite |
+| `--output <path>` | Output directory (default: `tests/`) |
+
+**Examples:**
+
+```bash
+# Inline user story
+npx assuremind generate \
+  --story "As a user I want to log in with my email and password so that I can access my dashboard" \
+  --suite "Login Flow"
+
+# From a file
+npx assuremind generate \
+  --story-file docs/user-stories/checkout.md \
+  --suite "Checkout Flow"
+```
+
+**After generating:**
+Open the Studio, find the new suite, review the generated steps, then run **"Generate All"** to create Playwright code for each step.
+
+---
+
+### `validate`
+
+Validate configuration, environment variables, and test files.
+
+```bash
+npx assuremind validate
+```
+
+**Checks performed:**
+- `autotest.config.json` — valid JSON, required fields present, values in range
+- `.env` — AI provider key is set
+- `variables/global.json` — valid JSON, no syntax errors
+- `tests/` directory — all suite and case JSON files parse correctly
+- `baseUrl` — reachable (HTTP check, non-blocking)
+
+**Output example:**
+```
+✅ autotest.config.json — valid
+✅ .env — AI_PROVIDER=anthropic, key present
+✅ variables/global.json — 4 variables defined
+✅ tests/ — 3 suites, 12 cases, 47 steps — all valid
+⚠️  baseUrl http://localhost:3000 — not reachable (start your app first)
+```
+
+---
+
+### `doctor`
+
+Check system requirements and overall setup health.
+
+```bash
+npx assuremind doctor
+```
+
+**Checks performed:**
+
+| Check | What it verifies |
+|-------|-----------------|
+| Node.js version | ≥ 18 |
+| npm version | ≥ 8 |
+| Playwright installed | `@playwright/test` or `playwright` package present |
+| Browser binaries | Chromium, Firefox, WebKit installed |
+| AI provider | Key set and API reachable |
+| Config file | `autotest.config.json` exists and is valid |
+| Results directory | Writable |
+| Disk space | Warn if < 500 MB free |
+
+**Output example:**
+```
+✅ Node.js v20.11.0 — ok
+✅ npm 10.4.0 — ok
+✅ Playwright 1.48.0 — installed
+✅ Chromium — browser binary found
+✅ Firefox — browser binary found
+✅ WebKit — browser binary found
+✅ AI provider: anthropic — API reachable
+✅ autotest.config.json — valid
+✅ results/ — writable
+⚠️  Disk space: 1.2 GB free — consider cleaning results/
+```
+
+---
+
+### `apply-healing`
+
+Review and apply self-healing suggestions to test files.
+
+```bash
+npx assuremind apply-healing [options]
+```
+
+**What it does:**
+- Lists all pending healing suggestions
+- Shows the before/after code diff for each
+- Prompts you to accept or reject each suggestion
+- Accepted suggestions are written back to the test `.json` files
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--from <path>` | Load healing suggestions from a specific JSON file instead of `results/healing/` |
+| `-y, --yes` | Accept all pending suggestions without prompting (CI-friendly) |
+
+**Examples:**
+
+```bash
+# Interactive review
+npx assuremind apply-healing
+
+# Accept all suggestions silently (CI)
+npx assuremind apply-healing --yes
+
+# Apply from a specific healing report
+npx assuremind apply-healing --from results/healing/2026-03-25.json
+```
+
+**Interactive prompt example:**
+```
+Pending healing suggestions: 2
+
+─── Suggestion 1/2 ───────────────────────────────────────
+Case: login-tests/user-can-log-in
+Step: Click the Login button
+Level: 2 (AI Regeneration)
+
+Before:
+  await page.getByText('Login').click();
+
+After:
+  await page.getByRole('button', { name: 'Login' }).click();
+
+Accept this change? [Y/n] Y
+✅ Applied
+
+─── Suggestion 2/2 ───────────────────────────────────────
+...
+```
+
+---
+
+## Environment Variables
+
+These environment variables can override CLI flags or config file values:
+
+| Variable | Description |
+|----------|-------------|
+| `AI_PROVIDER` | AI provider to use |
+| `ANTHROPIC_API_KEY` | Anthropic API key |
+| `OPENAI_API_KEY` | OpenAI API key |
+| `GOOGLE_API_KEY` | Google Gemini API key |
+| `GROQ_API_KEY` | Groq API key |
+| `OLLAMA_BASE_URL` | Ollama server URL |
+| `OLLAMA_MODEL` | Ollama model name |
+| `AI_TIMEOUT` | AI request timeout in seconds |
+| `AI_MAX_RETRIES` | Max AI request retries |
+| `STUDIO_PORT` | Override studio port |
+| `HEALING_ENABLED` | `false` to disable healing globally |
+
+---
+
+## Configuration File
+
+`autotest.config.json` (auto-generated, also editable via Settings UI):
+
+```json
+{
+  "baseUrl": "http://localhost:3000",
+  "browsers": ["chromium"],
+  "headless": true,
+  "viewport": { "width": 1280, "height": 720 },
+  "timeout": 30000,
+  "retries": 1,
+  "parallel": 1,
+  "pageLoad": "domcontentloaded",
+  "screenshot": "only-on-failure",
+  "video": "off",
+  "trace": "on-first-retry",
+  "healing": {
+    "enabled": true,
+    "maxLevel": 5,
+    "dailyBudget": 5.0,
+    "autoPR": false
+  },
+  "reporting": {
+    "allure": true,
+    "html": true,
+    "json": true
+  },
+  "studioPort": 4400
+}
+```
+
+**Field reference:**
+
+| Field | Type | Options | Description |
+|-------|------|---------|-------------|
+| `baseUrl` | string | Any URL | Root URL of your app |
+| `browsers` | array | `chromium` `firefox` `webkit` | Browsers to run tests on |
+| `headless` | boolean | `true` `false` | Headless or headed mode |
+| `viewport` | object | `{ width, height }` | Browser window size |
+| `timeout` | number | ms | Step timeout |
+| `retries` | number | 0–10 | Retry count on failure |
+| `parallel` | number | 1–16 | Parallel workers |
+| `pageLoad` | string | `commit` `domcontentloaded` `load` `networkidle` | Page load wait strategy |
+| `screenshot` | string | `off` `on` `only-on-failure` | Screenshot capture |
+| `video` | string | `off` `on` `on-first-retry` `retain-on-failure` | Video recording |
+| `trace` | string | `off` `on` `on-first-retry` `retain-on-failure` | Playwright trace |
+| `healing.enabled` | boolean | | Enable self-healing |
+| `healing.maxLevel` | number | 1–6 | Max healing strategy level |
+| `healing.dailyBudget` | number | USD | Max daily AI spend on healing |
+| `healing.autoPR` | boolean | | Auto-create PRs for accepted heals |
+| `reporting.allure` | boolean | | Generate Allure report |
+| `reporting.html` | boolean | | Generate HTML report |
+| `reporting.json` | boolean | | Save JSON results |
+| `studioPort` | number | 1024–65535 | Studio server port |