explorbot 0.1.29 → 0.1.31

package/src/ai/tools.ts

@@ -18,7 +18,6 @@ import { isInteractive } from './task-agent.ts';
 
 const debugLog = createDebug('explorbot:tools');
 
-export const CODECEPT_TOOLS = ['click', 'hover', 'pressKey', 'form'] as const;
 export const ASSERTION_TOOLS = ['verify'] as const;
 
 export function createCodeceptJSTools(explorer: Explorer, task: Task) {

package/src/config.ts

@@ -22,6 +22,7 @@ interface PlaywrightConfig {
   waitForAction?: number;
   waitForNavigation?: 'load' | 'domcontentloaded' | 'networkidle';
   waitForTimeout?: number;
+  spinnerSelectors?: string[];
   ignoreHTTPSErrors?: boolean;
   userAgent?: string;
   viewport?: {

package/src/experience-tracker.ts

@@ -3,12 +3,12 @@ import { basename, dirname, join } from 'node:path';
 import matter from 'gray-matter';
 import { type Tokens, marked } from 'marked';
 import type { ActionResult } from './action-result.js';
-import { isNonReusableCode } from './ai/historian/utils.ts';
 import { ConfigParser } from './config.js';
 import { KnowledgeTracker } from './knowledge-tracker.js';
 import type { WebPageState } from './state-manager.js';
 import { createDebug, tag } from './utils/logger.js';
 import { mdq } from './utils/markdown-query.js';
+import { isNonReusableCode } from './utils/step-analyzer.ts';
 import { extractStatePath } from './utils/url-matcher.js';
 
 const debugLog = createDebug('explorbot:experience');

package/src/explorbot.ts

@@ -221,7 +221,13 @@ export class ExplorBot {
       this.agents.tester = this.createAgent(({ ai, explorer }) => {
         const researcher = this.agentResearcher();
         const navigator = this.agentNavigator();
-        const tools = createAgentTools({ explorer, researcher, navigator });
+        const stateManager = explorer.getStateManager();
+        const experienceTracker = stateManager.getExperienceTracker();
+        const getState = () => {
+          const state = stateManager.getCurrentState();
+          return state ? ActionResult.fromState(state) : null;
+        };
+        const tools = createAgentTools({ explorer, researcher, navigator, experienceTracker, getState });
         return new Tester(explorer, ai, researcher, navigator, tools);
       });
 

package/src/explorer.ts

@@ -2,10 +2,10 @@ import { existsSync, mkdirSync } from 'node:fs';
 import path, { join } from 'node:path';
 // @ts-ignore
 import * as codeceptjs from 'codeceptjs';
-import dedent from 'dedent';
 import stepsListener from 'codeceptjs/lib/listener/steps';
 import storeListener from 'codeceptjs/lib/listener/store';
 import { createTest } from 'codeceptjs/lib/mocha/test';
+import dedent from 'dedent';
 import type { BrowserContextOptions } from 'playwright';
 import { ActionResult } from './action-result.ts';
 import Action from './action.js';
@@ -21,10 +21,11 @@ import { PlaywrightRecorder } from './playwright-recorder.ts';
 import { Reporter } from './reporter.ts';
 import { StateManager } from './state-manager.js';
 import { Test, TestResult } from './test-plan.ts';
+import { BrowserRecoveryError, isFatalBrowserError, isNavigationTransitionError } from './utils/browser-errors.ts';
 import { ELEMENT_EXTRACTION_CONFIG, getElementDataExtractorSource } from './utils/html.ts';
 import { createDebug, log, tag } from './utils/logger.js';
+import { waitForPageReadiness } from './utils/page-readiness.ts';
 import { WebElement } from './utils/web-element.ts';
-import { BrowserRecoveryError, isFatalBrowserError } from './utils/browser-errors.ts';
 
 declare global {
   namespace NodeJS {
@@ -314,13 +315,26 @@ class Explorer {
     try {
       return await operation();
     } catch (error) {
-      if (!this.isFatalBrowserError(error)) throw error;
+      let recoveryError = error;
+
+      if (isNavigationTransitionError(error)) {
+        tag('warning').log(`${label}: page is still navigating, waiting before retry...`);
+        await this.waitForPageReadiness();
+        try {
+          return await operation();
+        } catch (retryError) {
+          if (!isNavigationTransitionError(retryError) && !this.isFatalBrowserError(retryError)) throw retryError;
+          recoveryError = retryError;
+        }
+      }
+
+      if (!this.isFatalBrowserError(recoveryError)) throw recoveryError;
 
       tag('warning').log(`${label}: browser page is unavailable, recovering...`);
       let recovered = await this.recoverFromBrowserError();
       if (!recovered) recovered = await this.restartBrowser();
-      if (!recovered) throw new BrowserRecoveryError(label, error, false);
-      if (!(await this.waitForUsablePageDom())) throw new BrowserRecoveryError(label, error, true);
+      if (!recovered) throw new BrowserRecoveryError(label, recoveryError, false);
+      if (!(await this.waitForPageReadiness())) throw new BrowserRecoveryError(label, recoveryError, true);
 
       try {
         return await operation();
@@ -377,7 +391,7 @@ class Explorer {
         const msg = err instanceof Error ? err.message : String(err);
         if (!RECOVERABLE_NAVIGATION_ERRORS.test(msg)) throw err;
         tag('warning').log(`Navigation warning (continuing after load): ${msg.split('\n')[0]}`);
-        await this.playwrightHelper.page.waitForLoadState('domcontentloaded', { timeout: 10000 }).catch(() => {});
+        await this.waitForPageReadiness();
         await action.capturePageState();
       }
     }
@@ -488,11 +502,11 @@ class Explorer {
       if (url) {
         tag('warning').log(`Browser error detected, recovering by navigating to ${url}`);
         await this.playwrightHelper.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 10000 });
-        return this.waitForUsablePageDom();
+        return this.waitForPageReadiness();
       }
       tag('warning').log('Browser error detected, reloading page');
       await this.playwrightHelper.page.reload({ waitUntil: 'domcontentloaded', timeout: 10000 });
-      return this.waitForUsablePageDom();
+      return this.waitForPageReadiness();
     } catch (err) {
       tag('error').log(`Browser recovery failed: ${err instanceof Error ? err.message : err}`);
       return false;
@@ -532,7 +546,7 @@ class Explorer {
 
       if (url) {
         await this.playwrightHelper.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 10000 });
-        if (!(await this.waitForUsablePageDom())) return false;
+        if (!(await this.waitForPageReadiness())) return false;
       }
 
       tag('success').log('Browser restarted');
@@ -550,27 +564,14 @@ class Explorer {
     }
   }
 
-  private async waitForUsablePageDom(): Promise<boolean> {
+  private async waitForPageReadiness(): Promise<boolean> {
     const page = this.playwrightHelper?.page;
     if (!page) return false;
 
-    await page.waitForLoadState?.('domcontentloaded', { timeout: 5000 }).catch(() => {});
-    if (page.waitForFunction) {
-      const hasUsableDom = await page
-        .waitForFunction(
-          () => {
-            const body = document.body;
-            if (!body) return false;
-            return body.children.length > 0 || body.textContent?.trim().length > 0;
-          },
-          undefined,
-          { timeout: 5000 }
-        )
-        .then(() => true)
-        .catch(() => false);
-      if (!hasUsableDom) return false;
-    }
-    await page.waitForLoadState?.('networkidle', { timeout: 3000 }).catch(() => {});
+    await waitForPageReadiness(page, {
+      timeout: this.config.playwright.waitForTimeout,
+      spinnerSelectors: this.config.playwright.spinnerSelectors,
+    });
     return true;
   }
 

package/src/utils/browser-errors.ts

@@ -2,6 +2,7 @@
 // not typed exceptions. Keep those external message markers in one adapter so
 // recovery decisions are not duplicated across agents/actions.
 const FATAL_BROWSER_ERROR_MARKERS = ['Frame was detached', 'Target closed', 'Target page, context or browser has been closed', 'Execution context was destroyed', 'Protocol error', 'Session closed'];
+const NAVIGATION_TRANSITION_ERROR_MARKERS = ['most likely because of a navigation', 'navigating and changing the content'];
 
 export class BrowserRecoveryError extends Error {
   constructor(
@@ -20,6 +21,11 @@ export function isFatalBrowserError(error: unknown): boolean {
   return FATAL_BROWSER_ERROR_MARKERS.some((marker) => message.includes(marker.toLowerCase()));
 }
 
+export function isNavigationTransitionError(error: unknown): boolean {
+  const message = browserErrorMessage(error).toLowerCase();
+  return NAVIGATION_TRANSITION_ERROR_MARKERS.some((marker) => message.includes(marker.toLowerCase()));
+}
+
 export function browserErrorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }

package/src/utils/page-readiness.ts

@@ -0,0 +1,59 @@
+export async function waitForPageReadiness(page: any, options: PageReadinessOptions = {}): Promise<void> {
+  if (!page) return;
+
+  const timeout = options.timeout ?? 6000;
+  await page.waitForLoadState?.('domcontentloaded', { timeout })?.catch(() => {});
+
+  await Promise.race([waitForNetworkIdle(page, timeout), waitForVisibleSpinnersHidden(page, options.spinnerSelectors || [], timeout), sleep(timeout)]).catch(() => {});
+  await waitForPageBodyContent(page, timeout);
+}
+
+function waitForNetworkIdle(page: any, timeout: number): Promise<void> {
+  if (!page?.waitForLoadState) return Promise.resolve();
+  return page.waitForLoadState('networkidle', { timeout }).catch(() => {});
+}
+
+async function waitForVisibleSpinnersHidden(page: any, selectors: string[], timeout: number): Promise<void> {
+  if (!selectors.length) return new Promise(() => {});
+  if (!page?.locator) return new Promise(() => {});
+
+  const visibleSpinners = [];
+  for (const selector of selectors) {
+    const locator = page.locator(selector);
+    const isVisible = await locator
+      .first()
+      .isVisible({ timeout: 100 })
+      .catch(() => false);
+    if (!isVisible) continue;
+    visibleSpinners.push(locator);
+  }
+
+  if (visibleSpinners.length === 0) return new Promise(() => {});
+
+  return Promise.all(visibleSpinners.map((locator) => locator.waitFor({ state: 'hidden', timeout }).catch(() => {}))).then(() => {});
+}
+
+function waitForPageBodyContent(page: any, timeout: number): Promise<void> {
+  if (!page?.waitForFunction) return Promise.resolve();
+
+  return page
+    .waitForFunction(
+      () => {
+        const body = document.body;
+        if (!body) return false;
+        return body.children.length > 0 || body.textContent?.trim().length > 0;
+      },
+      undefined,
+      { timeout }
+    )
+    .catch(() => {});
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+interface PageReadinessOptions {
+  timeout?: number;
+  spinnerSelectors?: string[];
+}

package/src/utils/step-analyzer.ts

@@ -0,0 +1,73 @@
+import type { SessionStep } from '../experience-tracker.ts';
+import type { StepData } from '../test-plan.ts';
+import { isDynamicId } from './xpath.ts';
+
+export const CODECEPT_TOOLS = ['click', 'hover', 'pressKey', 'form'] as const;
+export type CodeceptToolName = (typeof CODECEPT_TOOLS)[number];
+
+const CODECEPT_FORM_COMMANDS: readonly string[] = ['I.fillField', 'I.type', 'I.selectOption', 'I.attachFile', 'I.checkOption', 'I.uncheckOption'];
+
+export function isCodeceptToolName(toolName: string): toolName is CodeceptToolName {
+  return CODECEPT_TOOLS.includes(toolName as CodeceptToolName);
+}
+
+export function getCodeceptToolName(commandName: string): CodeceptToolName | null {
+  const toolName = CODECEPT_TOOLS.find((name) => commandName === `I.${name}`);
+  if (toolName) return toolName;
+  if (CODECEPT_FORM_COMMANDS.includes(commandName)) return 'form';
+  return null;
+}
+
+export function getCodeceptToolNameFromCode(code: string): CodeceptToolName | null {
+  const parenIndex = code.trim().indexOf('(');
+  if (parenIndex < 1) return null;
+  return getCodeceptToolName(code.trim().slice(0, parenIndex));
+}
+
+export function stripComments(code: string): string {
+  return code
+    .split('\n')
+    .filter((line) => {
+      const trimmed = line.trim();
+      return trimmed && !trimmed.startsWith('//') && !trimmed.startsWith('/*') && !trimmed.startsWith('*');
+    })
+    .join('\n');
+}
+
+export function isNonReusableCode(code: string): boolean {
+  if (/\bI\.clickXY\s*\(/.test(code)) return true;
+
+  for (const m of code.matchAll(/#([A-Za-z_][\w-]*)/g)) {
+    if (isDynamicId(m[1])) return true;
+  }
+
+  return false;
+}
+
+export function toReusableSessionStep(step: StepData): SessionStep | null {
+  if (step.status !== 'passed') return null;
+  const code = stripComments(step.text);
+  if (!code || isNonReusableCode(code)) return null;
+  const toolName = getCodeceptToolNameFromCode(code);
+  if (!toolName) return null;
+
+  return {
+    message: step.text,
+    status: 'passed',
+    tool: toolName,
+    code,
+  };
+}
+
+export function mergeUniqueStepsByCode(primary: SessionStep[], secondary: SessionStep[]): SessionStep[] {
+  const merged: SessionStep[] = [];
+  const seen = new Set<string>();
+  for (const step of [...primary, ...secondary]) {
+    const identity = stripComments(step.code || '').trim();
+    if (!identity) continue;
+    if (seen.has(identity)) continue;
+    seen.add(identity);
+    merged.push(step);
+  }
+  return merged;
+}