assuremind 1.0.0

package/templates/docs/GETTING-STARTED.md

@@ -0,0 +1,417 @@
+# Getting Started with Assuremind
+
+> AI-powered UI test automation — write steps in plain English, AI generates Playwright code, tests run forever.
+
+---
+
+## Table of Contents
+
+1. [Prerequisites](#1-prerequisites)
+2. [Installation](#2-installation)
+3. [Project Initialisation](#3-project-initialisation)
+4. [Configure AI Provider](#4-configure-ai-provider)
+5. [Configure Your App URL](#5-configure-your-app-url)
+6. [Start the Studio](#6-start-the-studio)
+7. [Create Your First Test Suite](#7-create-your-first-test-suite)
+8. [Write Test Steps](#8-write-test-steps)
+9. [Generate Code with AI](#9-generate-code-with-ai)
+10. [Run the Test](#10-run-the-test)
+11. [View Results & Reports](#11-view-results--reports)
+12. [Use Variables (Credentials & Dynamic Data)](#12-use-variables-credentials--dynamic-data)
+13. [Self-Healing](#13-self-healing)
+14. [CI/CD Integration](#14-cicd-integration)
+15. [Next Steps](#15-next-steps)
+
+---
+
+## 1. Prerequisites
+
+| Requirement | Version |
+|-------------|---------|
+| Node.js     | ≥ 18    |
+| npm         | ≥ 8     |
+| Git         | Any     |
+
+An API key for at least one supported AI provider (OpenAI, Anthropic, Google, Groq, Ollama, etc.)
+
+---
+
+## 2. Installation
+
+Install Assuremind from the private GitHub repository:
+
+```bash
+npm install git+https://github.com/<org>/assuremind.git
+```
+
+Then use the CLI:
+
+```bash
+npx assuremind init
+```
+
+---
+
+## 3. Project Initialisation
+
+Navigate to your project directory (must have a `package.json`) and run:
+
+```bash
+cd my-project
+npx assuremind init
+```
+
+This will:
+- Create the folder structure (`tests/`, `variables/`, `results/`, `fixtures/`)
+- Copy starter config files (`.env`, `autotest.config.ts`)
+- Copy this documentation to `docs/`
+- Install Playwright browsers (Chromium, Firefox, WebKit)
+
+**Folder structure created:**
+
+```
+my-project/
+├── .env                     ← AI credentials (never commit)
+├── .env.example             ← Provider reference
+├── autotest.config.ts       ← Framework configuration
+├── autotest.config.json     ← Runtime config (auto-synced)
+├── TESTAUTOMIND.md          ← Quick-reference cheat sheet
+├── docs/
+│   ├── GETTING-STARTED.md   ← This file
+│   ├── STUDIO.md            ← Full UI walkthrough
+│   └── CLI-REFERENCE.md     ← All CLI commands
+├── tests/                   ← Test suites (auto-managed by Studio)
+├── variables/
+│   ├── global.json          ← Variables for all environments
+│   ├── dev.env.json
+│   ├── staging.env.json
+│   └── prod.env.json
+├── fixtures/
+│   ├── auth/                ← Auth state files
+│   └── data/                ← Test data files
+└── results/
+    ├── screenshots/
+    ├── videos/
+    ├── traces/
+    ├── reports/
+    └── healing/
+```
+
+---
+
+## 4. Configure AI Provider
+
+Open `.env` in your project root and set your AI provider:
+
+```bash
+# Recommended: Anthropic Claude
+AI_PROVIDER=anthropic
+ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxx
+
+# Or: OpenAI GPT-4o
+AI_PROVIDER=openai
+OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
+
+# Or: Google Gemini
+AI_PROVIDER=google
+GOOGLE_API_KEY=AIzaxxxxxxxxxxxxxxxx
+
+# Or: Groq (fast + free tier)
+AI_PROVIDER=groq
+GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxx
+
+# Or: Ollama (local, completely free)
+AI_PROVIDER=ollama
+OLLAMA_BASE_URL=http://localhost:11434
+OLLAMA_MODEL=llama3.3
+```
+
+See `.env.example` for all 12 supported providers including Azure OpenAI, Bedrock, DeepSeek, Together AI, Qwen, and Perplexity.
+
+---
+
+## 5. Configure Your App URL
+
+Open `autotest.config.ts` and set `baseUrl` to your application's URL:
+
+```typescript
+export default defineConfig({
+  baseUrl: 'http://localhost:3000',  // ← change this to your app
+  browsers: ['chromium'],
+  headless: true,
+  timeout: 30000,
+  retries: 1,
+  parallel: 1,
+  screenshot: 'only-on-failure',
+  video: 'off',
+  trace: 'on-first-retry',
+  healing: {
+    enabled: true,
+    maxLevel: 5,
+    dailyBudget: 5.0,
+    autoPR: false,
+  },
+  studioPort: 4400,
+});
+```
+
+---
+
+## 6. Start the Studio
+
+```bash
+npx assuremind studio
+```
+
+The Studio opens automatically at **http://localhost:4400**
+
+Options:
+```bash
+npx assuremind studio --port 5000     # Custom port
+npx assuremind studio --no-open       # Don't auto-open browser
+```
+
+---
+
+## 7. Create Your First Test Suite
+
+1. In the Studio, click **"New Suite"** in the sidebar
+2. Enter a name e.g. `Login Tests`
+3. Optionally add a description and tags (e.g. `smoke`, `auth`)
+4. Click **Create**
+
+A suite is a collection of related test cases. For example:
+- `Login Tests` — login, logout, password reset
+- `Checkout Flow` — add to cart, checkout, payment
+- `User Profile` — update name, change password, upload avatar
+
+---
+
+## 8. Write Test Steps
+
+1. Click your suite → click **"New Case"**
+2. Enter a test case name e.g. `User can log in with valid credentials`
+3. Click into the case to open the **Case Editor**
+4. Click **"Add Step"** and write plain-English instructions:
+
+| Step | Instruction |
+|------|-------------|
+| 1 | `Go to the login page` |
+| 2 | `Enter "admin@example.com" in the email field` |
+| 3 | `Enter "password123" in the password field` |
+| 4 | `Click the Login button` |
+| 5 | `Verify the dashboard heading is visible` |
+| 6 | `Verify the URL contains "/dashboard"` |
+
+**Step writing tips:**
+- Be specific: `Click the Submit button` not `Click something`
+- Use quotes for literal values: `Enter "hello@example.com" in the email field`
+- Use `{{VARIABLE}}` for dynamic values: `Enter "{{USERNAME}}" in the email field`
+- Assertions start with: `Verify`, `Assert`, `Check`, `Confirm`
+- Navigation: `Go to`, `Navigate to`, `Open`
+
+---
+
+## 9. Generate Code with AI
+
+Once steps are written, click **"Generate All"** in the Case Editor toolbar.
+
+The AI reads each plain-English step and generates Playwright TypeScript code, for example:
+
+```typescript
+// Step: Go to the login page
+await page.goto('/login');
+
+// Step: Enter "admin@example.com" in the email field
+await page.getByLabel('Email').fill('admin@example.com');
+
+// Step: Click the Login button
+await page.getByRole('button', { name: 'Login' }).click();
+
+// Step: Verify the dashboard heading is visible
+await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+```
+
+You can also:
+- Generate code for a **single step** by clicking the ⚡ icon on that step row
+- **Edit the generated code** manually in the code panel
+- Re-generate if the code looks wrong
+
+---
+
+## 10. Run the Test
+
+**From the Studio:**
+- Open the case, click the **▶ Run** button in the toolbar
+- Watch real-time progress in the run panel — each step lights up green/red
+
+**From the CLI:**
+```bash
+# Run a specific suite
+npx assuremind run --suite "Login Tests"
+
+# Run a single test
+npx assuremind run --test "User can log in with valid credentials"
+
+# Run all suites
+npx assuremind run --all
+
+# Watch the browser while running
+npx assuremind run --all --headed
+
+# Run in CI mode (exit code 0=pass, 1=fail)
+npx assuremind run --all --ci
+```
+
+---
+
+## 11. View Results & Reports
+
+After a run completes:
+
+**In the Studio:**
+- Click **Reports** in the sidebar to see run history
+- Click any run to see per-suite, per-case, per-step results
+- Screenshots and traces are linked directly in the result view
+- Click the Allure icon (📊) on any run/case to open the full Allure HTML report
+
+**Result files saved to:**
+```
+results/
+├── screenshots/    ← PNG screenshots on failure
+├── videos/         ← MP4 recordings (if video enabled)
+├── traces/         ← Playwright .zip traces (open with trace viewer)
+└── reports/        ← HTML and Allure reports
+```
+
+**Open a trace in Playwright Trace Viewer:**
+```bash
+npx playwright show-trace results/traces/my-test.zip
+```
+
+---
+
+## 12. Use Variables (Credentials & Dynamic Data)
+
+Variables let you keep credentials and environment-specific values out of your test steps.
+
+**Define variables** in `variables/global.json`:
+
+```json
+{
+  "BASE_URL": "http://localhost:3000",
+  "USERNAME": "admin@example.com",
+  "PASSWORD": { "value": "supersecret", "secret": true }
+}
+```
+
+**Reference in steps** with `{{KEY}}`:
+```
+Enter "{{USERNAME}}" in the email field
+Enter "{{PASSWORD}}" in the password field
+```
+
+**Environment-specific variables** (override globals per env):
+- `variables/dev.env.json` — used with `--env dev`
+- `variables/staging.env.json` — used with `--env staging`
+- `variables/prod.env.json` — used with `--env prod`
+
+```bash
+npx assuremind run --all --env staging
+```
+
+**Manage via Studio:** Settings → Variables page lets you add/edit/delete variables with a UI.
+
+---
+
+## 13. Self-Healing
+
+When a test step fails because the UI changed (e.g. a selector is stale), Assuremind automatically tries up to 6 healing strategies:
+
+| Level | Strategy |
+|-------|----------|
+| 1 | Smart Retry — wait + retry the same code |
+| 2 | AI Regeneration — AI rewrites the step code |
+| 3 | Multi-Selector — try alternative selectors |
+| 4 | Visual/SoM — screenshot + AI visual analysis |
+| 5 | Decompose — break step into sub-actions |
+| 6 | Manual — flag for human review |
+
+Healed steps are saved as **pending suggestions** for you to review:
+
+```bash
+# Interactive review in terminal
+npx assuremind apply-healing
+
+# Accept all silently (good for CI)
+npx assuremind apply-healing --yes
+```
+
+Or review in the Studio → **Self-Healing** page.
+
+---
+
+## 14. CI/CD Integration
+
+**GitHub Actions example:**
+
+```yaml
+name: E2E Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      - name: Run E2E tests
+        env:
+          AI_PROVIDER: anthropic
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: npx assuremind run --all --ci
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results
+          path: results/
+
+      - name: Apply healing suggestions (on failure)
+        if: failure()
+        run: npx assuremind apply-healing --yes
+```
+
+**Environment variables for CI:**
+
+```bash
+# Required
+AI_PROVIDER=anthropic
+ANTHROPIC_API_KEY=...
+
+# Optional: disable healing in CI to save cost
+HEALING_ENABLED=false
+```
+
+---
+
+## 15. Next Steps
+
+| Topic | Resource |
+|-------|----------|
+| Full Studio UI walkthrough | `docs/STUDIO.md` |
+| All CLI commands | `docs/CLI-REFERENCE.md` |
+| Quick-reference cheat sheet | `TESTAUTOMIND.md` |
+| All AI provider options | `.env.example` |
+
+Run `npx assuremind doctor` at any time to check your setup health.