@matware/e2e-runner 1.2.1 → 1.3.1

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,25 @@
  */
 
 import path from 'path';
-import { log } from './logger.js';
+import fs from 'fs';
+import { assertVisualMatch } from './visual-diff.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',
+  'open_tab', 'switch_tab', 'close_tab', 'assert_tab_count', 'wait_for_tab',
+  'assert_visual',
+]);
 
 function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
@@ -102,6 +120,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 +268,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 +461,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 +749,162 @@ 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;
+    }
+
+    // ── Visual regression ───────────────────────────────────────────────────
+
+    case 'assert_visual': {
+      // Compares a live screenshot against a golden reference image.
+      //
+      // value: golden image filename (relative to screenshotsDir or goldenDir) — required
+      // selector: optional CSS selector — screenshot only that element instead of full page
+      // text: optional max diff percentage as string, e.g. "0.02" (default: config.verificationThreshold or 0.02)
+      //
+      // Additional fields via action object:
+      //   fullPage: boolean (default: true)
+      //   maskRegions: [{ x, y, width, height }] — regions to ignore (timestamps, avatars, etc.)
+      //   threshold: number — pixel color sensitivity 0-1 (default: 0.1)
+      //
+      // Returns: { diffPercentage, differentPixels, totalPixels, diffImagePath, baselinePath, currentPath }
+
+      if (!value) throw new Error('assert_visual requires "value" (golden image filename)');
+
+      // Resolve golden image path
+      const goldenDir = config.goldenDir || path.join(config.screenshotsDir, 'golden');
+      const goldenPath = path.isAbsolute(value) ? value : path.join(goldenDir, value);
+
+      if (!fs.existsSync(goldenPath)) {
+        // First run: save current screenshot as the golden reference
+        if (!fs.existsSync(goldenDir)) fs.mkdirSync(goldenDir, { recursive: true });
+        const screenshotOpts = { path: goldenPath, fullPage: action.fullPage !== false };
+        if (selector) {
+          const el = await page.$(selector);
+          if (!el) throw new Error(`assert_visual: selector "${selector}" not found`);
+          await el.screenshot(screenshotOpts);
+        } else {
+          await page.screenshot(screenshotOpts);
+        }
+        return {
+          goldenCreated: true,
+          goldenPath,
+          message: `Golden image saved: ${path.basename(goldenPath)}. Re-run to compare.`,
+        };
+      }
+
+      // Capture current screenshot
+      const safeName = path.basename(value, path.extname(value));
+      const currentPath = path.join(screenshotsDir, `current-${safeName}-${Date.now()}.png`);
+      const screenshotOpts = { path: currentPath, fullPage: action.fullPage !== false };
+      if (selector) {
+        const el = await page.$(selector);
+        if (!el) throw new Error(`assert_visual: selector "${selector}" not found`);
+        await el.screenshot(screenshotOpts);
+      } else {
+        await page.screenshot(screenshotOpts);
+      }
+
+      // Compare
+      const maxDiff = text ? parseFloat(text) : (config.verificationThreshold || 0.02);
+      const diffPath = path.join(screenshotsDir, `diff-${safeName}-${Date.now()}.png`);
+      const compareResult = assertVisualMatch(goldenPath, currentPath, maxDiff, {
+        threshold: action.threshold || 0.1,
+        maskRegions: action.maskRegions || [],
+        diffOutputPath: diffPath,
+        includeAntiAlias: action.includeAntiAlias || false,
+      });
+
+      if (!compareResult.passed) {
+        const pct = (compareResult.diffPercentage * 100).toFixed(2);
+        const maxPct = (maxDiff * 100).toFixed(2);
+        throw new Error(
+          `assert_visual failed: ${pct}% pixels differ (threshold: ${maxPct}%). ` +
+          `${compareResult.differentPixels}/${compareResult.totalPixels} pixels changed. ` +
+          `Diff: ${path.basename(diffPath)}`
+        );
+      }
+
+      return {
+        diffPercentage: compareResult.diffPercentage,
+        differentPixels: compareResult.differentPixels,
+        totalPixels: compareResult.totalPixels,
+        diffImagePath: compareResult.diffImagePath,
+        baselinePath: goldenPath,
+        currentPath,
+        screenshot: diffPath,
+      };
+    }
+
+    // ── Multi-tab actions ─────────────────────────────────────────────────────
+    // These actions are intercepted by the runner (runTest) which manages the
+    // tab registry and swaps the active page. The actual tab lifecycle happens
+    // in runner.js — these cases handle the in-page parts only.
+
+    case 'open_tab': {
+      // Opens a new tab and navigates to the given URL.
+      // value: URL (absolute or relative to baseUrl) — required
+      // text: optional label for the tab (used by switch_tab)
+      // The runner intercepts this to create the page and register it.
+      // If we reach here, it means the runner already created the page and
+      // we just need to navigate.
+      const tabUrl = value.startsWith('http') ? value : `${baseUrl}${value}`;
+      await page.goto(tabUrl, { waitUntil: 'domcontentloaded', timeout: 60000 });
+      break;
+    }
+
+    case 'switch_tab': {
+      // Switches to another open tab. The runner handles the actual page swap.
+      // This case is a no-op — the runner already switched the page reference.
+      break;
+    }
+
+    case 'close_tab': {
+      // Closes the current tab. The runner handles page cleanup and switching.
+      // This case is a no-op — the runner closes the page and swaps back.
+      break;
+    }
+
+    case 'assert_tab_count': {
+      // Asserts the number of open tabs.
+      // value: expected count (number or operator expression like ">=2")
+      // The runner injects __tabCount into the action result before we get here.
+      // If we reach here directly, we use browser context pages.
+      const tabCount = action.__tabCount;
+      if (tabCount === undefined) {
+        throw new Error('assert_tab_count: tab count not available (action must be run via runner)');
+      }
+      const opMatch = value.match(/^(>=|<=|>|<)\s*(\d+)$/);
+      if (opMatch) {
+        const [, op, numStr] = opMatch;
+        const expected = parseInt(numStr);
+        const passed = op === '>' ? tabCount > expected
+          : op === '>=' ? tabCount >= expected
+          : op === '<' ? tabCount < expected
+          : tabCount <= expected;
+        if (!passed) {
+          throw new Error(`assert_tab_count failed: ${tabCount} tabs open, expected ${op}${expected}`);
+        }
+      } else {
+        const expected = parseInt(value);
+        if (tabCount !== expected) {
+          throw new Error(`assert_tab_count failed: ${tabCount} tabs open, expected ${expected}`);
+        }
+      }
+      break;
+    }
+
+    case 'wait_for_tab': {
+      // Waits for a new tab/popup to appear. The runner handles this.
+      // This case is a no-op — the runner already waited and registered the new tab.
+      break;
+    }
+
     default:
-      log('⚠️', `Unknown action: ${type}`);
+      throw new Error(`Unknown action type: "${type}"`);
   }
 
   return null;