@matware/e2e-runner 1.2.1 → 1.3.0

package/skills/e2e-testing/references/troubleshooting.md

@@ -148,8 +148,8 @@ Or use `assert_no_network_errors` at specific points:
 Use network log drill-down:
 ```
 e2e_network_logs(runDbId, errorsOnly: true)                    → see all failed requests
-e2e_network_logs(runDbId, urlPattern: "/api/patients")          → filter by URL
-e2e_network_logs(runDbId, testName: "create-patient", includeBodies: true) → full request/response
+e2e_network_logs(runDbId, urlPattern: "/api/users")             → filter by URL
+e2e_network_logs(runDbId, testName: "create-user", includeBodies: true) → full request/response
 ```
 
 ## Common Mistakes
@@ -180,3 +180,45 @@ When checking paths, use path-only format (starts with `/`):
 { "type": "assert_url", "value": "/dashboard" }
 ```
 This compares against the pathname only, ignoring the `host.docker.internal` origin.
+
+## Action Type Pre-Validation
+
+All action types are validated at **load time** (before any browser connections). If a test file contains an unknown action type (e.g., a typo like `"clik"`), loading throws immediately with the location:
+
+```
+Unknown action type(s) in auth.json: "clik" in test "login-test"
+```
+
+The `KNOWN_ACTION_TYPES` Set in `src/actions.js` is the single source of truth. Unknown actions also throw at runtime as a safety net.
+
+## Screenshot Hashes
+
+Every screenshot captured during a run is assigned a short hash (`ss:a3f2b1c9`) — the first 8 hex chars of the SHA-256 of its file path. Hashes are deterministic and computed identically on the server (Node `crypto`) and in the browser (Web Crypto API).
+
+**Flow**: screenshot saved on disk → `saveRun()` registers hash in SQLite `screenshot_hashes` table → dashboard shows `[ss:XXXXXXXX]` badge (click to copy) → user pastes hash in Claude Code → `e2e_screenshot` MCP tool looks up hash, reads file, returns the image.
+
+- Hashes are registered inside the `saveRun()` transaction (covers action, error, verification, and baseline screenshots)
+- The `ss:` prefix is optional when calling `e2e_screenshot` — stripped during lookup
+- Dashboard computes hashes client-side (Web Crypto) for the Live view (before `persistRun()` writes to DB)
+- Run detail API (`/api/db/runs/:id`) includes `screenshotHashes` map per test result
+- Dashboard endpoint `/api/screenshot-hash/:hash` serves the image by hash
+- Dashboard Screenshots view has a **search bar** — type a hash to find and display the screenshot
+
+## Web Dashboard
+
+**`src/dashboard.js`** — HTTP server, REST API, WebSocket broadcast, pool polling.
+**`templates/dashboard.html`** — SPA, dark theme, vanilla JS, safe DOM (textContent + createEl helper).
+
+**Features:**
+- Live test execution with WebSocket updates
+- Run history with inline detail expansion
+- Screenshots gallery with hash badges and hash search
+- Network request logs with clickable expandable rows (full request/response detail)
+- Pool status monitoring
+- Multi-project support via project selector
+- Variables tab with masked values, inline edit, add, and delete
+
+**CLI:** `e2e-runner dashboard [--port 8484]`
+**MCP tools:** `e2e_dashboard_start`, `e2e_dashboard_stop`
+
+Config defaults: `dashboardPort: 8484`, `maxHistoryRuns: 100`

package/skills/e2e-testing/references/variables.md

@@ -0,0 +1,41 @@
+# Variables Reference
+
+Variables replace hardcoded sensitive values (JWT tokens, user IDs, API keys, etc.) in test JSON. Stored in SQLite (`~/.e2e-runner/dashboard.db`), scoped per project and per suite, editable from the dashboard UI.
+
+## Syntax
+
+```
+{{var.TOKEN}}        → resolves from DB (suite scope → project scope)
+{{env.MY_VAR}}       → resolves from process.env
+{{param}}            → existing module param substitution (unchanged)
+```
+
+**Resolution priority:** suite vars > project vars > error if not found.
+
+## Usage in Test JSON
+
+```json
+{ "$use": "auth-jwt", "params": { "token": "{{var.JWT_TOKEN}}", "orgId": "{{var.ORG_ID}}" } }
+{ "type": "goto", "value": "/users/{{var.USER_ID}}/profile" }
+{ "type": "gql", "value": "{ user(id: \"{{var.USER_ID}}\") { name } }" }
+```
+
+## MCP Tool (`e2e_vars`)
+
+```
+e2e_vars({ action: "set", key: "TOKEN", value: "abc123", scope: "project" })
+e2e_vars({ action: "set", key: "TOKEN", value: "xyz789", scope: "auth" })  // suite-specific override
+e2e_vars({ action: "list" })
+e2e_vars({ action: "get", key: "TOKEN" })
+e2e_vars({ action: "delete", key: "TOKEN", scope: "project" })
+```
+
+## Dashboard UI
+
+Variables tab shows all variables grouped by scope. Values are masked by default (click to reveal). Inline edit, add new, and delete are supported.
+
+## REST API
+
+- `GET /api/db/projects/:id/variables` — list all vars for project
+- `PUT /api/db/projects/:id/variables` — set a variable `{ scope, key, value }`
+- `DELETE /api/db/projects/:id/variables/:scope/:key` — delete a variable

package/skills/e2e-testing/references/visual-verification.md

@@ -0,0 +1,89 @@
+# Visual Verification Reference
+
+Tests can include an `expect` field for AI-powered visual verification. No API key required — Claude Code itself does the visual judgment.
+
+## Expect Field Formats
+
+### String form — free-form description
+```json
+{
+  "name": "dashboard-loads",
+  "expect": "Should show the data table with at least 3 rows, no error messages, and the sidebar with navigation links",
+  "actions": [
+    { "type": "goto", "value": "/dashboard" },
+    { "type": "wait", "selector": ".data-table" }
+  ]
+}
+```
+
+### Array form — per-criterion checklist (each evaluated independently as PASS/FAIL)
+```json
+{
+  "name": "dashboard-loads",
+  "expect": [
+    "Data table visible with at least 3 rows",
+    "No error messages or red banners",
+    "Sidebar shows navigation links"
+  ],
+  "actions": [
+    { "type": "goto", "value": "/dashboard" },
+    { "type": "wait", "selector": ".data-table" }
+  ]
+}
+```
+
+## Double Screenshot (Before/After)
+
+When `expect` is present, the runner captures TWO screenshots:
+1. **Baseline** (`baseline-{name}-{timestamp}.png`) — captured BEFORE test actions run (after `beforeEach` hooks)
+2. **Verification** (`verify-{name}-{timestamp}.png`) — captured AFTER all actions complete
+
+Both hashes are registered in SQLite and returned in the MCP response for before/after comparison.
+
+## Verification Strictness
+
+Controls how strictly Claude Code evaluates visual verification. Set via:
+- Config: `verificationStrictness: 'moderate'`
+- CLI: `--verification-strictness strict`
+- Env: `VERIFICATION_STRICTNESS=strict`
+- MCP: `verificationStrictness: 'strict'` in `e2e_run` args
+
+| Level | Behavior |
+|-------|----------|
+| **`strict`** | No ambiguity allowed. If any criterion is unclear, not fully visible, or doubtful → FAIL. |
+| **`moderate`** (default) | Reasonable judgment. Minor cosmetic differences acceptable, functional mismatches → FAIL. |
+| **`lenient`** | Only fail on clear, obvious contradictions. |
+
+## MCP Response Format
+
+The `e2e_run` response includes a `verifications` array:
+```json
+{
+  "verifications": [
+    {
+      "name": "dashboard-loads",
+      "expect": ["Data table visible...", "No error messages..."],
+      "success": true,
+      "screenshotHash": "ss:a3f2b1c9",
+      "baselineScreenshotHash": "ss:b4e1c2d8",
+      "isChecklist": true
+    }
+  ],
+  "verificationInstructions": "Verification strictness: MODERATE — ..."
+}
+```
+
+## Verdict Format
+
+After calling `e2e_screenshot` for each hash (after + baseline), Claude Code reports a structured verdict:
+
+```
+TEST: dashboard-loads
+VERDICT: PASS
+STATE CHANGE: Page loaded from blank to populated dashboard
+CRITERIA:
+  - "Data table visible with at least 3 rows": PASS
+  - "No error messages or red banners": PASS
+  - "Sidebar shows navigation links": PASS
+REASON: All criteria met, dashboard fully loaded with expected content
+```

package/src/actions.js

@@ -8,7 +8,21 @@
  */
 
 import path from 'path';
-import { log } from './logger.js';
+
+/** All recognized action types — single source of truth for validation. */
+export const KNOWN_ACTION_TYPES = new Set([
+  'goto', 'click', 'type', 'fill', 'wait', 'screenshot',
+  'assert_text', 'assert_url', 'assert_visible', 'assert_count',
+  'assert_element_text', 'assert_attribute', 'assert_class',
+  'assert_not_visible', 'assert_input_value', 'assert_matches',
+  'assert_no_network_errors', 'assert_storage',
+  'get_text', 'select', 'clear', 'clear_cookies', 'press', 'scroll', 'hover',
+  'navigate', 'evaluate',
+  'type_react', 'click_regex', 'click_option', 'focus_autocomplete', 'click_chip',
+  'set_storage', 'click_icon', 'click_menu_item', 'click_in_context',
+  'assert_text_in', 'assert_no_text',
+  'gql', 'wait_network_idle',
+]);
 
 function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
@@ -102,6 +116,16 @@ export async function executeAction(page, action, config) {
       break;
     }
 
+    case 'assert_no_text': {
+      // Assert that text does NOT appear anywhere on the page.
+      // text: substring to check for absence (required)
+      const bodyTextNo = await page.evaluate(() => document.body.innerText);
+      if (bodyTextNo.includes(text)) {
+        throw new Error(`assert_no_text failed: "${text}" was found on the page but should not be present`);
+      }
+      break;
+    }
+
     case 'assert_url': {
       const currentUrl = page.url();
       let match = false;
@@ -240,6 +264,30 @@ export async function executeAction(page, action, config) {
       break;
     }
 
+    case 'assert_text_in': {
+      // Assert that text exists inside a scoped container element.
+      // selector: CSS selector for the container (required)
+      // text: substring or regex pattern to match against container's textContent (required)
+      // value: "i" for case-insensitive regex (default), "exact" for case-sensitive substring
+      if (!selector) throw new Error('assert_text_in requires "selector"');
+      if (!text) throw new Error('assert_text_in requires "text"');
+      await page.waitForSelector(selector, { timeout });
+      const containerText = await page.$$eval(selector, els => els.map(el => el.textContent).join(' '));
+      const flags = value === 'exact' ? '' : 'i';
+      if (value === 'exact') {
+        if (!containerText.includes(text)) {
+          const preview = containerText.length > 200 ? containerText.slice(0, 200) + '...' : containerText;
+          throw new Error(`assert_text_in failed: "${text}" not found in "${selector}"\n  Content: ${preview}`);
+        }
+      } else {
+        if (!new RegExp(text, flags).test(containerText)) {
+          const preview = containerText.length > 200 ? containerText.slice(0, 200) + '...' : containerText;
+          throw new Error(`assert_text_in failed: /${text}/${flags} not found in "${selector}"\n  Content: ${preview}`);
+        }
+      }
+      break;
+    }
+
     case 'get_text': {
       await page.waitForSelector(selector, { timeout });
       const getText = await page.$eval(selector, el => el.textContent.trim());
@@ -409,6 +457,273 @@ export async function executeAction(page, action, config) {
       break;
     }
 
+    case 'set_storage': {
+      // Set a localStorage or sessionStorage key.
+      // value: "key=val", selector: "session" for sessionStorage (default: localStorage)
+      const eqIdx = value.indexOf('=');
+      if (eqIdx === -1) {
+        throw new Error(`set_storage: value must be "key=value", got "${value}"`);
+      }
+      const storageKey = value.slice(0, eqIdx);
+      const storageVal = value.slice(eqIdx + 1);
+      const storageType = selector === 'session' ? 'sessionStorage' : 'localStorage';
+      await page.evaluate((sType, k, v) => {
+        window[sType].setItem(k, v);
+      }, storageType, storageKey, storageVal);
+      break;
+    }
+
+    case 'assert_storage': {
+      // Assert a localStorage or sessionStorage key exists or has a specific value.
+      // value: "key" (existence) or "key=expected" (value match)
+      // selector: "session" for sessionStorage (default: localStorage)
+      const storageType = selector === 'session' ? 'sessionStorage' : 'localStorage';
+      const eqIdx = value.indexOf('=');
+      if (eqIdx === -1) {
+        // Existence check
+        const exists = await page.evaluate((sType, k) => window[sType].getItem(k) !== null, storageType, value);
+        if (!exists) {
+          throw new Error(`assert_storage failed: ${storageType} key "${value}" does not exist`);
+        }
+      } else {
+        const storageKey = value.slice(0, eqIdx);
+        const expectedVal = value.slice(eqIdx + 1);
+        const actual = await page.evaluate((sType, k) => window[sType].getItem(k), storageType, storageKey);
+        if (actual === null) {
+          throw new Error(`assert_storage failed: ${storageType} key "${storageKey}" does not exist`);
+        }
+        if (actual !== expectedVal) {
+          throw new Error(`assert_storage failed: ${storageType} key "${storageKey}" is "${actual}", expected "${expectedVal}"`);
+        }
+      }
+      break;
+    }
+
+    case 'click_icon': {
+      // Click an icon element by identifier — works with MUI, FontAwesome, Heroicons, Bootstrap Icons, etc.
+      // value: icon identifier (data-testid fragment, class fragment, aria-label, or SVG text/title)
+      // selector: optional CSS scope to narrow the search
+      const iconId = value;
+      const iconScope = selector || null;
+      await page.waitForFunction(
+        (id, scope) => {
+          const root = scope ? document.querySelector(scope) : document;
+          if (!root) return false;
+          // Search by common icon attribute patterns
+          const attrSelectors = [
+            `[data-testid*="${id}"]`,
+            `[data-icon*="${id}"]`,
+            `[aria-label*="${id}"]`,
+            `svg[class*="${id}"]`,
+            `i[class*="${id}"]`,
+            `span[class*="${id}"]`,
+          ];
+          for (const sel of attrSelectors) {
+            if (root.querySelector(sel)) return true;
+          }
+          // Search all SVGs for matching text content or title
+          for (const svg of root.querySelectorAll('svg')) {
+            const title = svg.querySelector('title');
+            if (title && title.textContent.toLowerCase().includes(id.toLowerCase())) return true;
+            if (svg.getAttribute('aria-label')?.toLowerCase().includes(id.toLowerCase())) return true;
+          }
+          return false;
+        },
+        { timeout },
+        iconId, iconScope
+      );
+      const clicked = await page.evaluate(
+        (id, scope) => {
+          const root = scope ? document.querySelector(scope) : document;
+          if (!root) return false;
+          let icon = null;
+          const attrSelectors = [
+            `[data-testid*="${id}"]`,
+            `[data-icon*="${id}"]`,
+            `[aria-label*="${id}"]`,
+            `svg[class*="${id}"]`,
+            `i[class*="${id}"]`,
+            `span[class*="${id}"]`,
+          ];
+          for (const sel of attrSelectors) {
+            icon = root.querySelector(sel);
+            if (icon) break;
+          }
+          // Fallback: search SVGs by title/aria-label text
+          if (!icon) {
+            for (const svg of root.querySelectorAll('svg')) {
+              const title = svg.querySelector('title');
+              if (title && title.textContent.toLowerCase().includes(id.toLowerCase())) { icon = svg; break; }
+              if (svg.getAttribute('aria-label')?.toLowerCase().includes(id.toLowerCase())) { icon = svg; break; }
+            }
+          }
+          if (!icon) return false;
+          // Walk up to nearest clickable ancestor
+          const clickableSelector = 'button, a, [role="button"], [role="tab"], [role="menuitem"]';
+          const clickable = icon.closest(clickableSelector);
+          (clickable || icon).click();
+          return true;
+        },
+        iconId, iconScope
+      );
+      if (!clicked) {
+        throw new Error(`click_icon failed: no icon matching "${iconId}" found${iconScope ? ` in "${iconScope}"` : ''}`);
+      }
+      break;
+    }
+
+    case 'click_menu_item': {
+      // Click a menu item by text content.
+      // text: menu item text to match (case-sensitive, substring)
+      // selector: optional CSS scope
+      const menuSelector = [
+        '[role="menuitem"]',
+        '[role="menuitemradio"]',
+        '[role="menuitemcheckbox"]',
+        '.dropdown-item',
+        '.menu-item',
+        '[class*="MenuItem"]',
+        '[role="menu"] > li',
+      ].join(', ');
+      const menuScope = selector || null;
+      await page.waitForFunction(
+        (t, sel, scope) => {
+          const root = scope ? document.querySelector(scope) : document;
+          if (!root) return false;
+          return [...root.querySelectorAll(sel)].some(el => el.textContent.includes(t));
+        },
+        { timeout },
+        text, menuSelector, menuScope
+      );
+      const clicked = await page.evaluate(
+        (t, sel, scope) => {
+          const root = scope ? document.querySelector(scope) : document;
+          if (!root) return false;
+          const match = [...root.querySelectorAll(sel)].find(el => el.textContent.includes(t));
+          if (match) { match.click(); return true; }
+          return false;
+        },
+        text, menuSelector, menuScope
+      );
+      if (!clicked) {
+        throw new Error(`click_menu_item failed: no menu item containing "${text}" found${menuScope ? ` in "${menuScope}"` : ''}`);
+      }
+      break;
+    }
+
+    case 'click_in_context': {
+      // Click a child element within a container identified by text content.
+      // text: text to find the container (required)
+      // selector: CSS selector for the child to click within that container (required)
+      if (!text || !selector) {
+        throw new Error('click_in_context requires both "text" (container text) and "selector" (child to click)');
+      }
+      const containerSelectors = [
+        'section', 'article',
+        '[class*="card"]', '[class*="Card"]',
+        '[class*="panel"]', '[class*="Panel"]',
+        '[class*="item"]', '[class*="Item"]',
+        '.MuiGrid-item', '[class*="MuiGrid2"]',
+        '[class*="row"]', '[class*="Row"]',
+        'details', 'fieldset',
+        '[role="region"]', '[role="group"]', '[role="listitem"]',
+        'li', 'tr', 'div[class]',
+      ].join(', ');
+      await page.waitForFunction(
+        (t, childSel, containerSels) => {
+          const containers = [...document.querySelectorAll(containerSels)]
+            .filter(el => el.textContent.includes(t));
+          // Sort by innerHTML length (smallest = most specific)
+          containers.sort((a, b) => a.innerHTML.length - b.innerHTML.length);
+          for (const c of containers) {
+            if (c.querySelector(childSel)) return true;
+          }
+          return false;
+        },
+        { timeout },
+        text, selector, containerSelectors
+      );
+      const clicked = await page.evaluate(
+        (t, childSel, containerSels) => {
+          const containers = [...document.querySelectorAll(containerSels)]
+            .filter(el => el.textContent.includes(t));
+          containers.sort((a, b) => a.innerHTML.length - b.innerHTML.length);
+          for (const c of containers) {
+            const child = c.querySelector(childSel);
+            if (child) { child.click(); return true; }
+          }
+          return false;
+        },
+        text, selector, containerSelectors
+      );
+      if (!clicked) {
+        throw new Error(`click_in_context failed: no "${selector}" found in container with text "${text}"`);
+      }
+      break;
+    }
+
+    case 'gql': {
+      // Execute a GraphQL query/mutation via browser fetch.
+      // Reads auth token from localStorage and sends it as a configurable header.
+      // Installs window.__e2eGql(query, vars) helper for use in subsequent evaluate actions.
+      //
+      // value: GraphQL query/mutation string (required)
+      // text: variables as JSON string (optional)
+      // selector: JS expression assertion — receives response as `r` (optional)
+      const gqlEndpoint = config.gqlEndpoint || '/api/graphql';
+      const gqlAuthHeader = config.gqlAuthHeader || 'Authorization';
+      const gqlAuthKey = config.gqlAuthKey || 'accessToken';
+      const gqlAuthPrefix = config.gqlAuthPrefix ?? 'Bearer ';
+      const gqlVars = text || undefined;
+
+      const gqlResult = await page.evaluate(async (query, varsJson, endpoint, authHdr, authKey, authPfx) => {
+        // Install reusable helper on first call
+        if (!window.__e2eGql) {
+          window.__e2eGqlConfig = { endpoint, authHeader: authHdr, authKey, authPrefix: authPfx };
+          window.__e2eGql = async (q, v) => {
+            const cfg = window.__e2eGqlConfig;
+            const token = localStorage.getItem(cfg.authKey);
+            const headers = { 'Content-Type': 'application/json' };
+            if (token) headers[cfg.authHeader] = cfg.authPrefix + token;
+            const resp = await fetch(location.origin + cfg.endpoint, {
+              method: 'POST', headers,
+              body: JSON.stringify({ query: q, variables: v }),
+            });
+            return resp.json();
+          };
+        }
+
+        const vars = varsJson ? JSON.parse(varsJson) : undefined;
+        const response = await window.__e2eGql(query, vars);
+        window.__e2eLastGql = response;
+        return response;
+      }, value, gqlVars, gqlEndpoint, gqlAuthHeader, gqlAuthKey, gqlAuthPrefix);
+
+      // Check for GraphQL errors
+      if (gqlResult.errors?.length) {
+        throw new Error(`gql failed: ${gqlResult.errors.map(e => e.message).join('; ')}`);
+      }
+
+      // Optional assertion via selector field (JS expression, `r` = full response)
+      // Intentional: runs JS in browser page context from team-authored JSON test files,
+      // same security model as the 'evaluate' action type.
+      if (selector) {
+        const assertResult = await page.evaluate((code, r) => {
+          const fn = new Function('r', `return (${code})`); // eslint-disable-line no-new-func
+          return fn(r);
+        }, selector, gqlResult);
+
+        if (typeof assertResult === 'string' && /^(FAIL|ERROR|FAILED)[\s:]/i.test(assertResult)) {
+          throw new Error(`gql assertion: ${assertResult}`);
+        }
+        if (assertResult === false) {
+          throw new Error(`gql assertion returned false`);
+        }
+      }
+
+      return { value: gqlResult.data };
+    }
+
     case 'evaluate': {
       // Intentional: runs JS in browser page context (from test JSON files)
       const jsSnippet = value.length > 120 ? value.slice(0, 120) + '...' : value;
@@ -430,8 +745,15 @@ export async function executeAction(page, action, config) {
       return evalResult !== undefined && evalResult !== null ? { value: evalResult } : null;
     }
 
+    case 'wait_network_idle': {
+      const idleTime = value ? parseInt(value) : 500;
+      const maxTimeout = action.timeout ? parseInt(action.timeout) : 30000;
+      await page.waitForNetworkIdle({ idleTime, timeout: maxTimeout });
+      break;
+    }
+
     default:
-      log('⚠️', `Unknown action: ${type}`);
+      throw new Error(`Unknown action type: "${type}"`);
   }
 
   return null;

package/src/ai-generate.js

@@ -52,7 +52,18 @@ The test format is:
       { "type": "click_regex", "text": "submit order", "selector": "button", "value": "last" },
       { "type": "click_option", "text": "Option Label" },
       { "type": "focus_autocomplete", "text": "Search by label" },
-      { "type": "click_chip", "text": "Tag Name" }
+      { "type": "click_chip", "text": "Tag Name" },
+      { "type": "set_storage", "value": "token=abc123" },
+      { "type": "set_storage", "value": "theme=dark", "selector": "session" },
+      { "type": "assert_storage", "value": "token" },
+      { "type": "assert_storage", "value": "theme=dark", "selector": "session" },
+      { "type": "click_icon", "value": "edit" },
+      { "type": "click_icon", "value": "delete", "selector": ".user-card" },
+      { "type": "click_menu_item", "text": "Delete" },
+      { "type": "click_menu_item", "text": "Export", "selector": ".actions-menu" },
+      { "type": "click_in_context", "text": "John Doe", "selector": "button.edit" },
+      { "type": "gql", "value": "{ users { id name } }" },
+      { "type": "gql", "value": "query($id: ID) { user(id: $id) { name } }", "text": "{\"id\": \"123\"}" }
     ]
   }
 ]
@@ -64,6 +75,18 @@ Framework-aware action reference (prefer these over evaluate for React/MUI apps)
 - focus_autocomplete: focus an autocomplete input by its label text (supports MUI .MuiAutocomplete-root and [role="combobox"])
 - click_chip: click a chip/tag element by text (searches [class*="Chip"], [data-chip])
 
+Storage actions:
+- set_storage: set a localStorage key. "value": "key=val". Use "selector": "session" for sessionStorage
+- assert_storage: assert a storage key exists ("value": "key") or has a value ("value": "key=expected"). Use "selector": "session" for sessionStorage
+
+GraphQL action:
+- gql: execute a GraphQL query/mutation via browser fetch. Auth token is read from localStorage automatically (configurable via gqlAuthHeader, gqlAuthKey, gqlAuthPrefix). "value" is the query string. "text" is variables as JSON string. "selector" is an optional JS assertion expression (receives response as "r"). Throws on GraphQL errors automatically. Also installs window.__e2eGql(query, vars) for use in subsequent evaluate actions
+
+Smart interaction actions:
+- click_icon: click an icon by identifier (data-testid fragment, class fragment, aria-label, SVG title). Walks up to nearest clickable parent (button, a, etc.). Optional "selector" scopes the search
+- click_menu_item: click a menu item by text. Searches [role="menuitem"], .dropdown-item, .menu-item, [class*="MenuItem"]. Optional "selector" scopes the search
+- click_in_context: click a child element within a container identified by text. "text" finds the container, "selector" is the child to click. Picks the smallest matching container
+
 Assertion action reference:
 - assert_text: checks if text appears anywhere in the page body
 - assert_element_text: checks textContent of a specific element (use "value": "exact" for strict match)
@@ -80,8 +103,15 @@ Reusable modules:
 - Tests can reference shared action sequences: { "$use": "module-name", "params": { "key": "value" } }
 - Use modules for repeated flows like login, navigation, or setup
 
+Hooks and DRY patterns:
+- When multiple tests share the same setup (e.g. authentication), use beforeEach instead of repeating it per test
+- Object format with hooks: { "beforeEach": [...], "tests": [{ "name": "...", "actions": [...] }] }
+- Array format (no hooks): [{ "name": "...", "actions": [...] }]
+- If 3+ tests repeat the same action sequence (e.g. goto + wait + screenshot), extract it into a module
+- NEVER repeat the same $use call with identical params across all tests — move it to beforeEach
+
 Rules:
-- Output a JSON array of test objects
+- Output valid JSON: either a plain array of test objects, or an object with "beforeEach"/"tests" keys when hooks are needed
 - NEVER use evaluate with inline JS for assertions that can be done with native action types:
   * Use assert_element_text instead of evaluate to check element textContent
   * Use assert_attribute instead of evaluate to check HTML attributes
@@ -94,6 +124,12 @@ Rules:
   * Use click_option instead of evaluate with querySelectorAll('[role="option"]') patterns
   * Use focus_autocomplete instead of evaluate with MuiAutocomplete-root label search patterns
   * Use click_chip instead of evaluate with querySelectorAll('[class*="Chip"]') patterns
+  * Use set_storage instead of evaluate with localStorage.setItem or sessionStorage.setItem
+  * Use assert_storage instead of evaluate with localStorage.getItem or sessionStorage.getItem checks
+  * Use click_icon instead of evaluate with querySelector('svg[data-testid]').closest('button').click() patterns
+  * Use click_menu_item instead of evaluate with querySelectorAll('[role="menuitem"]') patterns
+  * Use click_in_context instead of evaluate that finds a container by text then clicks a child element
+  * Use gql instead of evaluate with fetch + JSON.stringify + GraphQL queries/mutations
   * Reserve evaluate ONLY for complex logic that cannot be expressed with existing action types
 - "click" with "text" (no selector) finds buttons/links by visible text
 - "goto" values starting with "/" are relative to the app's base URL
@@ -117,9 +153,11 @@ CRITICAL — UI-first testing rules:
 
 const API_RULES = `
 API testing rules:
-- Tests verify backend API behavior directly via evaluate actions
+- Tests verify backend API behavior directly via gql actions (preferred) or evaluate actions
 - Each test should: set up context → call API → assert response shape and values
-- Use evaluate for GraphQL mutations, queries, and REST calls
+- PREFER the gql action for GraphQL queries/mutations — it handles auth and error checking automatically
+- Use gql with "selector" field for inline assertions on the response (JS expression where "r" is the response)
+- Use evaluate with window.__e2eGql() for complex multi-step GraphQL operations (the helper is installed by any gql action)
 - Name tests clearly describing the API operation (e.g. "createUser-returns-new-user")
 - Include error case tests (invalid input, missing fields, auth failures)
 - No need for goto/click/type — this is not UI testing
@@ -247,7 +285,7 @@ Test Category: ${testType}
 ${categoryRules}
 Base URL: ${config.baseUrl}
 
-Output a JSON array of test objects. Nothing else.`;
+Output ONLY valid JSON. Either a plain array of test objects, or an object with "beforeEach" and "tests" keys if hooks are needed. Nothing else.`;
 
   const response = await fetch('https://api.anthropic.com/v1/messages', {
     method: 'POST',
@@ -288,9 +326,21 @@ Output a JSON array of test objects. Nothing else.`;
     throw new Error(`Failed to parse generated tests as JSON: ${err.message}\n\nRaw output:\n${text}`);
   }
 
-  if (!Array.isArray(tests)) {
-    throw new Error('Generated tests must be a JSON array');
+  // Accept both array format and object format with hooks
+  let hooks;
+  if (Array.isArray(tests)) {
+    // Plain array: [{ name, actions }]
+  } else if (tests && Array.isArray(tests.tests)) {
+    // Object with hooks: { beforeEach: [...], tests: [...] }
+    hooks = {};
+    for (const key of ['beforeAll', 'afterAll', 'beforeEach', 'afterEach']) {
+      if (Array.isArray(tests[key])) hooks[key] = tests[key];
+    }
+    if (Object.keys(hooks).length === 0) hooks = undefined;
+    tests = tests.tests;
+  } else {
+    throw new Error('Generated tests must be a JSON array or an object with a "tests" array');
   }
 
-  return { tests, suiteName };
+  return { tests, hooks, suiteName };
 }