assuremind 1.0.0

package/docs/GETTING-STARTED.md

@@ -0,0 +1,378 @@
+# Getting Started with Assuremind
+
+This guide walks you from a blank folder to running your first AI-generated UI test in under 10 minutes.
+
+---
+
+## 1. Prerequisites
+
+- **Node.js 18 or later** — [download](https://nodejs.org)
+- **An AI provider API key** — Anthropic, OpenAI, Google, Groq, or any other supported provider (see [Step 4](#4-configure-your-ai-provider))
+- A web application to test (any URL works — you can use your localhost dev server)
+
+---
+
+## 2. Create a New Project
+
+Assuremind does not need its own project — it works inside any existing Node.js project or a brand-new folder.
+
+```bash
+mkdir my-tests
+cd my-tests
+npm init -y
+```
+
+---
+
+## 3. Install Assuremind
+
+```bash
+npm install git+https://github.com/<org>/assuremind.git
+```
+
+---
+
+## 4. Initialise the Project
+
+```bash
+npx assuremind init
+```
+
+This command:
+
+- Creates the folder structure (`tests/`, `variables/`, `results/`, `fixtures/`)
+- Copies **`.env.example`** — full reference of all supported environment variables
+- Creates **`.env`** — minimal template for you to fill in
+- Creates **`autotest.config.ts`** — framework configuration
+- Creates **`TESTAUTOMIND.md`** — quick-reference card for daily use
+- Installs Playwright browsers (`chromium`, `firefox`, `webkit`)
+
+If you want to skip the Playwright browser download (e.g., in CI where you install them separately):
+
+```bash
+npx assuremind init --skip-playwright
+```
+
+---
+
+## 5. Configure Your AI Provider
+
+Open `.env` and fill in your chosen provider. You only need **one**:
+
+### Anthropic (Claude) — recommended for best results
+
+```bash
+AI_PROVIDER=anthropic
+ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxx
+# ANTHROPIC_MODEL=claude-sonnet-4-6   # optional, defaults to latest Sonnet
+```
+
+### OpenAI (GPT)
+
+```bash
+AI_PROVIDER=openai
+OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
+# OPENAI_MODEL=gpt-4o   # optional
+```
+
+### Google (Gemini)
+
+```bash
+AI_PROVIDER=google
+GOOGLE_API_KEY=AIzaxxxxxxxxxxxxxxxx
+# GOOGLE_MODEL=gemini-2.5-flash   # optional
+```
+
+### Groq (fast, free tier available)
+
+```bash
+AI_PROVIDER=groq
+GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxx
+# GROQ_MODEL=llama-3.3-70b-versatile   # optional
+```
+
+### Ollama (local, completely free)
+
+```bash
+AI_PROVIDER=ollama
+OLLAMA_BASE_URL=http://localhost:11434
+OLLAMA_MODEL=llama3.3
+```
+
+See `.env.example` for all 12 supported providers including DeepSeek, Together AI, Perplexity, Qwen, AWS Bedrock, and Azure OpenAI.
+
+---
+
+## 6. Configure Your Application URL
+
+Open `autotest.config.ts` and set `baseUrl` to your application:
+
+```typescript
+import { defineConfig } from 'assuremind';
+
+export default defineConfig({
+  baseUrl: 'http://localhost:3000',   // ← change this
+  browsers: ['chromium'],
+  headless: true,
+  timeout: 30000,
+  retries: 1,
+  parallel: 2,
+  healing: {
+    enabled: true,
+    maxLevel: 5,
+    dailyBudget: 5.0,
+  },
+});
+```
+
+---
+
+## 7. Write Your First Test
+
+### Option A — Studio UI (recommended for beginners)
+
+Start the Studio:
+
+```bash
+npx assuremind studio
+```
+
+Your browser opens at `http://localhost:4400`. From there:
+
+1. Click **Test Editor** in the sidebar
+2. Click **New Suite** → name it `Login Tests`, select suite type **UI**, **API**, or **Audit**
+3. Click **New Case** → name it `User can log in`
+4. Add steps in plain English, one per line:
+   - `Go to the login page`
+   - `Enter "admin@example.com" in the email field`
+   - `Enter "password123" in the password field`
+   - `Click the Login button`
+   - `Verify the dashboard heading is visible`
+5. Click **Generate Code** — AI generates Playwright code for each step
+6. Click **Run** to execute the test
+
+See [STUDIO.md](./STUDIO.md) for a full Studio walkthrough.
+
+### Option B — CLI generate command
+
+Generate a full test suite from a user story in one command:
+
+```bash
+npx assuremind generate \
+  --story "As a user I want to log in with my email and password so I can access my dashboard." \
+  --suite "Login Tests"
+```
+
+This creates the suite file structure under `tests/login-tests/` and generates Playwright code for every step.
+
+### Option C — Write JSON directly
+
+Create `tests/login-tests/suite.json`:
+
+```json
+{
+  "id": "suite-001",
+  "name": "Login Tests",
+  "description": "Tests for the authentication flow",
+  "tags": ["smoke", "auth"],
+  "createdAt": "2026-01-01T00:00:00.000Z",
+  "updatedAt": "2026-01-01T00:00:00.000Z"
+}
+```
+
+Create `tests/login-tests/user-can-log-in.test.json`:
+
+```json
+{
+  "id": "case-001",
+  "name": "User can log in",
+  "description": "",
+  "tags": ["smoke"],
+  "priority": "critical",
+  "steps": [
+    { "id": "step-1", "order": 1, "instruction": "Go to the login page", "generatedCode": "", "strategy": "primary", "lastHealed": null },
+    { "id": "step-2", "order": 2, "instruction": "Click the Login button", "generatedCode": "", "strategy": "primary", "lastHealed": null }
+  ],
+  "createdAt": "2026-01-01T00:00:00.000Z",
+  "updatedAt": "2026-01-01T00:00:00.000Z"
+}
+```
+
+Steps with empty `generatedCode` will have code generated on the first run.
+
+---
+
+## 8. Run Tests
+
+The `run` command supports flexible filters that can be combined with AND logic.
+
+### Run everything
+
+```bash
+npx assuremind run --all
+```
+
+### Run by suite type
+
+```bash
+# Run only UI suites
+npx assuremind run --type ui
+
+# Run only API suites
+npx assuremind run --type api
+
+# Run only Audit suites
+npx assuremind run --type audit
+```
+
+### Run a specific suite (partial name match)
+
+```bash
+npx assuremind run --suite "Login Tests"
+```
+
+### Run tests matching a tag
+
+```bash
+npx assuremind run --tag smoke
+```
+
+### Run a single test by name (partial match)
+
+```bash
+npx assuremind run --test "User can log in"
+```
+
+### Combine filters (AND logic)
+
+```bash
+# Audit suites with the regression tag
+npx assuremind run --type audit --tag regression
+
+# A named suite filtered to smoke tests
+npx assuremind run --suite "Orange HRM" --tag smoke
+
+# Audit suites containing a specific test name
+npx assuremind run --type audit --test "Login Page"
+```
+
+### Run in headed mode (watch the browser)
+
+```bash
+npx assuremind run --all --headed
+```
+
+### Run with device emulation (mobile/tablet)
+
+```bash
+# Emulate iPhone 15 Pro (use Chromium for best results)
+npx assuremind run --all --device "iPhone 15 Pro" --browser chromium
+
+# Emulate Pixel 7 on a specific suite
+npx assuremind run --suite "Mobile Checkout" --device "Pixel 7" --browser chromium
+
+# Emulate iPad Pro with WebKit
+npx assuremind run --all --device "iPad Pro 11" --browser webkit
+```
+
+Device emulation applies the full Playwright device descriptor — viewport, user-agent, device pixel ratio, touch events, and `isMobile` flag. See the [CLI Reference](./CLI-REFERENCE.md) for the full device list.
+
+### Run in CI mode (exit code 0 = pass, 1 = fail)
+
+```bash
+npx assuremind run --all --ci
+
+# CI with device emulation
+npx assuremind run --all --device "iPhone 15 Pro" --browser chromium --ci
+```
+
+---
+
+## 9. Review Results
+
+After a run:
+
+```
+─────────────────────────────────
+  ✅ All tests passed!
+
+    5 passed  0 failed  0 skipped
+    Duration: 12.4s
+    Run ID:   2026-03-23T14-30-00
+─────────────────────────────────
+```
+
+Results are saved to `results/runs/<runId>.json`. Reports are written to `results/reports/`.
+
+View historical results in the Studio:
+
+```bash
+npx assuremind studio
+# Navigate to Reports in the sidebar
+```
+
+---
+
+## 10. Review Self-Healing Suggestions
+
+When a test step fails and the AI generates a healed version, the suggestion is saved to `results/healing/pending.json`. Review and apply:
+
+```bash
+npx assuremind apply-healing
+```
+
+You will be prompted for each suggestion:
+
+```
+Healing suggestion for: "Click the Login button"
+  Suite:   Login Tests
+  Case:    User can log in
+  Step:    step-2
+
+  Original code:  await page.click('#login-btn');
+  Healed code:    await page.click('button[type="submit"]');
+
+Accept? [y/n/a/q] (y=yes, n=no, a=accept all, q=quit):
+```
+
+Or accept all suggestions without prompting:
+
+```bash
+npx assuremind apply-healing --yes
+```
+
+---
+
+## 11. Use Test Variables
+
+Variables let you avoid hardcoding credentials and URLs. Define them in `variables/global.json`:
+
+```json
+{
+  "BASE_URL": "http://localhost:3000",
+  "ADMIN_EMAIL": "admin@example.com",
+  "ADMIN_PASSWORD": { "value": "supersecret", "secret": true }
+}
+```
+
+Reference them in step instructions using double-braces:
+
+```
+Enter "{{ADMIN_EMAIL}}" in the email field
+Enter "{{ADMIN_PASSWORD}}" in the password field
+```
+
+Or manage variables in the Studio → **Variables** page.
+
+---
+
+## 12. Next Steps
+
+| Topic | Where to look |
+|-------|---------------|
+| All CLI flags | [CLI Reference](./CLI-REFERENCE.md) |
+| Studio UI walkthrough | [Studio Guide](./STUDIO.md) |
+| Build the package from source | [CONTRIBUTING.md](../CONTRIBUTING.md) |
+| Config options | `autotest.config.ts` comments |
+| All supported AI providers | `.env.example` |
+| Quick daily reference | `TESTAUTOMIND.md` in your project root |