testronaut 2.1.0 → 2.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testronaut",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "main": "./runner/testronaut.js",
   "bin": {
     "testronaut": "bin/cli.js"

package/tests/toolsTests/chromeBrowserClickText.test.js

@@ -69,4 +69,44 @@ describe('ChromeBrowser.check_text', () => {
 
     await expect(browser.check_text({ text: 'Hidden message' })).resolves.toBe('NOT FOUND: Hidden message');
   });
+
+  it('reports the iframe containing a visible match', async () => {
+    const noMatches = { count: vi.fn().mockResolvedValue(0) };
+    const frameMatches = {
+      count: vi.fn().mockResolvedValue(1),
+      nth: vi.fn().mockReturnValue({ isVisible: vi.fn().mockResolvedValue(true) }),
+    };
+    const mainFrame = { getByText: vi.fn().mockReturnValue(noMatches) };
+    const childFrame = {
+      getByText: vi.fn().mockReturnValue(frameMatches),
+      name: vi.fn().mockReturnValue(''),
+      frameElement: vi.fn().mockResolvedValue({ getAttribute: vi.fn().mockResolvedValue('webviewer-1') }),
+      url: vi.fn().mockReturnValue('https://example.test/viewer'),
+    };
+    const browser = Object.create(ChromeBrowser.prototype);
+    browser.page = {
+      mainFrame: vi.fn().mockReturnValue(mainFrame),
+      frames: vi.fn().mockReturnValue([mainFrame, childFrame]),
+    };
+
+    await expect(browser.check_text({ text: 'Quarterly report' }))
+      .resolves.toBe('FOUND in frame webviewer-1: Quarterly report');
+  });
+});
+
+describe('ChromeBrowser iframe interaction targeting', () => {
+  it('builds an explicit frame-qualified click locator', () => {
+    const locator = { first: vi.fn().mockReturnThis() };
+    const frameContext = { locator: vi.fn().mockReturnValue(locator) };
+    const browser = Object.create(ChromeBrowser.prototype);
+    browser.page = { frameLocator: vi.fn().mockReturnValue(frameContext) };
+
+    const [make] = browser._buildClickCandidates({
+      frame: 'iframe#webviewer-1', selector: 'button[aria-label="Settings"]', searchAllFrames: true,
+    });
+
+    expect(make()).toBe(locator);
+    expect(browser.page.frameLocator).toHaveBeenCalledWith('iframe#webviewer-1');
+    expect(frameContext.locator).toHaveBeenCalledWith('button[aria-label="Settings"]');
+  });
 });

package/tests/toolsTests/chromeBrowserGetDomFrames.test.js

@@ -0,0 +1,33 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ChromeBrowser } from '../../tools/chromeBrowser.js';
+
+describe('ChromeBrowser.get_dom iframe serialization', () => {
+  it('keeps serialized same-origin content and inaccessible-frame markers', async () => {
+    const browser = Object.create(ChromeBrowser.prototype);
+    browser.domListLimit = 3;
+    browser.debugEnabled = false;
+    browser.context = null;
+    browser.page = {
+      isClosed: vi.fn().mockReturnValue(false),
+      waitForLoadState: vi.fn().mockResolvedValue(undefined),
+      content: vi.fn().mockResolvedValue('<html><body></body></html>'),
+      evaluate: vi.fn().mockResolvedValue(`
+        <html><body>
+          <testronaut-frame id="viewer" data-testronaut-frame="viewer" data-testronaut-frame-status="same-origin">
+            <html><body><button aria-label="Settings">Settings</button><p>Quarterly report</p></body></html>
+          </testronaut-frame>
+          <testronaut-frame id="payment" data-testronaut-frame="payment" data-testronaut-frame-status="cross-origin">
+            [cross-origin frame, content not accessible]
+          </testronaut-frame>
+        </body></html>`),
+    };
+
+    const result = await browser.get_dom();
+
+    expect(result).toContain('data-testronaut-frame="viewer"');
+    expect(result).toContain('<iframe');
+    expect(result).toContain('Quarterly report');
+    expect(result).toContain('aria-label="Settings"');
+    expect(result).toContain('[cross-origin frame, content not accessible]');
+  });
+});

package/tests/toolsTests/domControl.test.js

@@ -56,7 +56,7 @@ describe('domControl helpers', () => {
       expect(result).not.toContain('<style');
       expect(result).not.toContain('<meta');
       expect(result).not.toContain('<link');
-      expect(result).not.toContain('<iframe');
+      expect(result).toContain('<iframe src="frame.html"></iframe>');
       expect(result).not.toContain('<canvas');
       expect(result).not.toContain('<svg');
       expect(result).not.toContain('<!-- comment -->');

package/tests/toolsTests/toolSchema.test.js

@@ -21,6 +21,14 @@ describe('tools/toolSchema', () => {
     const entry = toolsSchema.find(tool => tool.function.name === 'get_dom');
     expect(entry.function.parameters.properties.selector.type).toBe('string');
   });
+  it('exposes iframe targeting and iframe text search', () => {
+    const fill = toolsSchema.find(tool => tool.function.name === 'fill');
+    const click = toolsSchema.find(tool => tool.function.name === 'click');
+    const checkText = toolsSchema.find(tool => tool.function.name === 'check_text');
+    expect(fill.function.parameters.properties.frame.type).toBe('string');
+    expect(click.function.parameters.properties.frame.type).toBe('string');
+    expect(checkText.function.parameters.properties.searchAllFrames.default).toBe(true);
+  });
   it('includes resource_progress tool with empty params', () => {
     const entry = toolsSchema.find(t => t.function?.name === 'resource_progress');
     expect(entry?.type).toBe('function');

package/tools/chromeBrowser.js

@@ -180,8 +180,13 @@ export class ChromeBrowser {
   }
 
   // Build candidate locator MAKERS (Page|Frame-aware)
-  _buildClickCandidates({ selector, text, role, attrs, scope, searchAllFrames }) {
-    const frames = searchAllFrames ? this._allFrames({ includeMain: true }) : [this.page.mainFrame()];
+  _interactionContexts(frame, searchAllFrames) {
+    if (frame) return [this.page.frameLocator(frame)];
+    return searchAllFrames ? this._allFrames({ includeMain: true }) : [this.page.mainFrame()];
+  }
+
+  _buildClickCandidates({ selector, text, role, attrs, scope, searchAllFrames, frame }) {
+    const frames = this._interactionContexts(frame, searchAllFrames);
     const makers = [];
     const add = (fn) => fn && makers.push(fn);
 
@@ -211,8 +216,9 @@ export class ChromeBrowser {
       }
     }
 
-    const seen = new Set();
-    return makers.filter(fn => { const k = fn.toString(); if (seen.has(k)) return false; seen.add(k); return true; });
+    // Do not de-duplicate by function source: closures for different frames have
+    // identical source text but resolve against different documents.
+    return makers;
   }
 
 
@@ -459,8 +465,8 @@ export class ChromeBrowser {
   }
 
   // Build candidates for text entry (Page|Frame-aware)
-  _buildFillCandidates({ selector, placeholder, role = 'textbox', attrs, scope, searchAllFrames }) {
-    const frames = searchAllFrames ? this._allFrames({ includeMain: true }) : [this.page.mainFrame()];
+  _buildFillCandidates({ selector, placeholder, role = 'textbox', attrs, scope, searchAllFrames, frame }) {
+    const frames = this._interactionContexts(frame, searchAllFrames);
     const makers = [];
     const add = (fn) => fn && makers.push(fn);
 
@@ -499,9 +505,9 @@ export class ChromeBrowser {
       }
     }
 
-    // de-dup
-    const seen = new Set();
-    return makers.filter(fn => { const k = fn.toString(); if (seen.has(k)) return false; seen.add(k); return true; });
+    // Do not de-duplicate by function source: closures for different frames have
+    // identical source text but resolve against different documents.
+    return makers;
   }
 
 
@@ -714,6 +720,7 @@ export class ChromeBrowser {
   async fill({
     selector,
     text,
+    frame,
     placeholder,          // string | RegExp
     role = 'textbox',     // generic default
     attrs,
@@ -729,9 +736,9 @@ export class ChromeBrowser {
 
     const makeCandidates = () => {
       if (strategy === 'strict') {
-        return this._buildFillCandidates({ selector, scope, searchAllFrames });
+        return this._buildFillCandidates({ selector, scope, searchAllFrames, frame });
       }
-      return this._buildFillCandidates({ selector, placeholder, role, attrs, scope, searchAllFrames });
+      return this._buildFillCandidates({ selector, placeholder, role, attrs, scope, searchAllFrames, frame });
     };
 
     return this._withRetries(async () => {
@@ -778,7 +785,7 @@ export class ChromeBrowser {
    * @param {number}          [opts.delayMs=200]       // micro settle
    */
   async click({
-    selector, text, role, attrs, scope,
+    selector, text, role, attrs, scope, frame,
     searchAllFrames = true,
     strategy = 'auto',
     waitFor,   
@@ -794,8 +801,8 @@ export class ChromeBrowser {
 
     // Build your candidates the way you already do (generic/hint-driven)
     const makers = (strategy === 'strict')
-      ? this._buildClickCandidates({ selector, scope, searchAllFrames })
-      : this._buildClickCandidates({ selector, text, role, attrs, scope, searchAllFrames });
+      ? this._buildClickCandidates({ selector, scope, searchAllFrames, frame })
+      : this._buildClickCandidates({ selector, text, role, attrs, scope, searchAllFrames, frame });
 
     // choose & click (same as your generic version)
     let chosen = null;
@@ -1014,9 +1021,57 @@ export class ChromeBrowser {
     // Fallback to empty string if still nothing (keeps caller logic simple)
     if (!html) html = '';
 
+    // page.content() only serializes iframe elements, not their documents. Build a
+    // read-only clone that embeds accessible frame documents so selectors and the
+    // global output limit apply to the complete snapshot.
+    try {
+      html = await this.page.evaluate(() => {
+        const serializeDocument = (doc) => {
+          const clone = doc.documentElement.cloneNode(true);
+          const sourceFrames = Array.from(doc.querySelectorAll('iframe'));
+          const clonedFrames = Array.from(clone.querySelectorAll('iframe'));
+
+          sourceFrames.forEach((sourceFrame, index) => {
+            const clonedFrame = clonedFrames[index];
+            if (!clonedFrame) return;
+            // iframe is a raw-text element in HTML parsers. Use a temporary
+            // custom element so Cheerio parses the embedded controls as markup.
+            const serializedFrame = doc.createElement('testronaut-frame');
+            for (const attribute of Array.from(clonedFrame.attributes)) {
+              serializedFrame.setAttribute(attribute.name, attribute.value);
+            }
+            clonedFrame.replaceWith(serializedFrame);
+            const label = sourceFrame.id || sourceFrame.name || sourceFrame.getAttribute('src') || `frame-${index + 1}`;
+            serializedFrame.setAttribute('data-testronaut-frame', label);
+            try {
+              const childDocument = sourceFrame.contentDocument;
+              if (!childDocument?.documentElement) throw new Error('inaccessible');
+              serializedFrame.setAttribute('data-testronaut-frame-status', 'same-origin');
+              serializedFrame.innerHTML = serializeDocument(childDocument);
+            } catch {
+              serializedFrame.setAttribute('data-testronaut-frame-status', 'cross-origin');
+              serializedFrame.textContent = '[cross-origin frame, content not accessible]';
+            }
+          });
+
+          return clone.outerHTML;
+        };
+        return serializeDocument(document);
+      });
+    } catch {
+      // Preserve the main-document snapshot if serialization races a navigation.
+    }
+
     // --- 4) Optional DOM reduction/cleanup (your existing steps) ---
     let $ = cheerio.load(html);
 
+    // Restore the public marker shape after the HTML parser has materialized
+    // the temporary element's descendants.
+    $('testronaut-frame').each((_, element) => {
+      element.name = 'iframe';
+      element.tagName = 'iframe';
+    });
+
     if (selector) {
       let selection;
       try {
@@ -1141,12 +1196,27 @@ export class ChromeBrowser {
   }
 
   
-  async check_text({ text }) {
-    const matches = this.page.getByText(text);
-    const count = await matches.count();
-    for (let index = 0; index < count; index++) {
-      if (await matches.nth(index).isVisible().catch(() => false)) {
-        return `FOUND: ${text}`;
+  async check_text({ text, searchAllFrames = true }) {
+    const mainFrame = this.page.mainFrame?.();
+    const frames = searchAllFrames && this.page.frames
+      ? [mainFrame, ...this.page.frames().filter(frame => frame !== mainFrame)].filter(Boolean)
+      : [mainFrame || this.page];
+
+    for (const frame of frames) {
+      const matches = frame.getByText(text);
+      const count = await matches.count();
+      for (let index = 0; index < count; index++) {
+        if (!await matches.nth(index).isVisible().catch(() => false)) continue;
+        if (frame === mainFrame || frame === this.page) return `FOUND: ${text}`;
+
+        let label = frame.name?.() || '';
+        if (!label) {
+          label = await frame.frameElement?.()
+            .then(element => element.getAttribute('id'))
+            .catch(() => '') || '';
+        }
+        label ||= frame.url?.() || 'unnamed';
+        return `FOUND in frame ${label}: ${text}`;
       }
     }
     return `NOT FOUND: ${text}`;

package/tools/domControl.js

@@ -7,7 +7,7 @@
  *   normalize, and compress HTML so it’s cheaper and clearer for LLMs.
  *
  * Responsibilities:
- *   - Remove non-content tags (scripts, styles, iframes, etc.) and noisy attributes.
+ *   - Remove non-content tags (scripts, styles, etc.) and noisy attributes.
  *   - Collapse overly long lists/sections into truncated markers.
  *   - Reduce repeated div blocks to a representative sample.
  *   - Strip obfuscated/utility CSS classes that don’t help reasoning.
@@ -23,7 +23,8 @@
 
 /**
  * Remove tags and attributes that are unlikely to help LLM reasoning.
- * - Strips: script, style, meta, link, noscript, iframe, canvas, svg
+ * - Strips: script, style, meta, link, noscript, canvas, svg
+ * - Keeps iframe shells and any same-origin content injected by get_dom.
  * - Keeps only a safe whitelist of attributes on remaining elements.
  * - Removes HTML comments.
  *
@@ -31,7 +32,7 @@
  * @returns {$} same Cheerio instance for chaining
  */
 export const removeNonContentTags = async ($) => {
-  $('script, style, meta, link, noscript, iframe, canvas, svg').remove();
+  $('script, style, meta, link, noscript, canvas, svg').remove();
   
   $('*').each((_, el) => {
     const $el = $(el);
@@ -39,6 +40,7 @@ export const removeNonContentTags = async ($) => {
       'href', 'src', 'type', 'alt', 'title',
       'placeholder', 'name', 'id', 'class', 'value',
       'data-testid', 'disabled', 'role', 'data-state',
+      'data-testronaut-frame', 'data-testronaut-frame-status',
       // keep key data-* attributes that help identify rows/items without bloating too much
       'data-type', 'data-id', 'data-title', 'data-parentid', 'data-order'
     ];

package/tools/toolSchema.js

@@ -44,6 +44,7 @@ const toolsSchema = [
         properties: {
           selector: { type: 'string' },
           text: { type: 'string' },
+          frame: { type: 'string', description: 'Optional CSS selector for the containing iframe.' },
         },
         required: ['selector', 'text'],
       },
@@ -58,6 +59,7 @@ const toolsSchema = [
         type: 'object',
         properties: {
           selector: { type: 'string' },
+          frame: { type: 'string', description: 'Optional CSS selector for the containing iframe.' },
           waitFor: {
             type: 'string',
             enum: ['load', 'domcontentloaded', 'networkidle'],
@@ -108,6 +110,11 @@ const toolsSchema = [
         type: 'object',
         properties: {
           text: { type: 'string' },
+          searchAllFrames: {
+            type: 'boolean',
+            default: true,
+            description: 'Search iframe documents as well as the main document.',
+          },
         },
         required: ['text'],
       },