@matware/e2e-runner 1.1.1 → 1.2.1

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

@@ -0,0 +1,182 @@
+# Troubleshooting Guide
+
+## Pool Connection Issues
+
+### "Pool not reachable" / Connection refused
+
+**Cause**: Chrome pool (browserless/chrome Docker container) is not running.
+
+**Fix**:
+```bash
+npx e2e-runner pool start
+npx e2e-runner pool status   # verify it's running
+```
+
+Pool management is CLI-only — `pool start` and `pool stop` are not available via MCP.
+
+### "Pool at capacity" / Tests queuing
+
+**Cause**: All Chrome sessions are occupied.
+
+**Fix**: Increase capacity or reduce concurrency:
+```bash
+npx e2e-runner pool stop
+npx e2e-runner pool start --max-sessions 10
+```
+Or reduce test concurrency: `--concurrency 2`
+
+The runner checks `/pressure` before each connection and waits up to 60s for a free slot.
+
+### Docker not running
+
+**Cause**: Docker daemon is not started.
+
+**Fix**: Start Docker Desktop or `sudo systemctl start docker`, then `npx e2e-runner pool start`.
+
+## React / SPA Issues
+
+### React inputs not updating state
+
+**Symptom**: `type` action enters text but React state doesn't change (form validation fails, submit disabled).
+
+**Fix**: Use `type_react` instead of `type` for React controlled inputs:
+```json
+{ "type": "type_react", "selector": "#email", "value": "user@test.com" }
+```
+
+`type_react` uses the native value setter and dispatches `input` + `change` events that React's synthetic event system recognizes.
+
+### SPA navigation not completing
+
+**Symptom**: `goto` hangs or times out on client-side route changes.
+
+**Fix**: Use `navigate` instead of `goto` for SPA route changes:
+```json
+{ "type": "navigate", "value": "/new-page" }
+```
+
+`navigate` uses a 5s race timeout and won't block if `load` doesn't fire (common in SPAs).
+
+### MUI autocomplete not opening
+
+**Symptom**: Clicking or typing in an MUI Autocomplete doesn't open the dropdown.
+
+**Fix**: Use `focus_autocomplete` to properly focus by label text:
+```json
+{ "type": "focus_autocomplete", "text": "Search by name" },
+{ "type": "type_react", "selector": "#autocomplete-input", "value": "search term" },
+{ "type": "click_option", "text": "Desired option" }
+```
+
+## Flaky Tests
+
+### Intermittent failures on dynamic content
+
+**Symptom**: Tests pass sometimes, fail others. Usually timing-related.
+
+**Fixes**:
+1. Add explicit `wait` before assertions:
+   ```json
+   { "type": "wait", "selector": ".data-loaded" },
+   { "type": "assert_text", "text": "Expected content" }
+   ```
+
+2. Use action-level retries for known flaky selectors:
+   ```json
+   { "type": "click", "selector": "#dynamic-btn", "retries": 3 }
+   ```
+
+3. Use test-level retries:
+   ```json
+   { "name": "flaky-test", "retries": 2, "actions": [...] }
+   ```
+
+4. Check the learning system for patterns:
+   ```
+   e2e_learnings("flaky") → identify consistently flaky tests
+   e2e_learnings("selectors") → find unstable selectors
+   ```
+
+### Tests interfering with each other
+
+**Symptom**: Tests pass individually but fail when run together.
+
+**Fix**: Mark tests that share mutable state as `serial`:
+```json
+{ "name": "create-item", "serial": true, "actions": [...] },
+{ "name": "verify-item", "serial": true, "actions": [...] }
+```
+
+## Timeout Issues
+
+### Test timeout (default 60s)
+
+**Fix**: Increase per-test or globally:
+```json
+{ "name": "slow-test", "timeout": 120000, "actions": [...] }
+```
+Or globally: `--test-timeout 120000`
+
+### Action timeout (default 10s)
+
+Each action's `waitForSelector` uses the default timeout. Override per-action:
+```json
+{ "type": "wait", "selector": ".slow-element", "timeout": 30000 }
+```
+Or globally: `--timeout 30000`
+
+## Network Errors
+
+### Tests passing but network requests failing
+
+**Symptom**: Tests pass but `networkSummary` shows failed requests.
+
+**Fix**: Enable strict mode to fail tests with network errors:
+```
+e2e_run({ all: true, failOnNetworkError: true })
+```
+
+Or use `assert_no_network_errors` at specific points:
+```json
+{ "type": "goto", "value": "/api-heavy-page" },
+{ "type": "wait", "selector": ".loaded" },
+{ "type": "assert_no_network_errors" }
+```
+
+### Investigating specific failures
+
+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
+```
+
+## Common Mistakes
+
+### Using `beforeAll` for browser state
+
+`beforeAll` runs on a separate page that closes before tests. Use `beforeEach` for state setup.
+
+### Using `evaluate` for simple assertions
+
+Prefer granular assertion actions over `evaluate` with inline JS:
+```json
+// Bad: verbose, error-prone
+{ "type": "evaluate", "value": "if (!document.querySelector('h1').textContent.includes('Dashboard')) throw 'not found'" }
+
+// Good: clear, auto-waits
+{ "type": "assert_element_text", "selector": "h1", "text": "Dashboard" }
+```
+
+### Forgetting `cwd` in MCP calls
+
+All MCP tools need `cwd` to resolve config files and test directories. Always pass the project root.
+
+### Path-only `assert_url`
+
+When checking paths, use path-only format (starts with `/`):
+```json
+{ "type": "assert_url", "value": "/dashboard" }
+```
+This compares against the pathname only, ignoring the `host.docker.internal` origin.

package/src/actions.js

@@ -31,13 +31,14 @@ export async function executeAction(page, action, config) {
         await page.waitForSelector(selector, { timeout });
         await page.click(selector);
       } else if (text) {
+        const clickTextSelector = 'button, a, [role="button"], [role="tab"], [role="menuitem"], [role="option"], [role="listitem"], div[class*="cursor"], span, li, td, th, label, p, h1, h2, h3, h4, h5, h6, dd, dt';
         await page.waitForFunction(
-          (t) => [...document.querySelectorAll('button, a, [role="button"], [role="tab"], [role="menuitem"], div[class*="cursor"], span')]
+          (t, sel) => [...document.querySelectorAll(sel)]
             .find(el => el.textContent.includes(t)),
           { timeout },
-          text
+          text, clickTextSelector
         );
-        await page.$$eval('button, a, [role="button"], [role="tab"], [role="menuitem"], div[class*="cursor"], span', (els, t) => {
+        await page.$$eval(clickTextSelector, (els, t) => {
           const el = els.find(e => e.textContent.includes(t));
           if (el) el.click();
         }, text);
@@ -54,13 +55,21 @@ export async function executeAction(page, action, config) {
 
     case 'wait':
       if (selector) {
-        await page.waitForSelector(selector, { timeout });
+        try {
+          await page.waitForSelector(selector, { timeout });
+        } catch (e) {
+          throw new Error(`wait failed: selector "${selector}" not found after ${timeout}ms`);
+        }
       } else if (text) {
-        await page.waitForFunction(
-          (t) => document.body.innerText.includes(t),
-          { timeout },
-          text
-        );
+        try {
+          await page.waitForFunction(
+            (t) => document.body.innerText.includes(t),
+            { timeout },
+            text
+          );
+        } catch (e) {
+          throw new Error(`wait failed: text "${text}" not found after ${timeout}ms`);
+        }
       } else if (value) {
         await sleep(parseInt(value));
       }
@@ -73,6 +82,13 @@ export async function executeAction(page, action, config) {
       }
       // Sanitize: use only the basename to prevent path traversal
       filename = path.basename(filename);
+      // Inject timestamp before extension to make filenames unique per run
+      // (prevents overwriting previous runs' screenshots)
+      if (value) {
+        const ext = path.extname(filename);
+        const base = filename.slice(0, -ext.length);
+        filename = `${base}-${Date.now()}${ext}`;
+      }
       const filepath = path.join(screenshotsDir, filename);
       await page.screenshot({ path: filepath, fullPage: action.fullPage || false });
       return { screenshot: filepath };
@@ -88,8 +104,26 @@ export async function executeAction(page, action, config) {
 
     case 'assert_url': {
       const currentUrl = page.url();
-      if (!currentUrl.includes(value)) {
-        throw new Error(`assert_url failed: expected "${value}", got "${currentUrl}"`);
+      let match = false;
+      if (value.startsWith('/')) {
+        // Path-only comparison: extract pathname (+ query if value has ?)
+        try {
+          const parsed = new URL(currentUrl);
+          const compareTo = value.includes('?') ? parsed.pathname + parsed.search : parsed.pathname;
+          match = compareTo === value || compareTo.startsWith(value);
+        } catch {
+          match = currentUrl.includes(value);
+        }
+        if (!match) {
+          const pathname = (() => { try { return new URL(currentUrl).pathname; } catch { return currentUrl; } })();
+          throw new Error(`assert_url failed: expected path "${value}", got "${pathname}" (full: ${currentUrl})`);
+        }
+      } else {
+        // Full URL comparison (backwards compatible)
+        match = currentUrl.includes(value);
+        if (!match) {
+          throw new Error(`assert_url failed: expected "${value}", got "${currentUrl}"`);
+        }
       }
       break;
     }
@@ -111,13 +145,107 @@ export async function executeAction(page, action, config) {
 
     case 'assert_count': {
       const count = await page.$$eval(selector, els => els.length);
-      const expected = parseInt(value);
-      if (count !== expected) {
-        throw new Error(`assert_count failed: "${selector}" has ${count} elements, expected ${expected}`);
+      const opMatch = value.match(/^(>=|<=|>|<)\s*(\d+)$/);
+      if (opMatch) {
+        const [, op, numStr] = opMatch;
+        const expected = parseInt(numStr);
+        const passed = op === '>' ? count > expected
+          : op === '>=' ? count >= expected
+          : op === '<' ? count < expected
+          : count <= expected;
+        if (!passed) {
+          throw new Error(`assert_count failed: "${selector}" has ${count} elements, expected ${op}${expected}`);
+        }
+      } else {
+        const expected = parseInt(value);
+        if (count !== expected) {
+          throw new Error(`assert_count failed: "${selector}" has ${count} elements, expected ${expected}`);
+        }
+      }
+      break;
+    }
+
+    case 'assert_element_text': {
+      await page.waitForSelector(selector, { timeout });
+      const elText = await page.$eval(selector, el => el.textContent);
+      if (value === 'exact') {
+        if (elText.trim() !== text) {
+          throw new Error(`assert_element_text failed: "${selector}" text is "${elText.trim()}", expected exact "${text}"`);
+        }
+      } else {
+        if (!elText.includes(text)) {
+          throw new Error(`assert_element_text failed: "${selector}" text "${elText.trim()}" does not contain "${text}"`);
+        }
       }
       break;
     }
 
+    case 'assert_attribute': {
+      await page.waitForSelector(selector, { timeout });
+      const eqIndex = value.indexOf('=');
+      if (eqIndex === -1) {
+        const hasAttr = await page.$eval(selector, (el, attr) => el.hasAttribute(attr), value);
+        if (!hasAttr) {
+          throw new Error(`assert_attribute failed: "${selector}" does not have attribute "${value}"`);
+        }
+      } else {
+        const attrName = value.slice(0, eqIndex);
+        const expectedVal = value.slice(eqIndex + 1);
+        const actual = await page.$eval(selector, (el, attr) => el.getAttribute(attr), attrName);
+        if (actual !== expectedVal) {
+          throw new Error(`assert_attribute failed: "${selector}" attribute "${attrName}" is "${actual}", expected "${expectedVal}"`);
+        }
+      }
+      break;
+    }
+
+    case 'assert_class': {
+      await page.waitForSelector(selector, { timeout });
+      const hasClass = await page.$eval(selector, (el, cls) => el.classList.contains(cls), value);
+      if (!hasClass) {
+        throw new Error(`assert_class failed: "${selector}" does not have class "${value}"`);
+      }
+      break;
+    }
+
+    case 'assert_not_visible': {
+      const notVisEl = await page.$(selector);
+      if (notVisEl) {
+        const isVisible = await page.$eval(selector, (e) => {
+          const style = window.getComputedStyle(e);
+          return style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0';
+        });
+        if (isVisible) {
+          throw new Error(`assert_not_visible failed: "${selector}" is visible`);
+        }
+      }
+      break;
+    }
+
+    case 'assert_input_value': {
+      await page.waitForSelector(selector, { timeout });
+      const inputVal = await page.$eval(selector, el => el.value);
+      if (!inputVal.includes(value)) {
+        throw new Error(`assert_input_value failed: "${selector}" value is "${inputVal}", expected to contain "${value}"`);
+      }
+      break;
+    }
+
+    case 'assert_matches': {
+      await page.waitForSelector(selector, { timeout });
+      const matchText = await page.$eval(selector, el => el.textContent);
+      if (!new RegExp(value).test(matchText)) {
+        throw new Error(`assert_matches failed: "${selector}" text "${matchText.trim()}" does not match pattern /${value}/`);
+      }
+      break;
+    }
+
+    case 'get_text': {
+      await page.waitForSelector(selector, { timeout });
+      const getText = await page.$eval(selector, el => el.textContent.trim());
+      return { value: getText };
+    }
+
     case 'select':
       await page.waitForSelector(selector, { timeout });
       await page.select(selector, value);
@@ -162,15 +290,142 @@ export async function executeAction(page, action, config) {
       break;
     }
 
+    case 'clear_cookies': {
+      const client = await page.createCDPSession();
+      await client.send('Network.clearBrowserCookies');
+      await client.send('Storage.clearDataForOrigin', {
+        origin: value || baseUrl || page.url(),
+        storageTypes: 'cookies,local_storage,session_storage',
+      });
+      await client.detach();
+      break;
+    }
+
+    case 'type_react': {
+      // Types into React controlled inputs using the native value setter.
+      // This bypasses React's synthetic event system which ignores programmatic .value changes.
+      await page.waitForSelector(selector, { timeout });
+      await page.evaluate((sel, val) => {
+        const input = document.querySelector(sel);
+        if (!input) throw new Error(`type_react: element "${sel}" not found`);
+        const proto = input instanceof HTMLTextAreaElement
+          ? window.HTMLTextAreaElement.prototype
+          : window.HTMLInputElement.prototype;
+        const descriptor = Object.getOwnPropertyDescriptor(proto, 'value');
+        if (!descriptor || !descriptor.set) {
+          throw new Error(`type_react: element "${sel}" has no writable value property`);
+        }
+        descriptor.set.call(input, val);
+        input.dispatchEvent(new Event('input', { bubbles: true }));
+        input.dispatchEvent(new Event('change', { bubbles: true }));
+        input.focus();
+      }, selector, value);
+      break;
+    }
+
+    case 'click_regex': {
+      // Click an element whose textContent matches a regex pattern.
+      // text = regex pattern (always case-insensitive)
+      // selector = optional CSS scope (defaults to common clickable elements)
+      // value = "last" to click the last match (default: first)
+      const matchSelector = selector || 'button, a, [role="button"], [role="tab"], [role="menuitem"], [role="option"], [role="listitem"], div[class*="cursor"], span, li, td, th, label, p, h1, h2, h3, h4, h5, h6, dd, dt';
+      const matchLast = value === 'last';
+      await page.waitForFunction(
+        (regex, sel) => [...document.querySelectorAll(sel)].some(el => new RegExp(regex, 'i').test(el.textContent)),
+        { timeout },
+        text, matchSelector
+      );
+      const clicked = await page.$$eval(matchSelector, (els, regex, last) => {
+        const matches = els.filter(el => new RegExp(regex, 'i').test(el.textContent));
+        if (matches.length === 0) return false;
+        const target = last ? matches[matches.length - 1] : matches[0];
+        target.click();
+        return true;
+      }, text, matchLast);
+      if (!clicked) {
+        throw new Error(`click_regex failed: no element matching /${text}/i found`);
+      }
+      break;
+    }
+
+    case 'click_option': {
+      // Click a [role="option"] element by text content — common in autocomplete dropdowns.
+      await page.waitForFunction(
+        (t) => [...document.querySelectorAll('[role="option"]')].some(el => el.textContent.includes(t)),
+        { timeout },
+        text
+      );
+      const optionClicked = await page.$$eval('[role="option"]', (els, t) => {
+        const match = els.find(el => el.textContent.includes(t));
+        if (match) { match.click(); return true; }
+        return false;
+      }, text);
+      if (!optionClicked) {
+        throw new Error(`click_option failed: no [role="option"] containing "${text}" found`);
+      }
+      break;
+    }
+
+    case 'focus_autocomplete': {
+      // Focus an autocomplete/combobox input by its label text.
+      // Supports MUI Autocomplete (.MuiAutocomplete-root) and generic [role="combobox"].
+      const focused = await page.evaluate((labelText) => {
+        const containers = [
+          ...document.querySelectorAll('.MuiAutocomplete-root'),
+          ...document.querySelectorAll('[role="combobox"]'),
+        ];
+        const match = containers.find(c => {
+          const label = c.querySelector('label');
+          return label && label.textContent.includes(labelText);
+        });
+        if (!match) return null;
+        const input = match.querySelector('input');
+        if (!input) return null;
+        input.focus();
+        input.click();
+        return input.id || 'focused';
+      }, text);
+      if (!focused) {
+        throw new Error(`focus_autocomplete failed: no autocomplete with label "${text}" found`);
+      }
+      break;
+    }
+
+    case 'click_chip': {
+      // Click a chip/tag element by text content.
+      // Searches MUI Chip classes and common chip patterns.
+      const chipClicked = await page.evaluate((chipText) => {
+        const chips = Array.from(document.querySelectorAll(
+          '[class*="Chip"], [class*="chip"], [data-chip], [role="option"][aria-selected]'
+        ));
+        const match = chips.find(c => c.textContent.includes(chipText));
+        if (!match) return false;
+        match.click();
+        return true;
+      }, text);
+      if (!chipClicked) {
+        throw new Error(`click_chip failed: no chip containing "${text}" found`);
+      }
+      break;
+    }
+
     case 'evaluate': {
       // Intentional: runs JS in browser page context (from test JSON files)
-      const evalResult = await page.evaluate(value);
-      // Check return value for failure signals
+      const jsSnippet = value.length > 120 ? value.slice(0, 120) + '...' : value;
+      let evalResult;
+      try {
+        evalResult = await page.evaluate(value);
+      } catch (evalErr) {
+        const pageUrl = page.url();
+        throw new Error(`evaluate threw on ${pageUrl}: ${evalErr.message}\n  JS: ${jsSnippet}`);
+      }
       if (typeof evalResult === 'string' && /^(FAIL|ERROR|FAILED)[\s:]/i.test(evalResult)) {
-        throw new Error(`evaluate failed: ${evalResult}`);
+        const pageUrl = page.url();
+        throw new Error(`evaluate failed on ${pageUrl}: ${evalResult}\n  JS: ${jsSnippet}`);
       }
       if (evalResult === false) {
-        throw new Error('evaluate returned false');
+        const pageUrl = page.url();
+        throw new Error(`evaluate returned false on ${pageUrl}\n  JS: ${jsSnippet}`);
       }
       return evalResult !== undefined && evalResult !== null ? { value: evalResult } : null;
     }