explorbot 0.1.10 → 0.1.12

package/dist/src/utils/strings.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 export function truncateJson(input) {
     if (!input)
         return '';
@@ -11,3 +12,17 @@ export function sanitizeFilename(name) {
         .replace(/^_+|_+$/g, '')
         .slice(0, 50);
 }
+export function safeFilename(name, ext = '', maxBytes = 240) {
+    const sanitized = name.replace(/[^a-zA-Z0-9]/g, '_').toLowerCase();
+    const extBytes = Buffer.byteLength(ext, 'utf8');
+    const budget = maxBytes - extBytes;
+    if (Buffer.byteLength(sanitized, 'utf8') <= budget)
+        return sanitized + ext;
+    const hash = createHash('sha1').update(name).digest('hex').slice(0, 8);
+    const suffix = `_${hash}`;
+    let truncated = sanitized;
+    while (Buffer.byteLength(truncated + suffix, 'utf8') > budget && truncated.length > 0) {
+        truncated = truncated.slice(0, -1);
+    }
+    return truncated + suffix + ext;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -83,7 +83,7 @@
     "axe-core": "^4.11.1",
     "bash-tool": "^1.3.15",
     "cli-highlight": "^2.1.11",
-    "codeceptjs": "4.0.0-rc.11",
+    "codeceptjs": "4.0.0-rc.16",
     "commander": "^14.0.1",
     "debug": "^4.4.3",
     "dedent": "^1.6.0",
@@ -104,7 +104,7 @@
     "micromatch": "^4.0.8",
     "ora-classic": "^5.4.2",
     "parse5": "^8.0.0",
-    "playwright": "^1.40.0",
+    "playwright": "^1.59.0",
     "react": "^19.1.1",
     "strip-ansi": "^7.1.2",
     "turndown": "^7.2.1",

package/rules/navigator/output.md

@@ -13,6 +13,10 @@ In <explanation> write only one line without heading or bullet list or any other
 Check previous solutions, if there is already successful solution, use it!
 CodeceptJS code must start with "I."
 All lines of code must be CodeceptJS code and start with "I."
+
+Do not mix form filling with navigation in the same code block.
+If the code block fills a form and clicks a submit/confirm control, stop there — do not append I.amOnPage afterwards. Submitting the form already triggers navigation on the server side, and a follow-up I.amOnPage cancels that in-flight navigation and discards the just-submitted state (session, cookies, redirect target).
+If the action does not cause navigation on its own and a separate page visit is required to reach the target, put I.amOnPage in its own code block as a distinct step, not glued onto the form submission block.
 </rules>
 
 <output>
@@ -42,6 +46,11 @@ Use only locators from HTML PAGE that was passed in <page> context.
 <example_output>
 Trying to fill the form on the page
 
+```js
+  I.fillField({ "role": "textbox", "text": "Name" }, 'Value');
+  I.click({ "role": "button", "text": "Submit" });
+```
+
 ```js
   I.fillField('Name', 'Value');
   I.click('Submit');

package/rules/navigator/verification-actions.md

@@ -113,6 +113,8 @@ For input field values, ALWAYS use I.seeInField() — never check value via CSS
 Prefer text locators (label, name, placeholder) for form fields: I.seeInField('Search', 'value') over I.seeInField('input[name="search"]', 'value').
 Only use locators that exist in the provided HTML or ARIA snapshot.
 Verify exact conditions, not approximate matches.
+NEVER use `:has-text(...)` inside a seeElement/dontSeeElement locator. Checking text inside an element is the job of I.see(text, context) — the `:has-text()` form duplicates that capability with a fragile selector.
+NEVER emit two assertions that check the same fact with different shapes. `I.see(text, locator)` and `I.seeElement("<locator>:has-text('text')")` verify the same thing — pick one (prefer I.see). One claim, one assertion.
 </verification_rules>
 
 [DO NEVER USE OTHER CODECEPTJS COMMANDS THAN PROPOSED HERE]

package/src/action-result.ts

@@ -611,7 +611,7 @@ export class ActionResult implements ActionResultData {
         }
       }
       if (processedParts.length > 0) {
-        pageDiff.htmlParts = processedParts;
+        pageDiff.htmlParts = collapseHtmlParts(processedParts);
       }
     }
 
@@ -629,6 +629,31 @@ export class ActionResult implements ActionResultData {
   }
 }
 
+const HTML_PARTS_TOTAL_BUDGET = 8000;
+const HTML_PARTS_COUNT_LIMIT = 8;
+const HTML_PART_SUBTREE_BUDGET = 2000;
+
+function collapseHtmlParts(parts: HtmlDiffPart[]): HtmlDiffPart[] {
+  const total = parts.reduce((sum, p) => sum + p.subtree.length, 0);
+  const fullPageReRender = total > HTML_PARTS_TOTAL_BUDGET || parts.length > HTML_PARTS_COUNT_LIMIT;
+
+  if (fullPageReRender) {
+    return parts.map((part) => ({
+      ...part,
+      subtree: `<html><head></head><body>...collapsed (${part.subtree.length} chars, ${part.added.length} added, ${part.removed.length} removed)...</body></html>`,
+    }));
+  }
+
+  return parts.map((part) => {
+    if (part.subtree.length <= HTML_PART_SUBTREE_BUDGET) return part;
+    const head = part.subtree.slice(0, HTML_PART_SUBTREE_BUDGET);
+    return {
+      ...part,
+      subtree: `${head}...<!-- truncated ${part.subtree.length - HTML_PART_SUBTREE_BUDGET} chars -->`,
+    };
+  });
+}
+
 export class Diff {
   private _htmlDiffResult: HtmlDiffResult | null = null;
   private _ariaDiffResult: string | null = null;

package/src/action.ts

@@ -16,10 +16,12 @@ import { ConfigParser, outputPath } from './config.js';
 import type { ExplorbotConfig } from './config.js';
 import type { UserResolveFunction } from './explorbot.ts';
 import { Observability } from './observability.ts';
+import type { PlaywrightRecorder } from './playwright-recorder.ts';
 import type { StateManager } from './state-manager.js';
 import { extractCodeBlocks } from './utils/code-extractor.js';
 import { htmlCombinedSnapshot, minifyHtml } from './utils/html.js';
 import { createDebug, log, setStepSpanParent, tag } from './utils/logger.js';
+import { safeFilename } from './utils/strings.ts';
 import { throttle } from './utils/throttle.ts';
 
 const debugLog = createDebug('explorbot:action');
@@ -36,12 +38,16 @@ class Action {
   private expectation: string | null = null;
   public lastError: Error | null = null;
   public playwrightHelper: any;
+  public playwrightGroupId: string | null = null;
+  public assertionSteps: Array<{ name: string; args: any[] }> = [];
+  private recorder?: PlaywrightRecorder;
 
-  constructor(actor: CodeceptJS.I, stateManager: StateManager) {
+  constructor(actor: CodeceptJS.I, stateManager: StateManager, recorder?: PlaywrightRecorder) {
     this.actor = actor;
     this.stateManager = stateManager;
     this.config = ConfigParser.getInstance().getConfig();
     this.playwrightHelper = container.helpers('Playwright');
+    this.recorder = recorder;
   }
 
   async caputrePageWithScreenshot(): Promise<ActionResult> {
@@ -71,13 +77,20 @@ class Action {
       const timestamp = Date.now();
       const page = this.playwrightHelper.page;
       const frame = this.playwrightHelper.frame;
-      const [html, title, browserLogs] = await Promise.all([(this.actor as any).grabSource(), (this.actor as any).grabTitle(), this.captureBrowserLogs()]);
+      await page?.waitForLoadState('domcontentloaded', { timeout: 10000 })?.catch(() => {});
+      const grabAll = () => Promise.all([(this.actor as any).grabSource(), (this.actor as any).grabTitle(), this.captureBrowserLogs()]);
+      const [html, title, browserLogs] = await grabAll().catch(async (err: Error) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (!/navigating and changing the content/i.test(msg)) throw err;
+        await page?.waitForLoadState('domcontentloaded', { timeout: 10000 })?.catch(() => {});
+        return grabAll();
+      });
       const url = page?.url() || (await (this.actor as any).grabCurrentUrl?.());
 
       let screenshotFile: string | undefined = undefined;
 
       if (includeScreenshot) {
-        const filename = `${stateHash}_${timestamp}.png`;
+        const filename = safeFilename(`${stateHash}_${timestamp}`, '.png');
         screenshotFile = await (this.actor as any)
           .saveScreenshot(filename)
           .then(() => filename)
@@ -90,13 +103,13 @@ class Action {
       // Save HTML to file
       const statesDir = outputPath('states');
       fs.mkdirSync(statesDir, { recursive: true });
-      const htmlFile = `${stateHash}_${timestamp}.html`;
+      const htmlFile = safeFilename(`${stateHash}_${timestamp}`, '.html');
       const htmlPath = join(statesDir, htmlFile);
       fs.writeFileSync(htmlPath, html, 'utf8');
 
       debugLog('Captured page state');
       // Save logs to file
-      const logFile = `${stateHash}_${timestamp}.log`;
+      const logFile = safeFilename(`${stateHash}_${timestamp}`, '.log');
       const logPath = join(statesDir, logFile);
       const formattedLogs = browserLogs.map((log: any) => {
         const logTimestamp = new Date().toISOString();
@@ -122,7 +135,7 @@ class Action {
       }
 
       if (ariaSnapshot) {
-        const ariaFileName = `${stateHash}_${timestamp}.aria.yaml`;
+        const ariaFileName = safeFilename(`${stateHash}_${timestamp}`, '.aria.yaml');
         const ariaPath = join(statesDir, ariaFileName);
         fs.writeFileSync(ariaPath, ariaSnapshot, 'utf8');
         ariaSnapshotFile = ariaFileName;
@@ -218,7 +231,10 @@ class Action {
     let codeString = code.replace(/^\(I\) => /, '').trim();
 
     const executedSteps: string[] = [];
-    registerStepLogger(executedSteps);
+    const assertionSteps: Array<{ name: string; args: any[] }> = [];
+    const stepListener = attachStepLogger(executedSteps, assertionSteps);
+    const groupId = this.recorder ? await this.recorder.beginAction(codeString) : null;
+    this.playwrightGroupId = groupId;
     const activeSpan = Observability.getSpan();
     const tracer = trace.getTracer('ai');
     const stepSpan = activeSpan ? tracer.startSpan('codeceptjs.step', undefined, trace.setSpan(context.active(), activeSpan)) : null;
@@ -253,6 +269,7 @@ class Action {
       this.stateManager.updateState(pageState, codeString);
 
       this.actionResult = pageState;
+      this.assertionSteps = assertionSteps;
     } catch (err) {
       debugLog('Action error', errorToString(err));
       error = err as Error;
@@ -260,9 +277,11 @@ class Action {
         await recorder.reset();
         await recorder.start();
       }
+      this.assertionSteps = [];
       throw err;
     } finally {
-      unregisterStepLogger();
+      if (groupId) await this.recorder!.endAction();
+      detachStepLogger(stepListener);
       if (stepSpan) {
         stepSpan.end();
       }
@@ -407,41 +426,30 @@ function sleep(ms: number) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-let stepLoggerRegistered = false;
-let stepLoggerTarget: string[] | null = null;
+const ASSERTION_STEP_NAMES = new Set(['see', 'dontSee', 'seeElement', 'dontSeeElement', 'seeInField', 'dontSeeInField', 'seeInCurrentUrl', 'dontSeeInCurrentUrl']);
 
-const stepLogger = (step: any, error?: any) => {
-  if (!step?.toCode) {
-    return;
-  }
-  if (step.name?.startsWith('grab')) return;
-  const stepCode = step.toCode();
-  if (stepLoggerTarget) {
-    stepLoggerTarget.push(stepCode);
-  }
-  if (error) {
-    tag('step').log(step, error);
-    return;
-  }
-  tag('step').log(step);
-};
+type StepListener = (step: any, error?: any) => void;
 
-const registerStepLogger = (target: string[]) => {
-  stepLoggerTarget = target;
-  if (stepLoggerRegistered) {
-    return;
-  }
-  stepLoggerRegistered = true;
-  codeceptjs.event.dispatcher.on(codeceptjs.event.step.passed, stepLogger);
-  codeceptjs.event.dispatcher.on(codeceptjs.event.step.failed, stepLogger);
+const attachStepLogger = (target: string[], assertionsTarget?: Array<{ name: string; args: any[] }>): StepListener => {
+  const listener: StepListener = (step, error) => {
+    if (!step?.toCode) return;
+    if (step.name?.startsWith('grab')) return;
+    target.push(step.toCode());
+    if (assertionsTarget && ASSERTION_STEP_NAMES.has(step.name)) {
+      assertionsTarget.push({ name: step.name, args: step.args || [] });
+    }
+    if (error) {
+      tag('step').log(step, error);
+      return;
+    }
+    tag('step').log(step);
+  };
+  codeceptjs.event.dispatcher.on(codeceptjs.event.step.passed, listener);
+  codeceptjs.event.dispatcher.on(codeceptjs.event.step.failed, listener);
+  return listener;
 };
 
-const unregisterStepLogger = () => {
-  stepLoggerTarget = null;
-  if (!stepLoggerRegistered) {
-    return;
-  }
-  stepLoggerRegistered = false;
-  codeceptjs.event.dispatcher.off(codeceptjs.event.step.passed, stepLogger);
-  codeceptjs.event.dispatcher.off(codeceptjs.event.step.failed, stepLogger);
+const detachStepLogger = (listener: StepListener) => {
+  codeceptjs.event.dispatcher.off(codeceptjs.event.step.passed, listener);
+  codeceptjs.event.dispatcher.off(codeceptjs.event.step.failed, listener);
 };

package/src/ai/bosun.ts

@@ -9,9 +9,11 @@ import type { KnowledgeTracker } from '../knowledge-tracker.ts';
 import { Observability } from '../observability.ts';
 import { Plan, Task, Test, TestResult } from '../test-plan.ts';
 import { diffAriaSnapshots } from '../utils/aria.ts';
+import { getCliName } from '../utils/cli-name.ts';
 import { HooksRunner } from '../utils/hooks-runner.ts';
 import { createDebug, tag } from '../utils/logger.ts';
 import { loop, pause } from '../utils/loop.ts';
+import { type NextStepSection, printNextSteps } from '../utils/next-steps.ts';
 import type { Agent } from './agent.ts';
 import type { Conversation } from './conversation.ts';
 import type { Navigator } from './navigator.ts';
@@ -497,7 +499,15 @@ export class Bosun extends TaskAgent implements Agent {
     const content = this.generateKnowledgeContent(state, successfulInteractions);
     const result = knowledgeTracker.addKnowledge(knowledgePath, content);
 
-    tag('success').log(`Knowledge saved to: ${result.filePath}`);
+    const cli = getCliName();
+    const sections: NextStepSection[] = [
+      {
+        label: 'Knowledge',
+        path: result.filePath,
+        commands: [{ label: 'View matches', command: `${cli} knows ${knowledgePath}` }],
+      },
+    ];
+    printNextSteps(sections);
   }
 
   private generateKnowledgeContent(state: any, interactions: InteractionResult[]): string {

package/src/ai/conversation.ts

@@ -11,6 +11,9 @@ export function toolExecutionLabel(input: Record<string, any> | undefined): stri
   return input?.explanation || input?.assertion || input?.reason || input?.request || '';
 }
 
+const AUTO_COMPACT_ARIA_CHANGES_CUTOFF = 500;
+const AUTO_COMPACT_TARGETED_HTML_CUTOFF = 500;
+
 export class Conversation {
   id: string;
   messages: ModelMessage[];
@@ -132,6 +135,40 @@ export class Conversation {
     this.autoTrimRules.set(tagName, maxLength);
   }
 
+  compactToolResults(keepLastN: number): void {
+    const toolMessageIndexes: number[] = [];
+    for (let i = 0; i < this.messages.length; i++) {
+      if (this.messages[i].role === 'tool') toolMessageIndexes.push(i);
+    }
+    const compactUpTo = toolMessageIndexes.length - Math.max(0, keepLastN);
+    for (let k = 0; k < compactUpTo; k++) {
+      const message = this.messages[toolMessageIndexes[k]];
+      if (!Array.isArray(message.content)) continue;
+      for (const part of message.content) {
+        if (part.type !== 'tool-result') continue;
+        const rawOutput = part.output as Record<string, any> | undefined;
+        if (!rawOutput || rawOutput.type !== 'json' || !rawOutput.value || typeof rawOutput.value !== 'object') continue;
+        const value = rawOutput.value as Record<string, any>;
+        if (value.pageDiff && typeof value.pageDiff === 'object') {
+          const pageDiff = value.pageDiff as Record<string, any>;
+          if (Array.isArray(pageDiff.htmlParts)) {
+            pageDiff.htmlParts = undefined;
+            pageDiff.compacted = true;
+          }
+          if (typeof pageDiff.ariaChanges === 'string' && pageDiff.ariaChanges.length > AUTO_COMPACT_ARIA_CHANGES_CUTOFF) {
+            pageDiff.ariaChanges = `${pageDiff.ariaChanges.slice(0, AUTO_COMPACT_ARIA_CHANGES_CUTOFF)}...`;
+          }
+          if (typeof pageDiff.iframes === 'string') {
+            pageDiff.iframes = undefined;
+          }
+        }
+        if (typeof value.targetedHtml === 'string' && value.targetedHtml.length > AUTO_COMPACT_TARGETED_HTML_CUTOFF) {
+          value.targetedHtml = `${value.targetedHtml.slice(0, AUTO_COMPACT_TARGETED_HTML_CUTOFF)}...`;
+        }
+      }
+    }
+  }
+
   hasTag(tagName: string, lastN?: number): boolean {
     const escapedTag = tagName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     const regex = new RegExp(`<${escapedTag}>`, 'g');

package/src/ai/historian/codeceptjs.ts

@@ -0,0 +1,130 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ActionResult } from '../../action-result.ts';
+import { ConfigParser } from '../../config.ts';
+import { KnowledgeTracker } from '../../knowledge-tracker.ts';
+import type { Plan } from '../../test-plan.ts';
+import { tag } from '../../utils/logger.ts';
+import { relativeToCwd } from '../../utils/next-steps.ts';
+import { safeFilename } from '../../utils/strings.ts';
+import type { Conversation } from '../conversation.ts';
+import { ASSERTION_TOOLS, CODECEPT_TOOLS } from '../tools.ts';
+import type { Constructor } from './mixin.ts';
+import { escapeString, getExecutionLabel, isNonReusableCode, stripComments } from './utils.ts';
+
+export interface CodeceptJSMethods {
+  toCode(conversation: Conversation, scenario: string): string;
+  saveCodeceptPlanToFile(plan: Plan): string;
+}
+
+export function WithCodeceptJS<T extends Constructor>(Base: T) {
+  return class extends Base {
+    declare savedFiles: Set<string>;
+
+    toCode(conversation: Conversation, scenario: string): string {
+      const toolExecutions = conversation.getToolExecutions();
+      const TRACKABLE_TOOLS = [...CODECEPT_TOOLS, ...ASSERTION_TOOLS];
+      const successfulSteps = toolExecutions.filter((exec) => exec.wasSuccessful && TRACKABLE_TOOLS.includes(exec.toolName as any) && exec.output?.code);
+
+      if (successfulSteps.length === 0) {
+        return '';
+      }
+
+      const lines: string[] = [];
+      lines.push(`Scenario('${escapeString(scenario)}', ({ I }) => {`);
+
+      for (const exec of successfulSteps) {
+        if (isNonReusableCode(exec.output.code)) continue;
+        const explanation = getExecutionLabel(exec);
+        if (explanation) {
+          lines.push('');
+          lines.push(`  Section('${escapeString(explanation)}');`);
+        }
+        const code = stripComments(exec.output.code);
+        const codeLines = code.includes('\n') ? code.split('\n') : code.split('; ');
+        for (const codeLine of codeLines) {
+          const trimmed = codeLine.trim();
+          if (trimmed) {
+            lines.push(`  ${trimmed}`);
+          }
+        }
+      }
+
+      lines.push('});');
+      return lines.join('\n');
+    }
+
+    saveCodeceptPlanToFile(plan: Plan): string {
+      const lines: string[] = [];
+
+      lines.push(`import step, { Section } from 'codeceptjs/steps';`);
+      lines.push('');
+      lines.push(`Feature('${escapeString(plan.title)}')`);
+      lines.push('');
+
+      const startUrl = plan.url || plan.tests[0]?.startUrl;
+      if (startUrl) {
+        lines.push('Before(({ I }) => {');
+        lines.push(`  I.amOnPage('${escapeString(startUrl)}');`);
+        lines.push(...this.getKnowledgeLines(startUrl));
+        lines.push('});');
+        lines.push('');
+      }
+
+      for (const test of plan.tests) {
+        if (test.generatedCode) {
+          if (test.isSuccessful) {
+            lines.push(test.generatedCode);
+          } else {
+            lines.push(`// FAILED: ${test.scenario}`);
+            lines.push(test.generatedCode.replace(/Scenario\(/, 'Scenario.skip('));
+          }
+          lines.push('');
+          continue;
+        }
+
+        lines.push(`Scenario.todo('${escapeString(test.scenario)}', ({ I }) => {`);
+        if (test.plannedSteps.length > 0) {
+          for (const step of test.plannedSteps) {
+            lines.push(`  // ${step}`);
+          }
+        } else {
+          lines.push(`  // ${test.scenario}`);
+        }
+        lines.push('});');
+        lines.push('');
+      }
+
+      const testsDir = ConfigParser.getInstance().getTestsDir();
+      mkdirSync(testsDir, { recursive: true });
+
+      const filePath = join(testsDir, safeFilename(plan.title, '.js'));
+      writeFileSync(filePath, lines.join('\n'));
+      this.savedFiles.add(filePath);
+
+      tag('substep').log(`Saved plan tests to: ${relativeToCwd(filePath)}`);
+      return filePath;
+    }
+
+    private getKnowledgeLines(url: string, indent = '  '): string[] {
+      const knowledgeTracker = new KnowledgeTracker();
+      const state = new ActionResult({ url });
+      const { wait, waitForElement, code } = knowledgeTracker.getStateParameters(state, ['wait', 'waitForElement', 'code']);
+
+      const lines: string[] = [];
+      if (wait !== undefined) {
+        lines.push(`${indent}I.wait(${wait});`);
+      }
+      if (waitForElement) {
+        lines.push(`${indent}I.waitForElement(${JSON.stringify(waitForElement)});`);
+      }
+      if (code) {
+        for (const codeLine of code.split('\n')) {
+          const trimmed = codeLine.trim();
+          if (trimmed) lines.push(`${indent}${trimmed}`);
+        }
+      }
+      return lines;
+    }
+  };
+}