onbuzz 4.9.13 → 4.10.0

package/src/tools/__tests__/webTool.e2e.test.js

@@ -1,603 +1,609 @@
-/**
- * WebTool E2E Tests
- *
- * These tests launch a REAL headless browser and test against live pages.
- * They validate error detection, HTTP status handling, selector feedback,
- * and the full execute → result pipeline.
- *
- * NOTE: These tests require network access and a working Puppeteer install.
- * They are slower (~60s total) and are tagged for separate runs.
- * Skipped on WSL/headless Linux (no display server for Chromium).
- *
- * Run with: npm run test:e2e
- */
-
-import { describe, test, expect, beforeAll, afterAll, jest } from '@jest/globals';
-
-// Real-network tests against example.com / iana.org are inherently
-// flaky on TCP / DNS / target-server hiccups. The contract under test
-// is "the WebTool chain machinery works", not "example.com is always
-// up", so we tolerate up to 2 retries before declaring failure.
-// If a test fails 3 times in a row, that's a real signal worth
-// investigating; transient flakes get absorbed silently.
-jest.retryTimes(2, { logErrorsBeforeRetry: true });
-import os from 'os';
-import fs from 'fs';
-
-// Skip on WSL (no display) or when SKIP_BROWSER_TESTS is set
-const isWSL = (() => {
-  try {
-    return os.platform() === 'linux' && fs.readFileSync('/proc/version', 'utf8').toLowerCase().includes('microsoft');
-  } catch { return false; }
-})();
-const skipBrowser = isWSL || process.env.SKIP_BROWSER_TESTS === 'true';
-
-const describeIfBrowser = skipBrowser ? describe.skip : describe;
-
-let WebTool;
-let wt;
-const silentLogger = { info() {}, warn() {}, error() {}, debug() {} };
-
-beforeAll(async () => {
-  if (skipBrowser) return;
-  const mod = await import('../../tools/webTool.js');
-  WebTool = mod.default;
-  wt = new WebTool({ logger: silentLogger });
-}, 30000);
-
-afterAll(async () => {
-  try { await wt.cleanup?.(); } catch {}
-}, 15000);
-
-// ─── HTTP Status Detection ──────────────────────────────────────────────────
-
-describeIfBrowser('HTTP status detection', () => {
-  test('fetch valid page returns success with HTTP 200', async () => {
-    const result = await wt.execute(
-      { operation: 'fetch', url: 'https://example.com', formats: ['title'] },
-      { agentId: 'http-test', context: {} }
-    );
-    expect(result.success).toBe(true);
-    expect(result.httpStatus).toBe(200);
-    expect(result.title).toBe('Example Domain');
-  }, 30000);
-
-  test('fetch 404 page returns success=false with HTTP 404', async () => {
-    const result = await wt.execute(
-      { operation: 'fetch', url: 'https://github.com/zzzzz999nonexistentuser/zzzzz999nonexistrepo' },
-      { agentId: 'http-test', context: {} }
-    );
-    expect(result.success).toBe(false);
-    expect(result.httpStatus).toBe(404);
-    expect(result.error).toContain('404');
-    expect(result.error).toContain('page not found');
-  }, 30000);
-
-  test('fetch returns httpStatus in result for successful pages', async () => {
-    const result = await wt.execute(
-      { operation: 'fetch', url: 'https://example.com', formats: ['title'] },
-      { agentId: 'http-test', context: {} }
-    );
-    expect(result.httpStatus).toBeDefined();
-    expect(typeof result.httpStatus).toBe('number');
-  }, 30000);
-});
-
-// ─── Selector Pre-Validation ─────────────────────────────────────────────────
-
-describeIfBrowser('Selector pre-validation', () => {
-  test('click on non-existent selector returns actionable error', async () => {
-    const result = await wt.execute({
-      operation: 'interactive',
-      actions: [{
-        type: 'open-tab',
-        name: 'sel-click',
-        url: 'https://example.com',
-        actions: [{ action: 'click', selector: '#nonexistent-button-xyz' }]
-      }]
-    }, { agentId: 'sel-test', context: {} });
-
-    expect(result.success).toBe(false);
-    const clickResult = result.data?.results?.[0]?.results?.[0];
-    expect(clickResult).toBeDefined();
-    expect(clickResult.success).toBe(false);
-    expect(clickResult.error).toContain('Element not found');
-    expect(clickResult.error).toContain('#nonexistent-button-xyz');
-    expect(clickResult.error).toContain('example.com');
-    expect(clickResult.suggestion).toBeDefined();
-  }, 30000);
-
-  test('type on non-existent selector returns actionable error', async () => {
-    const result = await wt.execute({
-      operation: 'interactive',
-      actions: [{
-        type: 'open-tab',
-        name: 'sel-type',
-        url: 'https://example.com',
-        actions: [{ action: 'type', selector: '#nonexistent-input', text: 'hello' }]
-      }]
-    }, { agentId: 'sel-test', context: {} });
-
-    expect(result.success).toBe(false);
-    const typeResult = result.data?.results?.[0]?.results?.[0];
-    expect(typeResult.success).toBe(false);
-    expect(typeResult.error).toContain('Element not found');
-    expect(typeResult.error).toContain('#nonexistent-input');
-  }, 30000);
-
-  test('hover on non-existent selector returns error', async () => {
-    const result = await wt.execute({
-      operation: 'interactive',
-      actions: [{
-        type: 'open-tab',
-        name: 'sel-hover',
-        url: 'https://example.com',
-        actions: [{ action: 'hover', selector: '.does-not-exist' }]
-      }]
-    }, { agentId: 'sel-test', context: {} });
-
-    expect(result.success).toBe(false);
-    const hoverResult = result.data?.results?.[0]?.results?.[0];
-    expect(hoverResult.success).toBe(false);
-    expect(hoverResult.error).toContain('Element not found');
-  }, 30000);
-
-  test('submit on non-existent form returns error', async () => {
-    const result = await wt.execute({
-      operation: 'interactive',
-      actions: [{
-        type: 'open-tab',
-        name: 'sel-submit',
-        url: 'https://example.com',
-        actions: [{ action: 'submit', selector: '#no-form' }]
-      }]
-    }, { agentId: 'sel-test', context: {} });
-
-    expect(result.success).toBe(false);
-    const submitResult = result.data?.results?.[0]?.results?.[0];
-    expect(submitResult.success).toBe(false);
-    expect(submitResult.error).toContain('Element not found');
-  }, 30000);
-
-  test('extract-text on non-existent element returns error', async () => {
-    const result = await wt.execute({
-      operation: 'interactive',
-      actions: [{
-        type: 'open-tab',
-        name: 'sel-extract',
-        url: 'https://example.com',
-        actions: [{ action: 'extract-text', selector: '#no-such-element' }]
-      }]
-    }, { agentId: 'sel-test', context: {} });
-
-    expect(result.success).toBe(false);
-    const extractResult = result.data?.results?.[0]?.results?.[0];
-    expect(extractResult.success).toBe(false);
-    expect(extractResult.error).toContain('Element not found');
-  }, 30000);
-
-  test('click with no selector returns clear error', async () => {
-    const result = await wt.execute({
-      operation: 'interactive',
-      actions: [{
-        type: 'open-tab',
-        name: 'sel-noselector',
-        url: 'https://example.com',
-        actions: [{ action: 'click' }]
-      }]
-    }, { agentId: 'sel-test', context: {} });
-
-    expect(result.success).toBe(false);
-    const clickResult = result.data?.results?.[0]?.results?.[0];
-    expect(clickResult.success).toBe(false);
-    expect(clickResult.error).toContain('selector is required');
-  }, 30000);
-});
-
-// ─── URL Validation in Interactive ───────────────────────────────────────────
-
-describeIfBrowser('URL validation in interactive actions', () => {
-  test('navigate to invalid URL returns error without crashing', async () => {
-    const result = await wt.execute({
-      operation: 'interactive',
-      actions: [{
-        type: 'open-tab',
-        name: 'url-invalid',
-        url: 'https://example.com',
-        actions: [{ action: 'navigate', url: 'not-a-valid-url' }]
-      }]
-    }, { agentId: 'url-test', context: {} });
-
-    expect(result.success).toBe(false);
-    const navResult = result.data?.results?.[0]?.results?.[0];
-    expect(navResult.success).toBe(false);
-    expect(navResult.error).toContain('Invalid URL format');
-  }, 30000);
-
-  test('navigate with no URL returns error', async () => {
-    const result = await wt.execute({
-      operation: 'interactive',
-      actions: [{
-        type: 'open-tab',
-        name: 'url-empty',
-        url: 'https://example.com',
-        actions: [{ action: 'navigate' }]
-      }]
-    }, { agentId: 'url-test', context: {} });
-
-    expect(result.success).toBe(false);
-    const navResult = result.data?.results?.[0]?.results?.[0];
-    expect(navResult.success).toBe(false);
-    expect(navResult.error).toContain('URL is required');
-  }, 30000);
-});
-
-// ─── Wait-for Timeout Feedback ───────────────────────────────────────────────
-
-describeIfBrowser('Wait-for timeout feedback', () => {
-  test('wait-for non-existent element returns timeout error with context', async () => {
-    const result = await wt.execute({
-      operation: 'interactive',
-      actions: [{
-        type: 'open-tab',
-        name: 'wait-test',
-        url: 'https://example.com',
-        actions: [{ action: 'wait-for', selector: '#element-that-will-never-exist', timeout: 2000 }]
-      }]
-    }, { agentId: 'wait-test', context: {} });
-
-    expect(result.success).toBe(false);
-    const waitResult = result.data?.results?.[0]?.results?.[0];
-    expect(waitResult.success).toBe(false);
-    expect(waitResult.error).toContain('did not appear');
-    expect(waitResult.error).toContain('2s');
-    expect(waitResult.error).toContain('example.com');
-    expect(waitResult.suggestion).toBeDefined();
-  }, 15000);
-
-  test('wait-for with no selector returns error', async () => {
-    const result = await wt.execute({
-      operation: 'interactive',
-      actions: [{
-        type: 'open-tab',
-        name: 'wait-nosel',
-        url: 'https://example.com',
-        actions: [{ action: 'wait-for' }]
-      }]
-    }, { agentId: 'wait-test', context: {} });
-
-    expect(result.success).toBe(false);
-    const waitResult = result.data?.results?.[0]?.results?.[0];
-    expect(waitResult.success).toBe(false);
-    expect(waitResult.error).toContain('selector is required');
-  }, 15000);
-});
-
-// ─── Successful Operations ───────────────────────────────────────────────────
-
-describeIfBrowser('Successful operations', () => {
-  test('extract-text on existing element returns content', async () => {
-    const result = await wt.execute({
-      operation: 'interactive',
-      actions: [{
-        type: 'open-tab',
-        name: 'success-extract',
-        url: 'https://example.com',
-        actions: [{ action: 'extract-text', selector: 'h1' }]
-      }]
-    }, { agentId: 'success-test', context: {} });
-
-    expect(result.success).toBe(true);
-    const extractResult = result.data?.results?.[0]?.results?.[0];
-    expect(extractResult.success).toBe(true);
-    expect(extractResult.text).toContain('Example Domain');
-  }, 30000);
-
-  test('navigate to valid URL returns success with HTTP status', async () => {
-    const result = await wt.execute({
-      operation: 'interactive',
-      actions: [{
-        type: 'open-tab',
-        name: 'success-nav',
-        url: 'https://example.com',
-        actions: [{ action: 'navigate', url: 'https://example.com' }]
-      }]
-    }, { agentId: 'success-test', context: {} });
-
-    expect(result.success).toBe(true);
-    const navResult = result.data?.results?.[0]?.results?.[0];
-    expect(navResult.success).toBe(true);
-    expect(navResult.httpStatus).toBe(200);
-    expect(navResult.url).toContain('example.com');
-  }, 30000);
-
-  // SKIP: deterministically fails when run as part of the suite (passes
-  // alone in <5 s). Root cause is external — example.com appears to
-  // rate-limit / serve a different response to subsequent in-rapid-
-  // succession requests from the same source, and the `<a>` element
-  // selector then fails to match. The other "Successful operations"
-  // tests are also hitting example.com but only fetch/extract — the
-  // click is what trips the heuristic.
-  //
-  // Proper fix is a local test-server fixture (host a static HTML
-  // page from the test setup, point all "Successful operations" tests
-  // at it) — that gives deterministic behavior + cuts e2e time. Out
-  // of scope for the current change; tracked as a follow-on item.
-  test.skip('click on existing element succeeds (rate-limited by example.com when run in suite — needs local test fixture)', async () => {
-    const result = await wt.execute({
-      operation: 'interactive',
-      actions: [{
-        type: 'open-tab',
-        name: 'success-click',
-        url: 'https://example.com',
-        actions: [{ action: 'click', selector: 'a' }]
-      }]
-    }, { agentId: 'success-test', context: {} });
-
-    expect(result.success).toBe(true);
-    const clickResult = result.data?.results?.[0]?.results?.[0];
-    expect(clickResult.success).toBe(true);
-  }, 30000);
-
-  test('wait/delay action succeeds with correct timing', async () => {
-    const start = Date.now();
-    const result = await wt.execute({
-      operation: 'interactive',
-      actions: [{
-        type: 'open-tab',
-        name: 'success-wait',
-        url: 'https://example.com',
-        actions: [{ action: 'wait', waitTime: 1000 }]
-      }]
-    }, { agentId: 'success-test', context: {} });
-
-    const elapsed = Date.now() - start;
-    expect(result.success).toBe(true);
-    const waitResult = result.data?.results?.[0]?.results?.[0];
-    expect(waitResult.success).toBe(true);
-    expect(waitResult.waited).toBe(1000);
-    // Should have taken at least ~1s
-    expect(elapsed).toBeGreaterThan(800);
-  }, 30000);
-});
-
-// ─── Search ──────────────────────────────────────────────────────────────────
-
-describeIfBrowser('Search operations', () => {
-  test('search with valid query returns results', async () => {
-    const result = await wt.execute(
-      { operation: 'search', query: 'javascript MDN', engine: 'duckduckgo', maxResults: 3 },
-      { agentId: 'search-test', context: {} }
-    );
-    expect(result.success).toBe(true);
-    expect(result.resultsCount).toBeGreaterThan(0);
-    expect(result.data?.results?.length).toBeGreaterThan(0);
-    // Each result should have url and title
-    const firstResult = result.data.results[0];
-    expect(firstResult.url).toBeDefined();
-    expect(firstResult.title).toBeDefined();
-  }, 45000);
-
-  test('search with empty query returns error', async () => {
-    const result = await wt.execute(
-      { operation: 'search', query: '' },
-      { agentId: 'search-test', context: {} }
-    );
-    expect(result.success).toBe(false);
-  }, 10000);
-});
-
-// ─── Multi-Action Chains ─────────────────────────────────────────────────────
-
-describeIfBrowser('Multi-action chains', () => {
-  test('chain of actions reports per-action success/failure', async () => {
-    const result = await wt.execute({
-      operation: 'interactive',
-      actions: [{
-        type: 'open-tab',
-        name: 'chain-test',
-        url: 'https://example.com',
-        actions: [
-          { action: 'extract-text', selector: 'h1' },          // should succeed
-          { action: 'click', selector: '#nonexistent-button' }, // should fail
-          { action: 'extract-text', selector: 'p' },           // should succeed
-        ]
-      }]
-    }, { agentId: 'chain-test', context: {} });
-
-    // Overall should be false because one action failed
-    expect(result.success).toBe(false);
-    // Warning lives on the open-tab action result (nested)
-    const openTabResult = result.data?.results?.[0];
-    expect(openTabResult.success).toBe(false);
-    expect(openTabResult.warning).toContain('1 of');
-
-    const actionResults = result.data?.results?.[0]?.results;
-    expect(actionResults).toHaveLength(3);
-    expect(actionResults[0].success).toBe(true);  // extract h1
-    expect(actionResults[1].success).toBe(false);  // click nonexistent
-    expect(actionResults[2].success).toBe(true);  // extract p
-  }, 30000);
-
-  test('action chain continues after a failed action', async () => {
-    const result = await wt.execute({
-      operation: 'interactive',
-      actions: [{
-        type: 'open-tab',
-        name: 'continue-test',
-        url: 'https://example.com',
-        actions: [
-          { action: 'click', selector: '#nope' },       // fails
-          { action: 'extract-text', selector: 'h1' },   // still runs
-        ]
-      }]
-    }, { agentId: 'chain-test', context: {} });
-
-    const actionResults = result.data?.results?.[0]?.results;
-    // Second action should still have executed
-    expect(actionResults).toHaveLength(2);
-    expect(actionResults[1].success).toBe(true);
-    expect(actionResults[1].text).toContain('Example Domain');
-  }, 30000);
-});
-
-// ─── Tab Reuse ───────────────────────────────────────────────────────────────
-
-describeIfBrowser('Tab reuse', () => {
-  test('reusing existing tab preserves session and returns reused flag', async () => {
-    // First: open tab
-    await wt.execute({
-      operation: 'interactive',
-      actions: [{
-        type: 'open-tab',
-        name: 'reuse-tab',
-        url: 'https://example.com',
-        actions: []
-      }]
-    }, { agentId: 'reuse-test', context: {} });
-
-    // Second: reuse same tab
-    const result = await wt.execute({
-      operation: 'interactive',
-      actions: [{
-        type: 'open-tab',
-        name: 'reuse-tab',
-        actions: [{ action: 'extract-text', selector: 'h1' }]
-      }]
-    }, { agentId: 'reuse-test', context: {} });
-
-    expect(result.success).toBe(true);
-    expect(result.data?.results?.[0]?.reused).toBe(true);
-    const extractResult = result.data?.results?.[0]?.results?.[0];
-    expect(extractResult.text).toContain('Example Domain');
-  }, 30000);
-});
-
-// ─── JS Error & Network Failure Detection ────────────────────────────────────
-
-describeIfBrowser('JS error and network failure detection', () => {
-  test('JS errors on page are captured in pageErrors tracker', async () => {
-    // Open tab first
-    await wt.execute({
-      operation: 'interactive',
-      actions: [{
-        type: 'open-tab',
-        name: 'jserr-tab',
-        url: 'https://example.com',
-        actions: [{ action: 'navigate', url: 'https://example.com' }]
-      }]
-    }, { agentId: 'jserr-test', context: {} });
-
-    // Access internal tab to verify listeners exist
-    const tab = wt.agentTabs.get('jserr-test')?.get('jserr-tab');
-    expect(tab).toBeDefined();
-    expect(tab.pageErrors).toBeDefined();
-    expect(Array.isArray(tab.pageErrors)).toBe(true);
-    expect(tab.networkFailures).toBeDefined();
-    expect(Array.isArray(tab.networkFailures)).toBe(true);
-    expect(tab.httpErrors).toBeDefined();
-    expect(Array.isArray(tab.httpErrors)).toBe(true);
-  }, 30000);
-
-  test('listeners are attached and capture uncaught JS errors', async () => {
-    // Open tab
-    await wt.execute({
-      operation: 'interactive',
-      actions: [{
-        type: 'open-tab',
-        name: 'jserr-capture',
-        url: 'https://example.com',
-        actions: []
-      }]
-    }, { agentId: 'jserr-capture', context: {} });
-
-    const tab = wt.agentTabs.get('jserr-capture')?.get('jserr-capture');
-    expect(tab).toBeDefined();
-
-    // Inject a JS error
-    await tab.page.evaluate(() => {
-      setTimeout(() => { throw new Error('Test uncaught error'); }, 10);
-    });
-    await new Promise(r => setTimeout(r, 500));
-
-    expect(tab.pageErrors.length).toBeGreaterThan(0);
-    expect(tab.pageErrors[0].message).toContain('Test uncaught error');
-  }, 30000);
-
-  test('failed network requests are captured', async () => {
-    await wt.execute({
-      operation: 'interactive',
-      actions: [{
-        type: 'open-tab',
-        name: 'netfail-capture',
-        url: 'https://example.com',
-        actions: []
-      }]
-    }, { agentId: 'netfail-capture', context: {} });
-
-    const tab = wt.agentTabs.get('netfail-capture')?.get('netfail-capture');
-    expect(tab).toBeDefined();
-
-    // Trigger a failed fetch
-    await tab.page.evaluate(() => {
-      fetch('https://api.nonexistent-domain-xyz-test.com/endpoint').catch(() => {});
-    });
-    await new Promise(r => setTimeout(r, 3000));
-
-    expect(tab.networkFailures.length).toBeGreaterThan(0);
-    expect(tab.networkFailures[0].errorText).toContain('ERR_NAME_NOT_RESOLVED');
-    expect(tab.networkFailures[0].url).toContain('nonexistent-domain-xyz-test');
-  }, 30000);
-});
-
-// ─── Result Structure ────────────────────────────────────────────────────────
-
-describeIfBrowser('Result structure and data consistency', () => {
-  test('fetch result has required fields', async () => {
-    const result = await wt.execute(
-      { operation: 'fetch', url: 'https://example.com', formats: ['title', 'text'] },
-      { agentId: 'struct-test', context: {} }
-    );
-    expect(result).toHaveProperty('success');
-    expect(result).toHaveProperty('operation', 'fetch');
-    expect(result).toHaveProperty('toolUsed', 'web');
-    expect(result).toHaveProperty('data');
-    expect(result).toHaveProperty('title');
-    expect(result).toHaveProperty('httpStatus');
-  }, 30000);
-
-  test('interactive result has actionsExecuted count', async () => {
-    const result = await wt.execute({
-      operation: 'interactive',
-      actions: [{
-        type: 'open-tab',
-        name: 'struct-tab',
-        url: 'https://example.com',
-        actions: [
-          { action: 'extract-text', selector: 'h1' },
-          { action: 'extract-text', selector: 'p' },
-        ]
-      }]
-    }, { agentId: 'struct-test', context: {} });
-
-    expect(result.data?.results?.[0]?.actionsExecuted).toBe(2);
-    expect(result.data?.results?.[0]?.results).toHaveLength(2);
-  }, 30000);
-
-  test('error results include suggestion field', async () => {
-    const result = await wt.execute({
-      operation: 'interactive',
-      actions: [{
-        type: 'open-tab',
-        name: 'suggest-tab',
-        url: 'https://example.com',
-        actions: [{ action: 'click', selector: '#nope' }]
-      }]
-    }, { agentId: 'struct-test', context: {} });
-
-    const clickResult = result.data?.results?.[0]?.results?.[0];
-    expect(clickResult.suggestion).toBeDefined();
-    expect(typeof clickResult.suggestion).toBe('string');
-    expect(clickResult.suggestion.length).toBeGreaterThan(0);
-  }, 30000);
-});
+/**
+ * WebTool E2E Tests
+ *
+ * These tests launch a REAL headless browser and test against live pages.
+ * They validate error detection, HTTP status handling, selector feedback,
+ * and the full execute → result pipeline.
+ *
+ * NOTE: These tests require network access and a working Puppeteer install.
+ * They are slower (~60s total) and are tagged for separate runs.
+ * Skipped on WSL/headless Linux (no display server for Chromium).
+ *
+ * Run with: npm run test:e2e
+ */
+
+import { describe, test, expect, beforeAll, afterAll, jest } from '@jest/globals';
+
+// Real-network tests against example.com / iana.org are inherently
+// flaky on TCP / DNS / target-server hiccups. The contract under test
+// is "the WebTool chain machinery works", not "example.com is always
+// up", so we tolerate up to 2 retries before declaring failure.
+// If a test fails 3 times in a row, that's a real signal worth
+// investigating; transient flakes get absorbed silently.
+jest.retryTimes(2, { logErrorsBeforeRetry: true });
+import os from 'os';
+import fs from 'fs';
+
+// Skip on WSL (no display) or when SKIP_BROWSER_TESTS is set
+const isWSL = (() => {
+  try {
+    return os.platform() === 'linux' && fs.readFileSync('/proc/version', 'utf8').toLowerCase().includes('microsoft');
+  } catch { return false; }
+})();
+const skipBrowser = isWSL || process.env.SKIP_BROWSER_TESTS === 'true';
+
+const describeIfBrowser = skipBrowser ? describe.skip : describe;
+
+let WebTool;
+let wt;
+const silentLogger = { info() {}, warn() {}, error() {}, debug() {} };
+
+beforeAll(async () => {
+  if (skipBrowser) return;
+  const mod = await import('../../tools/webTool.js');
+  WebTool = mod.default;
+  wt = new WebTool({ logger: silentLogger });
+}, 30000);
+
+afterAll(async () => {
+  try { await wt.cleanup?.(); } catch { /* swallow */ }
+}, 15000);
+
+// ─── HTTP Status Detection ──────────────────────────────────────────────────
+
+describeIfBrowser('HTTP status detection', () => {
+  test('fetch valid page returns success with HTTP 200', async () => {
+    const result = await wt.execute(
+      { operation: 'fetch', url: 'https://example.com', formats: ['title'] },
+      { agentId: 'http-test', context: {} }
+    );
+    expect(result.success).toBe(true);
+    expect(result.httpStatus).toBe(200);
+    expect(result.title).toBe('Example Domain');
+  }, 30000);
+
+  test('fetch 404 page returns success=false with HTTP 404', async () => {
+    const result = await wt.execute(
+      { operation: 'fetch', url: 'https://github.com/zzzzz999nonexistentuser/zzzzz999nonexistrepo' },
+      { agentId: 'http-test', context: {} }
+    );
+    expect(result.success).toBe(false);
+    expect(result.httpStatus).toBe(404);
+    expect(result.error).toContain('404');
+    expect(result.error).toContain('page not found');
+  }, 30000);
+
+  test('fetch returns httpStatus in result for successful pages', async () => {
+    const result = await wt.execute(
+      { operation: 'fetch', url: 'https://example.com', formats: ['title'] },
+      { agentId: 'http-test', context: {} }
+    );
+    expect(result.httpStatus).toBeDefined();
+    expect(typeof result.httpStatus).toBe('number');
+  }, 30000);
+});
+
+// ─── Selector Pre-Validation ─────────────────────────────────────────────────
+
+describeIfBrowser('Selector pre-validation', () => {
+  test('click on non-existent selector returns actionable error', async () => {
+    const result = await wt.execute({
+      operation: 'interactive',
+      actions: [{
+        type: 'open-tab',
+        name: 'sel-click',
+        url: 'https://example.com',
+        actions: [{ action: 'click', selector: '#nonexistent-button-xyz' }]
+      }]
+    }, { agentId: 'sel-test', context: {} });
+
+    expect(result.success).toBe(false);
+    const clickResult = result.data?.results?.[0]?.results?.[0];
+    expect(clickResult).toBeDefined();
+    expect(clickResult.success).toBe(false);
+    expect(clickResult.error).toContain('Element not found');
+    expect(clickResult.error).toContain('#nonexistent-button-xyz');
+    expect(clickResult.error).toContain('example.com');
+    expect(clickResult.suggestion).toBeDefined();
+  }, 30000);
+
+  test('type on non-existent selector returns actionable error', async () => {
+    const result = await wt.execute({
+      operation: 'interactive',
+      actions: [{
+        type: 'open-tab',
+        name: 'sel-type',
+        url: 'https://example.com',
+        actions: [{ action: 'type', selector: '#nonexistent-input', text: 'hello' }]
+      }]
+    }, { agentId: 'sel-test', context: {} });
+
+    expect(result.success).toBe(false);
+    const typeResult = result.data?.results?.[0]?.results?.[0];
+    expect(typeResult.success).toBe(false);
+    expect(typeResult.error).toContain('Element not found');
+    expect(typeResult.error).toContain('#nonexistent-input');
+  }, 30000);
+
+  test('hover on non-existent selector returns error', async () => {
+    const result = await wt.execute({
+      operation: 'interactive',
+      actions: [{
+        type: 'open-tab',
+        name: 'sel-hover',
+        url: 'https://example.com',
+        actions: [{ action: 'hover', selector: '.does-not-exist' }]
+      }]
+    }, { agentId: 'sel-test', context: {} });
+
+    expect(result.success).toBe(false);
+    const hoverResult = result.data?.results?.[0]?.results?.[0];
+    expect(hoverResult.success).toBe(false);
+    expect(hoverResult.error).toContain('Element not found');
+  }, 30000);
+
+  test('submit on non-existent form returns error', async () => {
+    const result = await wt.execute({
+      operation: 'interactive',
+      actions: [{
+        type: 'open-tab',
+        name: 'sel-submit',
+        url: 'https://example.com',
+        actions: [{ action: 'submit', selector: '#no-form' }]
+      }]
+    }, { agentId: 'sel-test', context: {} });
+
+    expect(result.success).toBe(false);
+    const submitResult = result.data?.results?.[0]?.results?.[0];
+    expect(submitResult.success).toBe(false);
+    expect(submitResult.error).toContain('Element not found');
+  }, 30000);
+
+  test('extract-text on non-existent element returns error', async () => {
+    const result = await wt.execute({
+      operation: 'interactive',
+      actions: [{
+        type: 'open-tab',
+        name: 'sel-extract',
+        url: 'https://example.com',
+        actions: [{ action: 'extract-text', selector: '#no-such-element' }]
+      }]
+    }, { agentId: 'sel-test', context: {} });
+
+    expect(result.success).toBe(false);
+    const extractResult = result.data?.results?.[0]?.results?.[0];
+    expect(extractResult.success).toBe(false);
+    expect(extractResult.error).toContain('Element not found');
+  }, 30000);
+
+  test('click with no selector returns clear error', async () => {
+    const result = await wt.execute({
+      operation: 'interactive',
+      actions: [{
+        type: 'open-tab',
+        name: 'sel-noselector',
+        url: 'https://example.com',
+        actions: [{ action: 'click' }]
+      }]
+    }, { agentId: 'sel-test', context: {} });
+
+    expect(result.success).toBe(false);
+    const clickResult = result.data?.results?.[0]?.results?.[0];
+    expect(clickResult.success).toBe(false);
+    expect(clickResult.error).toContain('selector is required');
+  }, 30000);
+});
+
+// ─── URL Validation in Interactive ───────────────────────────────────────────
+
+describeIfBrowser('URL validation in interactive actions', () => {
+  test('navigate to invalid URL returns error without crashing', async () => {
+    const result = await wt.execute({
+      operation: 'interactive',
+      actions: [{
+        type: 'open-tab',
+        name: 'url-invalid',
+        url: 'https://example.com',
+        actions: [{ action: 'navigate', url: 'not-a-valid-url' }]
+      }]
+    }, { agentId: 'url-test', context: {} });
+
+    expect(result.success).toBe(false);
+    const navResult = result.data?.results?.[0]?.results?.[0];
+    expect(navResult.success).toBe(false);
+    expect(navResult.error).toContain('Invalid URL format');
+  }, 30000);
+
+  test('navigate with no URL returns error', async () => {
+    const result = await wt.execute({
+      operation: 'interactive',
+      actions: [{
+        type: 'open-tab',
+        name: 'url-empty',
+        url: 'https://example.com',
+        actions: [{ action: 'navigate' }]
+      }]
+    }, { agentId: 'url-test', context: {} });
+
+    expect(result.success).toBe(false);
+    const navResult = result.data?.results?.[0]?.results?.[0];
+    expect(navResult.success).toBe(false);
+    expect(navResult.error).toContain('URL is required');
+  }, 30000);
+});
+
+// ─── Wait-for Timeout Feedback ───────────────────────────────────────────────
+
+describeIfBrowser('Wait-for timeout feedback', () => {
+  test('wait-for non-existent element returns timeout error with context', async () => {
+    const result = await wt.execute({
+      operation: 'interactive',
+      actions: [{
+        type: 'open-tab',
+        name: 'wait-test',
+        url: 'https://example.com',
+        actions: [{ action: 'wait-for', selector: '#element-that-will-never-exist', timeout: 2000 }]
+      }]
+    }, { agentId: 'wait-test', context: {} });
+
+    expect(result.success).toBe(false);
+    const waitResult = result.data?.results?.[0]?.results?.[0];
+    expect(waitResult.success).toBe(false);
+    expect(waitResult.error).toContain('did not appear');
+    expect(waitResult.error).toContain('2s');
+    expect(waitResult.error).toContain('example.com');
+    expect(waitResult.suggestion).toBeDefined();
+  }, 15000);
+
+  test('wait-for with no selector returns error', async () => {
+    const result = await wt.execute({
+      operation: 'interactive',
+      actions: [{
+        type: 'open-tab',
+        name: 'wait-nosel',
+        url: 'https://example.com',
+        actions: [{ action: 'wait-for' }]
+      }]
+    }, { agentId: 'wait-test', context: {} });
+
+    expect(result.success).toBe(false);
+    const waitResult = result.data?.results?.[0]?.results?.[0];
+    expect(waitResult.success).toBe(false);
+    expect(waitResult.error).toContain('selector is required');
+  }, 15000);
+});
+
+// ─── Successful Operations ───────────────────────────────────────────────────
+
+describeIfBrowser('Successful operations', () => {
+  test('extract-text on existing element returns content', async () => {
+    const result = await wt.execute({
+      operation: 'interactive',
+      actions: [{
+        type: 'open-tab',
+        name: 'success-extract',
+        url: 'https://example.com',
+        actions: [{ action: 'extract-text', selector: 'h1' }]
+      }]
+    }, { agentId: 'success-test', context: {} });
+
+    expect(result.success).toBe(true);
+    const extractResult = result.data?.results?.[0]?.results?.[0];
+    expect(extractResult.success).toBe(true);
+    expect(extractResult.text).toContain('Example Domain');
+  }, 30000);
+
+  test('navigate to valid URL returns success with HTTP status', async () => {
+    const result = await wt.execute({
+      operation: 'interactive',
+      actions: [{
+        type: 'open-tab',
+        name: 'success-nav',
+        url: 'https://example.com',
+        actions: [{ action: 'navigate', url: 'https://example.com' }]
+      }]
+    }, { agentId: 'success-test', context: {} });
+
+    expect(result.success).toBe(true);
+    const navResult = result.data?.results?.[0]?.results?.[0];
+    expect(navResult.success).toBe(true);
+    // example.com serves 304 Not Modified on subsequent calls in the same
+    // suite (the previous test fetched the same URL and the browser cached
+    // it). Both 200 and 304 indicate a successful navigation — we only care
+    // that the page loaded, not whether the body was re-sent over the wire.
+    // Anything in [200, 400) is a healthy navigation outcome.
+    expect(navResult.httpStatus).toBeGreaterThanOrEqual(200);
+    expect(navResult.httpStatus).toBeLessThan(400);
+    expect(navResult.url).toContain('example.com');
+  }, 30000);
+
+  // SKIP: deterministically fails when run as part of the suite (passes
+  // alone in <5 s). Root cause is external — example.com appears to
+  // rate-limit / serve a different response to subsequent in-rapid-
+  // succession requests from the same source, and the `<a>` element
+  // selector then fails to match. The other "Successful operations"
+  // tests are also hitting example.com but only fetch/extract — the
+  // click is what trips the heuristic.
+  //
+  // Proper fix is a local test-server fixture (host a static HTML
+  // page from the test setup, point all "Successful operations" tests
+  // at it) — that gives deterministic behavior + cuts e2e time. Out
+  // of scope for the current change; tracked as a follow-on item.
+  test.skip('click on existing element succeeds (rate-limited by example.com when run in suite — needs local test fixture)', async () => {
+    const result = await wt.execute({
+      operation: 'interactive',
+      actions: [{
+        type: 'open-tab',
+        name: 'success-click',
+        url: 'https://example.com',
+        actions: [{ action: 'click', selector: 'a' }]
+      }]
+    }, { agentId: 'success-test', context: {} });
+
+    expect(result.success).toBe(true);
+    const clickResult = result.data?.results?.[0]?.results?.[0];
+    expect(clickResult.success).toBe(true);
+  }, 30000);
+
+  test('wait/delay action succeeds with correct timing', async () => {
+    const start = Date.now();
+    const result = await wt.execute({
+      operation: 'interactive',
+      actions: [{
+        type: 'open-tab',
+        name: 'success-wait',
+        url: 'https://example.com',
+        actions: [{ action: 'wait', waitTime: 1000 }]
+      }]
+    }, { agentId: 'success-test', context: {} });
+
+    const elapsed = Date.now() - start;
+    expect(result.success).toBe(true);
+    const waitResult = result.data?.results?.[0]?.results?.[0];
+    expect(waitResult.success).toBe(true);
+    expect(waitResult.waited).toBe(1000);
+    // Should have taken at least ~1s
+    expect(elapsed).toBeGreaterThan(800);
+  }, 30000);
+});
+
+// ─── Search ──────────────────────────────────────────────────────────────────
+
+describeIfBrowser('Search operations', () => {
+  test('search with valid query returns results', async () => {
+    const result = await wt.execute(
+      { operation: 'search', query: 'javascript MDN', engine: 'duckduckgo', maxResults: 3 },
+      { agentId: 'search-test', context: {} }
+    );
+    expect(result.success).toBe(true);
+    expect(result.resultsCount).toBeGreaterThan(0);
+    expect(result.data?.results?.length).toBeGreaterThan(0);
+    // Each result should have url and title
+    const firstResult = result.data.results[0];
+    expect(firstResult.url).toBeDefined();
+    expect(firstResult.title).toBeDefined();
+  }, 45000);
+
+  test('search with empty query returns error', async () => {
+    const result = await wt.execute(
+      { operation: 'search', query: '' },
+      { agentId: 'search-test', context: {} }
+    );
+    expect(result.success).toBe(false);
+  }, 10000);
+});
+
+// ─── Multi-Action Chains ─────────────────────────────────────────────────────
+
+describeIfBrowser('Multi-action chains', () => {
+  test('chain of actions reports per-action success/failure', async () => {
+    const result = await wt.execute({
+      operation: 'interactive',
+      actions: [{
+        type: 'open-tab',
+        name: 'chain-test',
+        url: 'https://example.com',
+        actions: [
+          { action: 'extract-text', selector: 'h1' },          // should succeed
+          { action: 'click', selector: '#nonexistent-button' }, // should fail
+          { action: 'extract-text', selector: 'p' },           // should succeed
+        ]
+      }]
+    }, { agentId: 'chain-test', context: {} });
+
+    // Overall should be false because one action failed
+    expect(result.success).toBe(false);
+    // Warning lives on the open-tab action result (nested)
+    const openTabResult = result.data?.results?.[0];
+    expect(openTabResult.success).toBe(false);
+    expect(openTabResult.warning).toContain('1 of');
+
+    const actionResults = result.data?.results?.[0]?.results;
+    expect(actionResults).toHaveLength(3);
+    expect(actionResults[0].success).toBe(true);  // extract h1
+    expect(actionResults[1].success).toBe(false);  // click nonexistent
+    expect(actionResults[2].success).toBe(true);  // extract p
+  }, 30000);
+
+  test('action chain continues after a failed action', async () => {
+    const result = await wt.execute({
+      operation: 'interactive',
+      actions: [{
+        type: 'open-tab',
+        name: 'continue-test',
+        url: 'https://example.com',
+        actions: [
+          { action: 'click', selector: '#nope' },       // fails
+          { action: 'extract-text', selector: 'h1' },   // still runs
+        ]
+      }]
+    }, { agentId: 'chain-test', context: {} });
+
+    const actionResults = result.data?.results?.[0]?.results;
+    // Second action should still have executed
+    expect(actionResults).toHaveLength(2);
+    expect(actionResults[1].success).toBe(true);
+    expect(actionResults[1].text).toContain('Example Domain');
+  }, 30000);
+});
+
+// ─── Tab Reuse ───────────────────────────────────────────────────────────────
+
+describeIfBrowser('Tab reuse', () => {
+  test('reusing existing tab preserves session and returns reused flag', async () => {
+    // First: open tab
+    await wt.execute({
+      operation: 'interactive',
+      actions: [{
+        type: 'open-tab',
+        name: 'reuse-tab',
+        url: 'https://example.com',
+        actions: []
+      }]
+    }, { agentId: 'reuse-test', context: {} });
+
+    // Second: reuse same tab
+    const result = await wt.execute({
+      operation: 'interactive',
+      actions: [{
+        type: 'open-tab',
+        name: 'reuse-tab',
+        actions: [{ action: 'extract-text', selector: 'h1' }]
+      }]
+    }, { agentId: 'reuse-test', context: {} });
+
+    expect(result.success).toBe(true);
+    expect(result.data?.results?.[0]?.reused).toBe(true);
+    const extractResult = result.data?.results?.[0]?.results?.[0];
+    expect(extractResult.text).toContain('Example Domain');
+  }, 30000);
+});
+
+// ─── JS Error & Network Failure Detection ────────────────────────────────────
+
+describeIfBrowser('JS error and network failure detection', () => {
+  test('JS errors on page are captured in pageErrors tracker', async () => {
+    // Open tab first
+    await wt.execute({
+      operation: 'interactive',
+      actions: [{
+        type: 'open-tab',
+        name: 'jserr-tab',
+        url: 'https://example.com',
+        actions: [{ action: 'navigate', url: 'https://example.com' }]
+      }]
+    }, { agentId: 'jserr-test', context: {} });
+
+    // Access internal tab to verify listeners exist
+    const tab = wt.agentTabs.get('jserr-test')?.get('jserr-tab');
+    expect(tab).toBeDefined();
+    expect(tab.pageErrors).toBeDefined();
+    expect(Array.isArray(tab.pageErrors)).toBe(true);
+    expect(tab.networkFailures).toBeDefined();
+    expect(Array.isArray(tab.networkFailures)).toBe(true);
+    expect(tab.httpErrors).toBeDefined();
+    expect(Array.isArray(tab.httpErrors)).toBe(true);
+  }, 30000);
+
+  test('listeners are attached and capture uncaught JS errors', async () => {
+    // Open tab
+    await wt.execute({
+      operation: 'interactive',
+      actions: [{
+        type: 'open-tab',
+        name: 'jserr-capture',
+        url: 'https://example.com',
+        actions: []
+      }]
+    }, { agentId: 'jserr-capture', context: {} });
+
+    const tab = wt.agentTabs.get('jserr-capture')?.get('jserr-capture');
+    expect(tab).toBeDefined();
+
+    // Inject a JS error
+    await tab.page.evaluate(() => {
+      setTimeout(() => { throw new Error('Test uncaught error'); }, 10);
+    });
+    await new Promise(r => setTimeout(r, 500));
+
+    expect(tab.pageErrors.length).toBeGreaterThan(0);
+    expect(tab.pageErrors[0].message).toContain('Test uncaught error');
+  }, 30000);
+
+  test('failed network requests are captured', async () => {
+    await wt.execute({
+      operation: 'interactive',
+      actions: [{
+        type: 'open-tab',
+        name: 'netfail-capture',
+        url: 'https://example.com',
+        actions: []
+      }]
+    }, { agentId: 'netfail-capture', context: {} });
+
+    const tab = wt.agentTabs.get('netfail-capture')?.get('netfail-capture');
+    expect(tab).toBeDefined();
+
+    // Trigger a failed fetch
+    await tab.page.evaluate(() => {
+      fetch('https://api.nonexistent-domain-xyz-test.com/endpoint').catch(() => {});
+    });
+    await new Promise(r => setTimeout(r, 3000));
+
+    expect(tab.networkFailures.length).toBeGreaterThan(0);
+    expect(tab.networkFailures[0].errorText).toContain('ERR_NAME_NOT_RESOLVED');
+    expect(tab.networkFailures[0].url).toContain('nonexistent-domain-xyz-test');
+  }, 30000);
+});
+
+// ─── Result Structure ────────────────────────────────────────────────────────
+
+describeIfBrowser('Result structure and data consistency', () => {
+  test('fetch result has required fields', async () => {
+    const result = await wt.execute(
+      { operation: 'fetch', url: 'https://example.com', formats: ['title', 'text'] },
+      { agentId: 'struct-test', context: {} }
+    );
+    expect(result).toHaveProperty('success');
+    expect(result).toHaveProperty('operation', 'fetch');
+    expect(result).toHaveProperty('toolUsed', 'web');
+    expect(result).toHaveProperty('data');
+    expect(result).toHaveProperty('title');
+    expect(result).toHaveProperty('httpStatus');
+  }, 30000);
+
+  test('interactive result has actionsExecuted count', async () => {
+    const result = await wt.execute({
+      operation: 'interactive',
+      actions: [{
+        type: 'open-tab',
+        name: 'struct-tab',
+        url: 'https://example.com',
+        actions: [
+          { action: 'extract-text', selector: 'h1' },
+          { action: 'extract-text', selector: 'p' },
+        ]
+      }]
+    }, { agentId: 'struct-test', context: {} });
+
+    expect(result.data?.results?.[0]?.actionsExecuted).toBe(2);
+    expect(result.data?.results?.[0]?.results).toHaveLength(2);
+  }, 30000);
+
+  test('error results include suggestion field', async () => {
+    const result = await wt.execute({
+      operation: 'interactive',
+      actions: [{
+        type: 'open-tab',
+        name: 'suggest-tab',
+        url: 'https://example.com',
+        actions: [{ action: 'click', selector: '#nope' }]
+      }]
+    }, { agentId: 'struct-test', context: {} });
+
+    const clickResult = result.data?.results?.[0]?.results?.[0];
+    expect(clickResult.suggestion).toBeDefined();
+    expect(typeof clickResult.suggestion).toBe('string');
+    expect(clickResult.suggestion.length).toBeGreaterThan(0);
+  }, 30000);
+});