assuremind 1.0.0

package/templates/docs/STUDIO.md

@@ -0,0 +1,625 @@
+# Assuremind Studio — UI Walkthrough
+
+> End-to-end guide for using every page and feature in the Assuremind Studio.
+
+Start the Studio:
+```bash
+npx assuremind studio
+```
+Opens at **http://localhost:4400**
+
+---
+
+## Table of Contents
+
+1. [Layout Overview](#1-layout-overview)
+2. [Dashboard](#2-dashboard)
+3. [Test Suites — Suite List](#3-test-suites--suite-list)
+4. [Suite Detail — Test Cases](#4-suite-detail--test-cases)
+5. [Case Editor — Writing Steps](#5-case-editor--writing-steps)
+6. [Case Editor — Generating Code](#6-case-editor--generating-code)
+7. [Case Editor — Running a Test](#7-case-editor--running-a-test)
+8. [Case Editor — Drag & Drop Step Reorder](#8-case-editor--drag--drop-step-reorder)
+9. [Variables Page](#9-variables-page)
+10. [Self-Healing Page](#10-self-healing-page)
+11. [Reports Page](#11-reports-page)
+12. [Settings Page](#12-settings-page)
+13. [Keyboard Shortcuts & Tips](#13-keyboard-shortcuts--tips)
+
+---
+
+## 1. Layout Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Assuremind Studio                           [version]     │
+├──────────────┬──────────────────────────────────────────────┤
+│              │                                              │
+│  Sidebar     │   Main Content Area                         │
+│              │                                              │
+│  🏠 Dashboard│                                              │
+│  ✨ Smart    │                                              │
+│  📁 Suites   │                                              │
+│  ▶ Run       │                                              │
+│  📊 Reports  │                                              │
+│  🔧 Variables│                                              │
+│  💚 Healing  │                                              │
+│  ⚙️  Settings │                                              │
+│  🌿 Git      │                                              │
+│              │                                              │
+└──────────────┴──────────────────────────────────────────────┘
+```
+
+The **Sidebar** provides navigation between all sections. The current active page is highlighted.
+
+---
+
+## 2. Dashboard
+
+The Dashboard gives you a quick health snapshot of your test project.
+
+### What you'll see
+
+| Section | Description |
+|---------|-------------|
+| **Total Suites** | Number of test suites in the project |
+| **Total Cases** | Total test cases across all suites |
+| **Last Run** | When the most recent run happened |
+| **Pass Rate** | Percentage of passing tests in the last run |
+| **Recent Runs** | List of the last 5–10 runs with status badges |
+
+### Quick actions from the Dashboard
+
+- Click any recent run row → opens the detailed run result
+- Click **"New Suite"** shortcut → creates a new test suite directly
+
+---
+
+## 3. Test Suites — Suite List
+
+Navigate to **Suites** in the sidebar.
+
+### Creating a Suite
+
+1. Click **"+ New Suite"** (top-right)
+2. Fill in the form:
+   - **Name** — e.g. `Login Tests`, `Checkout Flow`
+   - **Description** *(optional)* — what this suite covers
+   - **Tags** *(optional)* — e.g. `smoke`, `regression`, `auth`
+3. Click **Create**
+
+The suite appears in the list with a badge showing case count.
+
+### Suite List Columns
+
+| Column | Description |
+|--------|-------------|
+| Name | Suite name — click to open |
+| Cases | Number of test cases |
+| Tags | Coloured tag badges |
+| Last Run | Pass/fail badge + relative time |
+| Actions | Edit (pencil), Delete (trash), Run (▶), Allure report (📊) |
+
+### Running a Suite from the List
+
+Click the **▶ Run** icon on any suite row. A run starts immediately in the background. The Last Run badge updates when it completes.
+
+### Editing / Deleting a Suite
+
+- **Edit** (pencil icon) → updates name, description, or tags
+- **Delete** (trash icon) → removes the suite and all its test cases (irreversible — confirm dialog shown)
+
+---
+
+## 4. Suite Detail — Test Cases
+
+Click on a suite name to open the Suite Detail page.
+
+### Header area
+
+- Suite name and description
+- Tag badges
+- **▶ Run Suite** button — runs all cases in this suite
+- **📊 Allure** button — opens the Allure HTML report for the last suite run
+- **+ New Case** button
+
+### Test Case List
+
+Each row shows:
+
+| Column | Description |
+|--------|-------------|
+| Name | Test case name — click to open Case Editor |
+| Steps | Number of steps in the case |
+| Status | Last run status badge (Passed / Failed / Not Run) |
+| Duration | Last run duration |
+| Actions | Edit, Delete, Run (▶), Allure (📊) |
+
+### Creating a Test Case
+
+1. Click **"+ New Case"**
+2. Enter:
+   - **Name** — e.g. `User can log in with valid credentials`
+   - **Description** *(optional)*
+   - **Tags** *(optional)*
+   - **Timeout** *(optional)* — override the global default (ms)
+3. Click **Create**
+
+### Running a Single Case
+
+Click **▶** on the case row, or open the case and use the Run button in the toolbar.
+
+---
+
+## 5. Case Editor — Writing Steps
+
+Click on a test case name to open the **Case Editor**. This is where you write, organise, and manage test steps.
+
+### Page Layout
+
+```
+┌────────────────────────────────────────────────────────────┐
+│  ← Back  |  Case Name                 [Generate All] [▶ Run]│
+├────────────────────────────────────────────────────────────┤
+│  Case Details (collapsible)                                 │
+│  Timeout: [30000 ms]  Tags: [...]                          │
+├────────────────────────────────────────────────────────────┤
+│  Steps                                            [+ Add]  │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │ ⠿  1  Go to the login page              [⚡][✏️][🗑️] │  │
+│  │      Code: await page.goto('/login');               │  │
+│  ├──────────────────────────────────────────────────────┤  │
+│  │ ⠿  2  Enter email in the email field    [⚡][✏️][🗑️] │  │
+│  │      Code: await page.getByLabel...    [timeout]   │  │
+│  └──────────────────────────────────────────────────────┘  │
+└────────────────────────────────────────────────────────────┘
+```
+
+### Adding a Step
+
+1. Click **"+ Add Step"**
+2. Type your plain-English instruction in the input field
+3. Press **Enter** or click **Add**
+
+The step is added at the bottom of the list.
+
+### Step Row Controls
+
+Each step row shows:
+
+| Control | Description |
+|---------|-------------|
+| **⠿** (grip icon) | Drag handle — use to reorder steps |
+| **Step number** | Order of the step (1, 2, 3…) |
+| **Instruction** | Plain-English description |
+| **Code panel** | Generated Playwright code (click to expand/edit) |
+| **Timeout field** | Per-step timeout override in ms (increment/decrement by 100) |
+| **⚡** | Generate/re-generate code for this step only |
+| **✏️** | Edit the step instruction |
+| **🗑️** | Delete the step |
+
+### Writing Good Step Instructions
+
+| Goal | Example Instruction |
+|------|---------------------|
+| Navigate | `Go to the login page` |
+| Navigate with URL | `Go to https://app.example.com/login` |
+| Click a button | `Click the Login button` |
+| Click a link | `Click the "Forgot Password" link` |
+| Fill a text field | `Enter "john@example.com" in the email field` |
+| Fill with variable | `Enter "{{USERNAME}}" in the username field` |
+| Select a dropdown | `Select "United States" from the country dropdown` |
+| Check a checkbox | `Check the "Remember me" checkbox` |
+| Assert visible | `Verify the success message is visible` |
+| Assert text | `Verify the heading contains "Welcome back"` |
+| Assert URL | `Verify the URL contains "/dashboard"` |
+| Assert count | `Verify there are 3 items in the cart` |
+| Wait | `Wait for the loading spinner to disappear` |
+| Hover | `Hover over the user avatar` |
+| Upload file | `Upload "fixtures/data/resume.pdf" to the file input` |
+| Press key | `Press the Escape key` |
+| Scroll | `Scroll down to the footer` |
+
+### Editing a Step Instruction
+
+1. Click **✏️** on any step
+2. Edit the instruction text in the inline input
+3. Press **Enter** or click away to save
+4. Re-generate the code if needed by clicking **⚡**
+
+### Setting Per-Step Timeout
+
+Each step row has a timeout field (right side of the row):
+- Default is blank (uses the case-level or global timeout)
+- Click the field and type a value in milliseconds, or use **↑ / ↓** arrows to increment/decrement in steps of 100ms
+- Use this to give extra time to slow steps like file uploads or heavy animations
+- Leave blank to inherit from the case/global timeout
+
+---
+
+## 6. Case Editor — Generating Code
+
+Assuremind uses AI to convert each plain-English step into Playwright TypeScript code.
+
+### Generate All Steps at Once
+
+Click **"Generate All"** in the Case Editor toolbar. The AI processes all steps in one batch — faster than generating one by one.
+
+Progress is shown in the toolbar while generation is running.
+
+### Generate a Single Step
+
+Click the **⚡** icon on any step row. Useful when:
+- You added a new step after batch generation
+- The generated code looks wrong and you want to retry
+- You edited the instruction and need fresh code
+
+### Viewing / Editing Generated Code
+
+Each step row has an expandable code panel below the instruction:
+
+```
+┌─ Step 3 ────────────────────────────────────────────────┐
+│  Click the Login button                      [⚡][✏️][🗑️]│
+│  ─────────────────────────────────────────────────────── │
+│  await page.getByRole('button', { name: 'Login' })       │
+│       .click();                                          │
+│                                              [timeout: ] │
+└──────────────────────────────────────────────────────────┘
+```
+
+Click on the code area to edit it manually. This is useful when:
+- The AI generated a selector you want to adjust
+- You want to add a more specific assertion
+- You need to use a hardcoded value the AI doesn't know
+
+### Code Generation Tips
+
+- The more specific your instruction, the better the code. `Click the blue Submit button in the modal` is better than `Click Submit`
+- For buttons, include the word `button` in the instruction — the AI uses `getByRole('button', { name: '...' })` automatically
+- For form fields, include the field label: `Enter text in the Email Address field`
+- Variables in `{{VAR}}` format are substituted at runtime, not at code generation time
+
+---
+
+## 7. Case Editor — Running a Test
+
+### Run from the Case Editor
+
+Click the **▶ Run** button in the Case Editor toolbar to run the current test case.
+
+A **Run Panel** appears at the bottom of the editor showing:
+
+```
+┌─ Run Panel ─────────────────────────────────────────────────┐
+│  Status: Running…                                           │
+│  ─────────────────────────────────────────────────────────── │
+│  ✅  Step 1: Go to the login page              (0.4s)       │
+│  ✅  Step 2: Enter email in email field        (0.8s)       │
+│  ✅  Step 3: Enter password in password field  (0.6s)       │
+│  🔄  Step 4: Click the Login button            …            │
+│  ⬜  Step 5: Verify dashboard is visible                    │
+└──────────────────────────────────────────────────────────────┘
+```
+
+| Icon | Meaning |
+|------|---------|
+| ✅ | Step passed |
+| ❌ | Step failed |
+| 🔄 | Step currently running |
+| ⬜ | Step not yet reached |
+| ⚡ | Step was healed (self-healing kicked in) |
+
+### After a Run
+
+- Click any **failed step** to see the error message and screenshot
+- Click **📊 Allure** to open the full Allure report for this run
+- Click **Traces** to download or view the Playwright trace
+- If self-healing activated, a notification badge appears on the **Self-Healing** sidebar item
+
+---
+
+## 8. Case Editor — Drag & Drop Step Reorder
+
+Steps can be rearranged without deleting and recreating them.
+
+### How to reorder
+
+1. Hover over any step row — the **⠿ grip icon** (left side) becomes visible
+2. Click and **hold** the grip icon
+3. **Drag** the step up or down
+4. **Drop** it at the desired position — a blue highlight shows the drop target
+5. The new order is saved automatically
+
+The step numbers update immediately after the drop.
+
+This is useful when you realise a step needs to happen earlier or later in the flow, or when you're reorganising a test after adding new steps.
+
+---
+
+## 9. Variables Page
+
+Navigate to **Variables** in the sidebar.
+
+Variables let you store credentials, URLs, and any dynamic data outside of step instructions. They are referenced using `{{KEY}}` syntax.
+
+### Variable List
+
+The Variables page shows all variables defined in `variables/global.json` as an editable table:
+
+| Column | Description |
+|--------|-------------|
+| Key | Variable name (e.g. `USERNAME`) |
+| Value | The value (masked if secret) |
+| Secret | Lock icon if `"secret": true` |
+| Actions | Edit (pencil), Delete (trash) |
+
+### Adding a Variable
+
+1. Click **"+ Add Variable"**
+2. Enter:
+   - **Key** — uppercase with underscores recommended: `ADMIN_EMAIL`
+   - **Value** — the variable's value
+   - **Secret** — toggle on to mask the value (stored as `{ "value": "...", "secret": true }`)
+3. Click **Save**
+
+### Editing a Variable
+
+Click **✏️** on any variable row → update the value → click Save.
+
+### Deleting a Variable
+
+Click **🗑️** on the row → confirm the delete prompt.
+
+### Using Variables in Steps
+
+In any step instruction, wrap the variable name in double curly braces:
+
+```
+Enter "{{USERNAME}}" in the email field
+Enter "{{PASSWORD}}" in the password field
+Go to "{{BASE_URL}}/dashboard"
+```
+
+At runtime, Assuremind substitutes the actual values before executing the Playwright code. Variable names are **case-sensitive**.
+
+### Environment-Specific Variables
+
+Create separate JSON files for each environment:
+
+```
+variables/
+├── global.json        ← applies to all environments
+├── dev.env.json       ← overrides for --env dev
+├── staging.env.json   ← overrides for --env staging
+└── prod.env.json      ← overrides for --env prod
+```
+
+Environment variables override global ones when a matching key exists. Run with a specific environment:
+
+```bash
+npx assuremind run --all --env staging
+```
+
+---
+
+## 10. Self-Healing Page
+
+Navigate to **Self-Healing** in the sidebar.
+
+When a test step fails and Assuremind automatically heals it, the healing event appears here for review.
+
+### Stats Cards
+
+At the top of the page:
+
+| Card | Description |
+|------|-------------|
+| Total Events | All healing events ever recorded |
+| Pending Review | Events waiting for your decision |
+| Accepted | Heals you approved and applied to test files |
+| Rejected | Heals you rejected |
+
+### Pending Review Section
+
+These are the most important — heals that have been generated but not yet written back to your test files.
+
+Each healing card shows:
+
+```
+┌─────────────────────────────────────────────────┐
+│  Click the Login button          [Pending] [🗑️]  │
+│  Case: login-tests/user-can-log-in · Level 2: AI │
+├────────────────────────┬────────────────────────┤
+│  Before (failed)       │  After (healed)         │
+│  await page.getBy      │  await page.getByRole   │
+│  Text('Login').click() │  ('button', {name:      │
+│                        │  'Login'}).click()       │
+├────────────────────────┴────────────────────────┤
+│  [✅ Accept & Update File]  [✗ Reject]           │
+└──────────────────────────────────────────────────┘
+```
+
+| Field | Description |
+|-------|-------------|
+| Instruction | The step instruction that was healed |
+| Level | Which healing strategy succeeded (1–6) |
+| Before | The code that failed |
+| After | The AI-generated replacement code |
+
+### Accepting a Heal
+
+Click **"✅ Accept & Update File"** — the test file on disk is updated with the new code. The heal moves to the **Accepted** section. Next time the test runs, it uses the healed code.
+
+### Rejecting a Heal
+
+Click **"✗ Reject"** — the heal is dismissed. The original code stays unchanged. Use this when you believe the heal is wrong and want to fix the step manually.
+
+### Deleting an Event
+
+Click **🗑️** (top-right of any card) to remove the event entirely from the log.
+
+### Bulk Actions (toolbar buttons)
+
+| Button | Action |
+|--------|--------|
+| **Accept All** | Accept all pending heals at once |
+| **Delete All** | Clear the entire healing log |
+
+### Events are sorted newest-first
+
+The most recent healing events appear at the top in each section (Pending, Accepted, Rejected). The log is capped at 50 events total — oldest are pruned automatically.
+
+---
+
+## 11. Reports Page
+
+Navigate to **Reports** in the sidebar.
+
+### Run History List
+
+Each completed run appears as a row:
+
+| Column | Description |
+|--------|-------------|
+| Date/Time | When the run started |
+| Duration | Total run time |
+| Suites | How many suites were included |
+| Cases | Total test cases run |
+| Passed | Number of passing cases |
+| Failed | Number of failing cases |
+| Status | Overall pass/fail badge |
+| Actions | 📊 Allure report, 📄 JSON result |
+
+### Opening the Allure Report
+
+Click **📊** on any run row to open the interactive Allure HTML report in a new tab.
+
+Allure shows:
+- Suite → case → step breakdown
+- Failure messages and stack traces
+- Embedded screenshots at the exact failing step
+- Playwright trace viewer link
+- Test duration graphs
+- Tags and metadata
+
+### Run Detail View
+
+Click on any run row to expand the detail view:
+
+```
+Run: 2026-03-25 14:32 · Duration: 45s · 12/13 passed
+
+Suite: Login Tests           ✅ 3/3
+  ✅ User can log in              1.2s
+  ✅ User can log out             0.8s
+  ✅ Password reset flow          2.1s
+
+Suite: Checkout Flow         ❌ 2/3
+  ✅ Add item to cart             3.4s
+  ✅ Apply coupon code            2.7s
+  ❌ Complete payment             5.1s  ← click to see error
+```
+
+Clicking a failed case shows the error, screenshot, and links to the trace.
+
+---
+
+## 12. Settings Page
+
+Navigate to **Settings** in the sidebar. Changes are saved immediately to `autotest.config.json`.
+
+### General Settings
+
+| Setting | Description |
+|---------|-------------|
+| **Base URL** | The root URL of your application under test |
+| **Headless Mode** | Toggle: run browsers visibly or in background |
+| **Viewport** | Screen resolution preset (Standard/HD/Mobile/Tablet/Custom) |
+| **Step Timeout** | Maximum ms per step (default: 30000) |
+| **Retries** | How many times to retry a failed test (default: 1) |
+| **Parallel Workers** | How many tests run simultaneously (default: 1) |
+| **Page Load Strategy** | When to consider a page "loaded": `domcontentloaded` / `load` / `networkidle` |
+
+### Browser Settings
+
+| Setting | Description |
+|---------|-------------|
+| **Browsers** | Toggle Chromium / Firefox / WebKit |
+
+### Recording Settings
+
+| Setting | Description |
+|---------|-------------|
+| **Screenshots** | `off` / `on` / `only-on-failure` |
+| **Video** | `off` / `on` / `on-first-retry` / `retain-on-failure` |
+| **Trace** | `off` / `on` / `on-first-retry` / `retain-on-failure` |
+
+### Viewport Presets
+
+| Preset | Resolution |
+|--------|------------|
+| Standard | 1280 × 720 |
+| Laptop | 1366 × 768 |
+| Full HD | 1920 × 1080 |
+| Mobile | 390 × 844 |
+| Tablet | 768 × 1024 |
+| Custom | Enter any width × height |
+
+### Self-Healing Settings
+
+| Setting | Description |
+|---------|-------------|
+| **Enable Healing** | Toggle self-healing on/off |
+| **Max Level** | Highest healing level to attempt (1–6) |
+| **Daily Budget** | Max USD per day to spend on AI healing calls |
+| **Auto PR** | Auto-create pull requests for accepted heals (if Git remote configured) |
+
+### Reporting Settings
+
+| Setting | Description |
+|---------|-------------|
+| **Allure** | Generate Allure XML and HTML report |
+| **HTML** | Generate plain HTML summary report |
+| **JSON** | Save run result as JSON |
+
+### Studio Port
+
+Port the Studio server runs on (default: 4400). Restart Studio after changing.
+
+---
+
+## 13. Keyboard Shortcuts & Tips
+
+### Studio Navigation
+
+| Shortcut | Action |
+|----------|--------|
+| Click sidebar item | Navigate to that section |
+| Browser back button | Go to previous page |
+
+### Case Editor
+
+| Action | How |
+|--------|-----|
+| Add a step | Click "+ Add Step" or press Enter in the last step input |
+| Reorder steps | Drag the ⠿ grip icon up/down |
+| Generate single step | Click ⚡ icon on the step row |
+| Generate all steps | Click "Generate All" in toolbar |
+| Edit step instruction | Click ✏️ icon |
+| Delete step | Click 🗑️ icon |
+| Set step timeout | Click timeout field → type or use ↑↓ arrows (100ms increments) |
+| Run case | Click ▶ Run in toolbar |
+
+### Tips for Better Tests
+
+1. **Run your app first** — make sure `baseUrl` is reachable before running tests
+2. **Use the headed mode** to watch the browser during development: `--headed` flag or toggle in Settings
+3. **Name cases clearly** — `User can log in with valid credentials` is better than `Login test 1`
+4. **One flow per case** — keep each test case focused on one user journey
+5. **Set step timeouts** for slow operations like file uploads or email sending
+6. **Use variables** for any value that differs between environments or testers
+7. **Accept heals promptly** — review the Self-Healing page after test runs
+8. **Generate All before running** — don't run a case with empty code panels
+9. **Check the trace** on failures — Playwright traces show exactly what happened step by step
+10. **Use tags** on suites/cases to run subsets: `npx assuremind run --tag smoke`