ghostrun-cli 1.0.0 → 1.0.2

package/REFERENCE.md

@@ -0,0 +1,165 @@
+# GhostRun — Flow Actions Reference
+
+Complete reference for all actions you can use in recorded or hand-crafted `.flow.json` files.
+
+---
+
+## Browser Actions
+
+### Navigation
+
+| Action | Fields | Description |
+|--------|--------|-------------|
+| `navigate` | `url` | Go to URL |
+| `reload` | — | Reload the current page |
+| `back` | — | Browser back |
+| `forward` | — | Browser forward |
+
+### Interaction
+
+| Action | Fields | Description |
+|--------|--------|-------------|
+| `click` | `selector` | Left-click an element |
+| `dblclick` | `selector` | Double-click an element |
+| `fill` | `selector`, `value` | Clear field and type value |
+| `type` | `selector`, `value`, `delay?` | Type with configurable key delay (ms) |
+| `clear` | `selector` | Clear a field |
+| `select` | `selector`, `value` | Select a dropdown option by value |
+| `check` | `selector`, `value: "true"\|"false"` | Check/uncheck a checkbox |
+| `focus` | `selector` | Focus an element |
+| `hover` | `selector` | Mouse hover |
+| `drag` | `selector`, `targetSelector` | Drag one element to another |
+| `keyboard` | `key`, `selector?` | Press a key (e.g. `Enter`, `Tab`, `Control+a`) |
+| `upload` | `selector`, `value` | Set file input (comma-separated paths) |
+
+### Waiting
+
+| Action | Fields | Description |
+|--------|--------|-------------|
+| `wait` | `selector` | Wait for element to appear |
+| `wait:text` | `selector`, `value` | Wait until element contains text |
+| `wait:url` | `value` | Wait for URL to match pattern |
+| `wait:ms` | `value` | Wait for N milliseconds |
+
+### Scrolling
+
+| Action | Fields | Description |
+|--------|--------|-------------|
+| `scroll` | `selector?` | Scroll to element (or page) |
+| `scroll:element` | `selector` | Scroll element into view |
+| `scroll:bottom` | — | Scroll to bottom of page |
+| `scroll:load` | `value?` | Scroll to bottom, wait for load (repeat N times) |
+| `next:page` | `selector?` | Click next page link and wait |
+
+### Assertions
+
+| Action | Fields | Description |
+|--------|--------|-------------|
+| `assert:visible` | `selector` | Assert element is visible |
+| `assert:hidden` | `selector` | Assert element is not visible |
+| `assert:text` | `selector`, `value` | Assert element contains text |
+| `assert:not-text` | `selector`, `value` | Assert element does NOT contain text |
+| `assert:value` | `selector`, `value` | Assert input value |
+| `assert:count` | `selector`, `value` | Assert number of matching elements |
+| `assert:attr` | `selector`, `value: "attr=expected"` | Assert element attribute |
+
+### Data Extraction
+
+| Action | Fields | Description |
+|--------|--------|-------------|
+| `extract` | `selector`, `variable: "variableName"` | Extract element text → variable |
+| `screenshot` | — | Capture screenshot at this step |
+
+### Browser State
+
+| Action | Fields | Description |
+|--------|--------|-------------|
+| `cookie:set` | `value: "name=value; domain=..."` | Set a cookie |
+| `cookie:clear` | — | Clear all cookies |
+| `storage:set` | `selector: "key"`, `value: "val"` | Set localStorage item |
+| `eval` | `value` | Execute JavaScript on the page |
+| `iframe:enter` | `selector` | Enter an iframe context |
+| `iframe:exit` | — | Exit iframe context, return to main frame |
+
+---
+
+## API Actions
+
+### HTTP Requests
+
+| Action | Fields | Description |
+|--------|--------|-------------|
+| `http:request` | `method`, `url`, `headers?`, `body?`, `auth?`, `extract?` | Make an HTTP request. `auth` supports `{ type: "bearer", token: "{{var}}" }`. `extract` is a map of `variableName → $.jsonPath`. |
+
+### Assertions
+
+| Action | Fields | Description |
+|--------|--------|-------------|
+| `assert:response` | `assert: "status"`, `expected` | Assert HTTP status code |
+| `assert:response` | `assert: "json:path"`, `path`, `expected` | Assert JSONPath value equals expected |
+| `assert:response` | `assert: "json:exists"`, `path` | Assert JSONPath exists in response |
+| `assert:response` | `assert: "header"`, `header`, `expected` | Assert response header value |
+| `assert:response` | `assert: "body:contains"`, `expected` | Assert raw body contains string |
+| `assert:response` | `assert: "time"`, `expected` | Assert response time < expected ms |
+
+### Variables & Flow Control
+
+| Action | Fields | Description |
+|--------|--------|-------------|
+| `set:variable` | `variable`, `value` | Set a named variable (supports `{{interpolation}}`) |
+| `extract:json` | `variable`, `path` | Extract a value from the last response body via JSONPath |
+| `env:switch` | `value` | Switch active environment mid-flow |
+
+---
+
+## Variables
+
+Use `{{variableName}}` in any `value`, `url`, `selector`, or `body` field:
+
+```json
+{ "action": "fill", "selector": "#email", "value": "{{userEmail}}" }
+```
+
+Pass at runtime:
+
+```bash
+ghostrun run <id> --var userEmail=user@example.com
+```
+
+Values extracted with `extract:` and `extract:json` are automatically available as variables in subsequent steps.
+
+---
+
+## Limitations
+
+| Interaction | Status | Notes |
+|------------|--------|-------|
+| Canvas drawing | ❌ | `<canvas>` elements — no visual capture |
+| WebGL / Three.js | ❌ | GPU-rendered content |
+| Browser native dialogs | ⚠️ Partial | `alert()`/`confirm()`/`prompt()` auto-dismissed |
+| File download verification | ⚠️ Partial | Download triggers but content is not validated |
+| WebRTC / media streams | ❌ | Camera, mic, screen capture APIs |
+| Browser extensions | ❌ | Extension UI not accessible via Playwright |
+| Shadow DOM (closed mode) | ⚠️ Limited | Open shadow DOM works; closed mode needs `eval` workaround |
+| Multi-tab / popup flows | ⚠️ Partial | New tabs opened by click are not automatically followed |
+| OS-level dialogs | ❌ | Native file picker, print dialog, OS auth prompts |
+| CAPTCHAs | ❌ | By design — no circumvention |
+| Biometric auth | ❌ | Touch ID, Face ID, WebAuthn |
+| Browser gestures (pinch/zoom) | ❌ | Mobile multi-touch gestures |
+| Hover-only menus (CSS `:hover`) | ✅ | Use `hover` action before clicking submenu items |
+| Right-click context menus | ⚠️ Limited | Browser context menus inaccessible; app-level menus often work |
+| Drag and drop | ✅ | Use `drag` with `selector` + `targetSelector` |
+| Infinite scroll / lazy load | ✅ | Use `scroll:load` with repeat count |
+
+**Workarounds:**
+
+```json
+// Run JS directly
+{ "action": "eval", "value": "document.querySelector('#btn').click()" }
+
+// Shadow DOM
+{ "action": "eval", "value": "document.querySelector('my-el').shadowRoot.querySelector('button').click()" }
+
+// Timing-sensitive steps
+{ "action": "wait:ms", "value": "500" }
+```

package/ghostrun.js

@@ -3644,7 +3644,7 @@ var import_uuid = require("uuid");
 var HOME_DIR = process.env.HOME || process.env.USERPROFILE || ".";
 var DATA_PATH = path.join(HOME_DIR, ".ghostrun");
 var DB_PATH = path.join(DATA_PATH, "data", "ghostrun.db");
-var DatabaseManager = class {
+var DatabaseManager = class _DatabaseManager {
   db;
   constructor() {
     fs.mkdirSync(path.join(DATA_PATH, "data"), { recursive: true });
@@ -3982,35 +3982,72 @@ var DatabaseManager = class {
     };
   }
   // ---- DB migrations ----
+  //
+  // Uses SQLite's built-in PRAGMA user_version as a schema version counter.
+  // Each migration runs exactly once: we read the current version, apply every
+  // migration whose index is >= that version (in order), then write the new version.
+  //
+  // HOW TO ADD A NEW MIGRATION:
+  //   1. Append a new string to the MIGRATIONS array below.
+  //   2. That's it. The runner handles the rest.
+  //
+  // Never edit or reorder existing entries — just append.
+  static MIGRATIONS = [
+    // v1: add diff_percent to steps
+    "ALTER TABLE steps ADD COLUMN diff_percent REAL",
+    // v2: add created_by to flows
+    "ALTER TABLE flows ADD COLUMN created_by TEXT NOT NULL DEFAULT 'human'",
+    // v3: add verified flag to flows
+    "ALTER TABLE flows ADD COLUMN verified INTEGER NOT NULL DEFAULT 0",
+    // v4: add captured_at to run_data
+    "ALTER TABLE run_data ADD COLUMN captured_at TEXT DEFAULT (datetime('now'))",
+    // v5: environments table
+    `CREATE TABLE IF NOT EXISTS environments (
+      id TEXT PRIMARY KEY, name TEXT NOT NULL UNIQUE, base_url TEXT,
+      variables TEXT NOT NULL DEFAULT '{}', is_active INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    )`,
+    // v6: api_responses table
+    `CREATE TABLE IF NOT EXISTS api_responses (
+      id TEXT PRIMARY KEY, run_id TEXT NOT NULL, step_number INTEGER NOT NULL,
+      method TEXT NOT NULL, url TEXT NOT NULL, status_code INTEGER,
+      response_time_ms INTEGER, response_headers TEXT, response_body TEXT,
+      error_message TEXT, created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    )`,
+    // v7: perf_runs table
+    `CREATE TABLE IF NOT EXISTS perf_runs (
+      id TEXT PRIMARY KEY, flow_id TEXT NOT NULL, flow_name TEXT NOT NULL,
+      config TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'running',
+      total_requests INTEGER, success_requests INTEGER, failed_requests INTEGER,
+      avg_rps REAL, p50_ms INTEGER, p95_ms INTEGER, p99_ms INTEGER,
+      min_ms INTEGER, max_ms INTEGER, per_step_stats TEXT,
+      started_at TEXT NOT NULL DEFAULT (datetime('now')), completed_at TEXT
+    )`
+    // --- add new migrations below this line ---
+  ];
+  // Number of migrations that existed before we introduced versioning.
+  // Existing databases have these applied already (via old try/catch approach)
+  // but their user_version is 0. We detect this and fast-forward rather than
+  // re-running them (which would throw "duplicate column" errors).
+  static LEGACY_MIGRATION_COUNT = 7;
+  columnExists(table, column) {
+    const cols = this.db.pragma(`table_info(${table})`);
+    return cols.some((c) => c.name === column);
+  }
   runMigrations() {
-    try {
-      this.db.exec("ALTER TABLE steps ADD COLUMN diff_percent REAL");
-    } catch {
-    }
-    try {
-      this.db.exec("ALTER TABLE flows ADD COLUMN created_by TEXT NOT NULL DEFAULT 'human'");
-    } catch {
-    }
-    try {
-      this.db.exec("ALTER TABLE flows ADD COLUMN verified INTEGER NOT NULL DEFAULT 0");
-    } catch {
-    }
-    try {
-      this.db.exec("ALTER TABLE run_data ADD COLUMN captured_at TEXT DEFAULT (datetime('now'))");
-    } catch {
-    }
-    try {
-      this.db.exec(`CREATE TABLE IF NOT EXISTS environments (id TEXT PRIMARY KEY, name TEXT NOT NULL UNIQUE, base_url TEXT, variables TEXT NOT NULL DEFAULT '{}', is_active INTEGER NOT NULL DEFAULT 0, created_at TEXT NOT NULL DEFAULT (datetime('now')))`);
-    } catch {
-    }
-    try {
-      this.db.exec(`CREATE TABLE IF NOT EXISTS api_responses (id TEXT PRIMARY KEY, run_id TEXT NOT NULL, step_number INTEGER NOT NULL, method TEXT NOT NULL, url TEXT NOT NULL, status_code INTEGER, response_time_ms INTEGER, response_headers TEXT, response_body TEXT, error_message TEXT, created_at TEXT NOT NULL DEFAULT (datetime('now')))`);
-    } catch {
-    }
-    try {
-      this.db.exec(`CREATE TABLE IF NOT EXISTS perf_runs (id TEXT PRIMARY KEY, flow_id TEXT NOT NULL, flow_name TEXT NOT NULL, config TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'running', total_requests INTEGER, success_requests INTEGER, failed_requests INTEGER, avg_rps REAL, p50_ms INTEGER, p95_ms INTEGER, p99_ms INTEGER, min_ms INTEGER, max_ms INTEGER, per_step_stats TEXT, started_at TEXT NOT NULL DEFAULT (datetime('now')), completed_at TEXT)`);
-    } catch {
+    let currentVersion = this.db.pragma("user_version", { simple: true }) ?? 0;
+    if (currentVersion === 0 && this.columnExists("steps", "diff_percent")) {
+      currentVersion = _DatabaseManager.LEGACY_MIGRATION_COUNT;
+      this.db.pragma(`user_version = ${currentVersion}`);
     }
+    if (currentVersion >= _DatabaseManager.MIGRATIONS.length) return;
+    const applyAll = this.db.transaction(() => {
+      for (let i = currentVersion; i < _DatabaseManager.MIGRATIONS.length; i++) {
+        this.db.exec(_DatabaseManager.MIGRATIONS[i]);
+      }
+      this.db.pragma(`user_version = ${_DatabaseManager.MIGRATIONS.length}`);
+    });
+    applyAll();
   }
   // ---- Suites ----
   createSuite(data) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ghostrun-cli",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Browser automation + API testing + load testing in one tool. Record flows, test REST APIs, run VU-based load tests, export to k6. Entirely local.",
   "main": "ghostrun.js",
   "bin": {
@@ -8,13 +8,21 @@
     "ghostrun-mcp": "mcp-server.js"
   },
   "keywords": [
-    "browser-automation", "api-testing", "load-testing", "playwright",
-    "test-runner", "cli", "k6", "local-first", "mcp", "e2e-testing"
+    "browser-automation",
+    "api-testing",
+    "load-testing",
+    "playwright",
+    "test-runner",
+    "cli",
+    "k6",
+    "local-first",
+    "mcp",
+    "e2e-testing"
   ],
   "homepage": "https://ghostrun.builtbysharan.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/builtbysharan/ghostrun"
+    "url": "https://github.com/TechBuiltBySharan/ghostrun"
   },
   "license": "MIT",
   "scripts": {