# 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 **`ASSUREMIND.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,
  },
  mcp: {
    enabled: true,         // AI sees real page elements during code generation
    headless: true,        // MCP browser runs without visible window
    actThenScript: false,  // Two-phase generation (higher accuracy, slower)
    proactiveHealing: false, // Pre-run selector validation
  },
  rag: {
    enabled: true,         // AI learns from past runs (semantic memory)
    codeCorpus: { enabled: true, maxEntries: 500, similarityThreshold: 0.65, directUseThreshold: 0.90 },
    healingCorpus: { enabled: true, maxEntries: 300, similarityThreshold: 0.60 },
    errorCatalog: { enabled: true, maxEntries: 200 },
    embedder: 'tfidf',     // local, free, offline — no API calls
  },
});
```

---

## 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 — Record a test (fastest, zero AI)

Start the Studio and use the built-in **Test Recorder** to create tests by clicking through your app:

1. Click **Test Editor** → select a suite and case (or create new ones)
2. Click the red **Record** button in the step editor
3. A headed Chromium browser opens your app — interact naturally:
   - Click buttons, fill forms, navigate pages
   - Elements **inside iframes** are captured automatically — generates correct `frameLocator()` code
   - Elements **inside shadow roots** (Web Components) are captured via `composedPath()` — generates `>>` pierce locators
   - **JS alerts/confirms** are auto-accepted and a `page.once('dialog', ...)` handler is prepended to the triggering step
   - **Keyboard** — Tab, Shift+Tab, arrow keys, Ctrl+A, Enter, Escape, and Space on buttons are all recorded
   - **Shift+Click** any element to assert it's visible (hard assertion — test stops on failure)
   - **Ctrl+Shift+Click** any element for a **soft assertion** (test continues, failures collected at end)
   - **Ctrl+Shift+U** to assert the current URL
   - **Ctrl+Shift+T** to assert the page title
4. Click **Stop Recording** — all actions become steps with pre-generated Playwright code
5. Click **Run** to execute immediately

**No AI calls, no API keys needed** — the recorder resolves locators against Playwright's accessibility tree in real time. The recorder is available for **UI** and **Audit** suites only (not API suites).

### Option C — 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 D — 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 (per-environment + CI secrets)

Variables let you avoid hardcoding credentials and URLs. Reference them in steps with double-braces:

```
Enter "{{ADMIN_EMAIL}}" in the email field
Enter "{{ADMIN_PASSWORD}}" in the password field
```

### Environments
Projects define a set of environments — by default **DEV, TEST, STAGE, INT, PROD** — editable in **Settings → Environment** (add, rename, delete, and set a base URL per environment). The **active** environment determines which values and base URL a run uses (override per run with `--env <NAME>`).

### Per-environment values
In **Studio → Variables**, each variable can hold a different value **per environment**, plus a **Global (default)** that applies when an environment has no specific value. On disk this is plain JSON:

```
variables/global.json        # defaults
variables/DEV.env.json        # DEV overrides
variables/PROD.env.json       # PROD overrides
```

```jsonc
// variables/global.json
{ "ADMIN_EMAIL": "admin@example.com",
  "ADMIN_PASSWORD": { "value": "local_secret", "secret": true } }

// variables/PROD.env.json  — overrides only for PROD
{ "ADMIN_PASSWORD": { "value": "prod_secret", "secret": true } }
```

### CI/CD secret overrides (highest priority)
At runtime, resolution is: **`AM_<KEY>` env var → environment value → global default**.

To override `{{MY_VAR}}` from a CI pipeline, inject the secret as **`AM_MY_VAR`** (not `MY_VAR`). The `AM_` prefix prevents accidental collisions with OS/shell variables that exist on every machine — common names like `USERNAME`, `HOME`, `PORT`, `PATH`, `USER` are left untouched.

**GitHub Actions example:**
```yaml
env:
  AM_ADMIN_PASSWORD: ${{ secrets.ADMIN_PASSWORD }}
  AM_API_KEY: ${{ secrets.API_KEY }}
```

Locally (no `AM_` vars set) the stored environment or global value is used. In CI the prefixed secret wins.

> Tip: keep real production secrets **out of the repo** — store a placeholder locally and inject the real value via `AM_`-prefixed CI secrets.

Manage all of this in the Studio → **Variables** page (environment grid) and **Settings → Environment**.

---

## 12. RAG Memory — AI Gets Smarter Over Time

RAG (Retrieval-Augmented Generation) is **ON by default — zero setup required**. The AI automatically learns from every test run:

- **Run 1** — memory is empty, AI generates code normally
- **Run 2+** — similar instructions are retrieved from past runs instead of making API calls (free + faster)
- **Run 10+** — most common steps served from memory at zero cost, self-healing resolves issues on the first attempt

### What happens automatically

| Event | What RAG does |
|-------|---------------|
| Step passes | Remembers the instruction → code mapping |
| Step fails | Records the error pattern for that URL |
| Healing fixes a step | Remembers the error → fix pair |
| Next similar step | Retrieves past code instead of calling AI ($0) |
| Next similar error | Uses proven past fix in the healing prompt |

### Storage

RAG data lives in `results/.rag/` as plain JSON files. To share memory across your team, commit it to Git. To reset, delete the folder.

### When to change RAG settings

Most users **never need to touch RAG settings**. The Settings → RAG Memory card exists for edge cases:

| Scenario | Action |
|----------|--------|
| Debugging a flaky test | Turn OFF Code Corpus — forces fresh AI generation |
| Healing keeps suggesting a bad fix | Turn OFF Healing Corpus |
| Major app redesign | Turn OFF RAG entirely — old memory is misleading |
| Want deterministic CI runs | Disable RAG in CI, keep ON locally |

---

## Advanced Step Patterns

The AI handles complex browser scenarios from plain English — no special syntax needed:

| Scenario | Example instruction |
|----------|-------------------|
| **Accept a JS alert** | `Accept the alert dialog` |
| **Dismiss a confirm popup** | `Dismiss the confirmation popup` |
| **Enter text in a prompt** | `Enter "yes" in the prompt and accept` |
| **Shadow DOM click** | `Click the submit button inside the my-form component` |
| **Shadow DOM fill** | `Fill the email input inside custom-input with "user@example.com"` |
| **Iframe click** | `Click the Submit button inside the payment iframe` |
| **Iframe fill** | `Enter "4111..." in the card number field inside the checkout frame` |
| **Press a key** | `Press Enter` / `Press Escape to close the modal` |
| **Keyboard shortcut** | `Press Ctrl+A to select all` / `Press Shift+Tab` |
| **Type via keyboard** | `Type "Hello World" using the keyboard` |

### Stopping a run

While a run is in progress in the Studio, a red **Stop** button appears in the execution header. Click it to immediately signal the server to stop — remaining test cases are skipped and the run exits cleanly.

---

## What's New — Enterprise Features

Assuremind v1.3 adds 6 enterprise-grade features, all accessible from the Studio sidebar:

| Feature | Studio Page | What it does |
|---------|------------|-------------|
| **Faker Data** | `/data-templates` | 100+ generators with multi-select — pick multiple tokens at once, inserted comma-separated, auto-refresh on every run |
| **Visual Regression** | Settings + Reports | Configure in Settings → Visual Regression; review diffs and baselines in Reports tabs |
| **CI/CD Integration** | `/ci-integration` | Quality gates, PR comments, Slack/Teams notifications |

All features are configured from the Studio UI — no code, no config files, no terminal required.

---

## 13. Next Steps

| Topic | Where to look |
|-------|---------------|
| Test Recorder | [Studio Guide → Test Recorder](./STUDIO.md#test-recorder) |
| 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 |
| MCP integration | Settings page → MCP Integration |
| RAG memory | Settings page → RAG Memory |
| All supported AI providers | `.env.example` |
| Quick daily reference | `ASSUREMIND.md` in your project root |