explorbot 0.1.27 → 0.1.28

package/src/explorer.ts

@@ -2,13 +2,14 @@ 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 type { BrowserContextOptions } from 'playwright';
 import { ActionResult } from './action-result.ts';
 import Action from './action.js';
 import { AIProvider } from './ai/provider.js';
-import type { BrowserContextOptions } from 'playwright';
 import { visuallyAnnotateContainers } from './ai/researcher/coordinates.ts';
 import { RequestStore } from './api/request-store.ts';
 import { XhrCapture } from './api/xhr-capture.ts';
@@ -19,10 +20,11 @@ import { KnowledgeTracker } from './knowledge-tracker.js';
 import { PlaywrightRecorder } from './playwright-recorder.ts';
 import { Reporter } from './reporter.ts';
 import { StateManager } from './state-manager.js';
-import { Test } from './test-plan.ts';
+import { Test, TestResult } from './test-plan.ts';
 import { ELEMENT_EXTRACTION_CONFIG, getElementDataExtractorSource } from './utils/html.ts';
 import { createDebug, log, tag } from './utils/logger.js';
 import { WebElement } from './utils/web-element.ts';
+import { BrowserRecoveryError, isFatalBrowserError } from './utils/browser-errors.ts';
 
 declare global {
   namespace NodeJS {
@@ -39,7 +41,6 @@ declare namespace CodeceptJS {
 }
 
 const debugLog = createDebug('explorbot:explorer');
-const FATAL_BROWSER_ERRORS = /Frame was detached|Target closed|Execution context was destroyed|Protocol error|Session closed/i;
 const RECOVERABLE_NAVIGATION_ERRORS = /net::ERR_ABORTED|page\.screenshot.*Timeout|waiting for fonts to load/i;
 
 interface TabInfo {
@@ -47,6 +48,12 @@ interface TabInfo {
   title: string;
 }
 
+interface BrowserExecutionErrorResult {
+  action: 'continue' | 'stop';
+  message: string;
+  recovered?: boolean;
+}
+
 class Explorer {
   private aiProvider: AIProvider;
   playwrightHelper: any;
@@ -64,6 +71,10 @@ class Explorer {
   private xhrCapture: XhrCapture | null = null;
   private requestStore: RequestStore | null = null;
   private playwrightRecorder: PlaywrightRecorder = new PlaywrightRecorder();
+  private observedTestPages = new Set<any>();
+  private testPageErrorHandler: ((error: Error) => void) | null = null;
+  private testConsoleHandler: ((message: any) => void) | null = null;
+  private testDialogHandler: ((dialog: any) => void) | null = null;
 
   constructor(config: ExplorbotConfig, aiProvider: AIProvider, options?: { show?: boolean; headless?: boolean; incognito?: boolean; session?: string }) {
     this.config = config;
@@ -199,12 +210,14 @@ class Explorer {
     }
   }
 
-  private setupXhrCapture(): void {
+  private setupXhrCapture(reuseRequestStore = false): void {
     const configParser = ConfigParser.getInstance();
     const outputDir = configParser.getOutputDir();
-    this.requestStore = new RequestStore(outputDir);
+    if (!reuseRequestStore || !this.requestStore) {
+      this.requestStore = new RequestStore(outputDir);
+    }
     const baseUrl = this.config.playwright.url;
-    this.xhrCapture = new XhrCapture(this.requestStore, baseUrl);
+    this.xhrCapture = new XhrCapture(this.requestStore!, baseUrl);
     this.xhrCapture.attach(this.playwrightHelper.page);
   }
 
@@ -239,18 +252,7 @@ class Explorer {
     }
     await this.connectOrLaunchBrowser();
     const hasSession = this.options?.session && existsSync(this.options.session);
-    const helperOptions = this.playwrightHelper.options || {};
-    // CodeceptJS skips _createContextPage when sessions/storageState are involved, so we
-    // build contextOptions ourselves. Most keys share a name with Playwright's
-    // BrowserContextOptions and are copied as-is; `emulate` must be flattened, `basicAuth`
-    // renamed to `httpCredentials`, and `storageState` comes from the --session flag.
-    const contextOptions: BrowserContextOptions = {
-      ...helperOptions,
-    };
-    if (helperOptions.emulate) Object.assign(contextOptions, helperOptions.emulate);
-    if (helperOptions.basicAuth) contextOptions.httpCredentials = helperOptions.basicAuth;
-    if (hasSession) contextOptions.storageState = this.options!.session;
-    await this.playwrightHelper._createContextPage(contextOptions);
+    await this.playwrightHelper._createContextPage(this.createBrowserContextOptions());
     await this.playwrightRecorder.start(this.playwrightHelper.browserContext);
     this.setupXhrCapture();
     if (hasSession) {
@@ -287,15 +289,75 @@ class Explorer {
     await this.playwrightHelper._startBrowser();
   }
 
+  private createBrowserContextOptions(): BrowserContextOptions {
+    const helperOptions = this.playwrightHelper.options || {};
+    const contextOptions: BrowserContextOptions = {
+      ...helperOptions,
+    };
+
+    if (helperOptions.emulate) Object.assign(contextOptions, helperOptions.emulate);
+    if (helperOptions.basicAuth) contextOptions.httpCredentials = helperOptions.basicAuth;
+    if (this.options?.session && existsSync(this.options.session)) contextOptions.storageState = this.options.session;
+
+    return contextOptions;
+  }
+
   createAction() {
     return new Action(this.actor, this.stateManager, this.playwrightRecorder);
   }
 
+  async runWithBrowserRecovery<T>(label: string, operation: () => Promise<T>): Promise<T> {
+    if (!(await this.ensurePageAvailable())) {
+      throw new Error(`Browser page is unavailable before ${label}`);
+    }
+
+    try {
+      return await operation();
+    } catch (error) {
+      if (!this.isFatalBrowserError(error)) throw error;
+
+      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);
+
+      try {
+        return await operation();
+      } catch (retryError) {
+        if (this.isFatalBrowserError(retryError)) {
+          throw new BrowserRecoveryError(label, retryError, true);
+        }
+        throw retryError;
+      }
+    }
+  }
+
+  async capturePageState(opts: { includeScreenshot?: boolean } = {}): Promise<ActionResult> {
+    return this.runWithBrowserRecovery('capturePageState', () => this.createAction().capturePageState(opts));
+  }
+
+  async capturePageWithScreenshot(): Promise<ActionResult> {
+    return this.capturePageState({ includeScreenshot: true });
+  }
+
+  async executeAction(code: string): Promise<Action> {
+    return this.runWithBrowserRecovery('executeAction', () => this.createAction().execute(code));
+  }
+
+  async attemptAction(code: string, originalMessage?: string, experience = true): Promise<boolean> {
+    return this.runWithBrowserRecovery('attemptAction', () => this.createAction().attempt(code, originalMessage, experience));
+  }
+
   getPlaywrightRecorder(): PlaywrightRecorder {
     return this.playwrightRecorder;
   }
 
   async visit(url: string) {
+    return this.runWithBrowserRecovery('visit', () => this.visitOnce(url));
+  }
+
+  private async visitOnce(url: string) {
     await this.closeOtherTabs();
 
     const serializedUrl = JSON.stringify(url);
@@ -338,12 +400,14 @@ class Explorer {
   }
 
   async annotateElements(): Promise<WebElement[]> {
-    const { elements } = await annotatePageElements(this.playwrightHelper.page);
-    return elements;
+    return this.runWithBrowserRecovery('annotateElements', async () => {
+      const { elements } = await annotatePageElements(this.playwrightHelper.page);
+      return elements;
+    });
   }
 
   async visuallyAnnotateElements(opts?: { containers?: Array<{ css: string; label: string }> }): Promise<number> {
-    return visuallyAnnotateContainers(this.playwrightHelper.page, opts?.containers || []);
+    return this.runWithBrowserRecovery('visuallyAnnotateElements', () => visuallyAnnotateContainers(this.playwrightHelper.page, opts?.containers || []));
   }
 
   async getEidxInContainer(containerCss: string | null): Promise<string[]> {
@@ -386,28 +450,99 @@ class Explorer {
     await this.playwrightHelper.page.reload();
   }
 
+  private resolveBrowserUrl(url?: string): string | null {
+    if (!url) return null;
+    try {
+      return new URL(url).toString();
+    } catch {}
+
+    const baseUrl = this.config.playwright?.url || this.config.web?.url;
+    if (!baseUrl) return null;
+
+    try {
+      return new URL(url, baseUrl).toString();
+    } catch {
+      return null;
+    }
+  }
+
   isFatalBrowserError(error: unknown): boolean {
-    const msg = error instanceof Error ? error.message : String(error);
-    return FATAL_BROWSER_ERRORS.test(msg);
+    return isFatalBrowserError(error);
   }
 
   async recoverFromBrowserError(): Promise<boolean> {
     try {
-      const url = this.stateManager.getCurrentState()?.url;
+      if (!this.playwrightHelper?.page || this.playwrightHelper.page.isClosed?.()) {
+        const context = this.playwrightHelper?.browserContext;
+        if (!context) return await this.restartBrowser();
+        const page = await context.newPage();
+        await page.bringToFront();
+        await this.playwrightHelper._setPage(page);
+        this.bindFrameNavigated(page);
+        if (this.xhrCapture) {
+          this.xhrCapture.attach(this.playwrightHelper.page);
+        }
+      }
+
+      const url = this.resolveBrowserUrl(this.stateManager.getCurrentState()?.url);
       if (url) {
         tag('warning').log(`Browser error detected, recovering by navigating to ${url}`);
         await this.playwrightHelper.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 10000 });
-        return true;
+        return this.waitForUsablePageDom();
       }
       tag('warning').log('Browser error detected, reloading page');
       await this.playwrightHelper.page.reload({ waitUntil: 'domcontentloaded', timeout: 10000 });
-      return true;
+      return this.waitForUsablePageDom();
     } catch (err) {
       tag('error').log(`Browser recovery failed: ${err instanceof Error ? err.message : err}`);
       return false;
     }
   }
 
+  async restartBrowser(): Promise<boolean> {
+    if (!this.playwrightHelper) return false;
+
+    const url = this.resolveBrowserUrl(this.stateManager.getCurrentState()?.url);
+
+    try {
+      if (this.xhrCapture && this.playwrightHelper.page) {
+        this.xhrCapture.detach(this.playwrightHelper.page);
+      }
+
+      await this.playwrightRecorder.stop();
+
+      if (this.playwrightHelper.browserContext) {
+        await this.playwrightHelper.browserContext.close().catch((err: unknown) => {
+          debugLog('Failed to close browser context before restart:', err);
+        });
+        this.playwrightHelper.browserContext = null;
+      }
+
+      if (!this.isSharedBrowser) {
+        await this.playwrightHelper._stopBrowser().catch((err: unknown) => {
+          debugLog('Failed to stop browser before restart:', err);
+        });
+      }
+
+      await this.connectOrLaunchBrowser();
+      await this.playwrightHelper._createContextPage(this.createBrowserContextOptions());
+      await this.playwrightRecorder.start(this.playwrightHelper.browserContext);
+      this.setupXhrCapture(true);
+      this.listenToStateChanged();
+
+      if (url) {
+        await this.playwrightHelper.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 10000 });
+        if (!(await this.waitForUsablePageDom())) return false;
+      }
+
+      tag('success').log('Browser restarted');
+      return true;
+    } catch (err) {
+      tag('error').log(`Browser restart failed: ${err instanceof Error ? err.message : err}`);
+      return false;
+    }
+  }
+
   async switchToMainFrame() {
     if (this.playwrightHelper.frame) {
       debugLog('Switching to main frame');
@@ -415,6 +550,30 @@ class Explorer {
     }
   }
 
+  private async waitForUsablePageDom(): 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(() => {});
+    return true;
+  }
+
   async isInsideIframe(): Promise<boolean> {
     if (this.playwrightHelper.frame) return true;
 
@@ -542,11 +701,13 @@ class Explorer {
     return this._activeTest;
   }
 
-  async startTest(test: Test) {
+  async startTest(test: Test): Promise<boolean> {
     this._activeTest = test;
+    test.start();
     await this.reporter.reportTestStart(test);
     await this.closeOtherTabs();
     this.otherTabs = [];
+    if (!(await this.ensurePageAvailable())) return false;
 
     const codeceptjsTest = toCodeceptjsTest(test);
 
@@ -563,13 +724,7 @@ class Explorer {
       test.setActiveNoteScreenshot(lastScreenshot);
     };
 
-    const dialogHandler = (dialog: any) => {
-      const dialogType = dialog.type();
-      const dialogMessage = dialog.message();
-      test.addNote(`Native dialog ${dialogType} appeared: ${dialogMessage}. Accepted automatically`);
-    };
-
-    this.playwrightHelper?.page?.on('dialog', dialogHandler);
+    this.watchActiveTestPage();
 
     codeceptjs.event.dispatcher.emit('test.before', codeceptjsTest);
     codeceptjs.event.dispatcher.emit('test.start', codeceptjsTest);
@@ -580,11 +735,105 @@ class Explorer {
     codeceptjs.event.dispatcher.on('test.after', () => {
       codeceptjs.event.dispatcher.off('step.passed', stepHandler);
       codeceptjs.event.dispatcher.off('step.failed', stepHandler);
-      this.playwrightHelper?.page?.off('dialog', dialogHandler);
+      this.unwatchActiveTestPages();
     });
+
+    return true;
+  }
+
+  async ensurePageAvailable(): Promise<boolean> {
+    const page = this.playwrightHelper?.page;
+    if (page && !page.isClosed?.()) {
+      this.watchActiveTestPage(page);
+      return true;
+    }
+
+    const recovered = await this.recoverFromBrowserError();
+    if (!recovered) return false;
+    this.watchActiveTestPage();
+    return true;
+  }
+
+  async ensureActiveTestPageAvailable(): Promise<boolean> {
+    return this.ensurePageAvailable();
+  }
+
+  async handleExecutionError(error: unknown): Promise<BrowserExecutionErrorResult> {
+    const message = error instanceof Error ? error.message : String(error);
+    tag('error').log(`Browser execution error: ${message}`);
+
+    if (error instanceof Error && error.name === 'AbortError') {
+      return {
+        action: 'stop',
+        message,
+      };
+    }
+
+    if (error instanceof BrowserRecoveryError) {
+      return {
+        action: 'stop',
+        recovered: error.recovered,
+        message: error.message,
+      };
+    }
+
+    if (!this.isFatalBrowserError(error)) {
+      return {
+        action: 'continue',
+        message: `Previous execution error: ${message}. Investigate the current state and choose a different approach.`,
+      };
+    }
+
+    let recovered = await this.recoverFromBrowserError();
+    if (!recovered) recovered = await this.restartBrowser();
+
+    if (!recovered) {
+      return {
+        action: 'stop',
+        recovered: false,
+        message: `Browser could not be recovered after fatal error: ${message}`,
+      };
+    }
+
+    this.watchActiveTestPage();
+    return {
+      action: 'continue',
+      recovered: true,
+      message: dedent`
+        Browser was recovered after a fatal page error.
+        Continue from the restored page.
+        The interrupted browser action is not product evidence.
+        Inspect the restored page and retry the current step when it is still required.
+      `,
+    };
+  }
+
+  watchActiveTestPage(page = this.playwrightHelper?.page): void {
+    if (!this._activeTest) return;
+    if (!page) return;
+    if (this.observedTestPages.has(page)) return;
+
+    this.testPageErrorHandler ||= (err: Error) => {
+      this._activeTest?.addNote(`Console error: ${err.message}`, TestResult.FAILED);
+    };
+    this.testConsoleHandler ||= (msg: any) => {
+      if (msg.type() !== 'error') return;
+      this._activeTest?.addNote(`Console error: ${msg.text()}`, TestResult.FAILED);
+    };
+    this.testDialogHandler ||= (dialog: any) => {
+      const dialogType = dialog.type();
+      const dialogMessage = dialog.message();
+      this._activeTest?.addNote(`Native dialog ${dialogType} appeared: ${dialogMessage}. Accepted automatically`);
+    };
+
+    page.on('pageerror', this.testPageErrorHandler);
+    page.on('console', this.testConsoleHandler);
+    page.on('dialog', this.testDialogHandler);
+    this.observedTestPages.add(page);
   }
 
   async stopTest(test: Test, meta?: Record<string, string>) {
+    this.unwatchActiveTestPages();
     this._activeTest = null;
     const lastScreenshot = this.stateManager.getCurrentState()?.screenshotFile;
     if (lastScreenshot) {
@@ -609,6 +858,15 @@ class Explorer {
     codeceptjs.event.dispatcher.emit('test.after', codeceptjsTest);
   }
 
+  private unwatchActiveTestPages(): void {
+    for (const page of this.observedTestPages) {
+      if (this.testPageErrorHandler) page.off('pageerror', this.testPageErrorHandler);
+      if (this.testConsoleHandler) page.off('console', this.testConsoleHandler);
+      if (this.testDialogHandler) page.off('dialog', this.testDialogHandler);
+    }
+    this.observedTestPages.clear();
+  }
+
   async hasPlaywrightLocator(locatorFn: (page: any) => any, opts: { multiple?: boolean; contents?: boolean; success?: (locator: any) => Promise<void> | void } = {}): Promise<boolean> {
     try {
       const pwLocator = locatorFn(this.playwrightHelper.page);
@@ -671,7 +929,7 @@ class Explorer {
     await oldPage.close();
     await newPage.bringToFront();
 
-    this.playwrightHelper.page = newPage;
+    await this.playwrightHelper._setPage(newPage);
     this.otherTabs = [];
 
     this.bindFrameNavigated(newPage);
@@ -705,8 +963,7 @@ class Explorer {
     }
 
     await firstPage.bringToFront();
-
-    this.playwrightHelper.page = firstPage;
+    await this.playwrightHelper._setPage(firstPage);
 
     debugLog(`Cleaned up tabs, now focused on: ${await firstPage.url()}`);
   }

package/src/state-manager.ts

@@ -24,6 +24,8 @@ export interface WebPageState {
   url: string;
   /** Page title */
   title?: string;
+  /** HTTP status of the main document navigation */
+  httpStatus?: number;
   /** Full URL for reference */
   fullUrl?: string;
   /** Timestamp when state was captured */

package/src/utils/browser-errors.ts

@@ -0,0 +1,25 @@
+// Playwright and CodeceptJS surface browser/page disposal as plain Error objects,
+// 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'];
+
+export class BrowserRecoveryError extends Error {
+  constructor(
+    label: string,
+    public originalError: unknown,
+    public recovered: boolean
+  ) {
+    super(`${label} failed ${recovered ? 'after browser recovery' : 'because browser could not be recovered'}: ${browserErrorMessage(originalError)}`);
+    this.name = 'BrowserRecoveryError';
+  }
+}
+
+export function isFatalBrowserError(error: unknown): boolean {
+  if (error instanceof BrowserRecoveryError) return true;
+  const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
+  return FATAL_BROWSER_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/error-page.ts

@@ -1,4 +1,5 @@
-import type { ActionResult } from '../action-result.js';
+import { ActionResult } from '../action-result.js';
+import type { WebPageState } from '../state-manager.js';
 import { isBodyEmpty } from './html.js';
 
 const HTTP_ERRORS = ['400 Bad Request', '401 Unauthorized', '403 Forbidden', '404 Not Found', '405 Method Not Allowed', '408 Request Timeout', '500 Internal Server Error', '502 Bad Gateway', '503 Service Unavailable', '504 Gateway Timeout'];
@@ -9,6 +10,8 @@ const LOADING_WORD = /\bloading\b/i;
 export type PageCondition = 'ok' | 'loading' | 'error';
 
 export function detectPageCondition(actionResult: ActionResult): PageCondition {
+  if (actionResult.httpStatus && actionResult.httpStatus >= 400) return 'error';
+
   const headingFields = [actionResult.title, actionResult.h1, actionResult.h2].filter(Boolean) as string[];
 
   for (const field of headingFields) {
@@ -37,12 +40,22 @@ export function isErrorPage(actionResult: ActionResult): boolean {
   return detectPageCondition(actionResult) === 'error';
 }
 
+export function getStateErrorPageError(state: WebPageState | null | undefined): ErrorPageError | null {
+  if (!state) return null;
+  const actionResult = ActionResult.fromState(state);
+  if (!isErrorPage(actionResult)) return null;
+  return new ErrorPageError(actionResult.url, actionResult.title, actionResult.httpStatus);
+}
+
 export class ErrorPageError extends Error {
   constructor(
     public readonly url: string,
-    public readonly title?: string
+    public readonly title?: string,
+    public readonly httpStatus?: number
   ) {
-    super(`Error page detected at ${url}${title ? ` (${title})` : ''}`);
+    const status = httpStatus ? `HTTP ${httpStatus}` : '';
+    const details = [status, title].filter(Boolean).join(', ');
+    super(`Error page detected at ${url}${details ? ` (${details})` : ''}`);
     this.name = 'ErrorPageError';
   }
 }

package/src/utils/logger.ts

@@ -11,7 +11,7 @@ import { Observability } from '../observability.ts';
 import { RecentStepFilter } from './log-filters.ts';
 import { parseMarkdownToTerminal } from './markdown-terminal.ts';
 
-export type LogType = 'info' | 'success' | 'error' | 'warning' | 'debug' | 'substep' | 'operation' | 'step' | 'multiline' | 'html' | 'input';
+export type LogType = 'info' | 'success' | 'error' | 'warning' | 'debug' | 'substep' | 'operation' | 'step' | 'multiline' | 'details' | 'html' | 'input';
 
 export interface TaggedLogEntry {
   type: LogType;
@@ -99,7 +99,7 @@ class ConsoleDestination implements LogDestination {
     if (entry.type === 'operation' && !this.verboseMode) return;
     if (entry.type === 'step' && !this.verboseMode && this.recentSteps.shouldSuppress(entry.content)) return;
     let content = entry.content;
-    if (entry.type === 'multiline') {
+    if (entry.type === 'multiline' || entry.type === 'details') {
       const cleaned = stripAnsi(dedent(entry.content));
       const parsed = parseMarkdownToTerminal(cleaned);
       content = parsed;
@@ -314,7 +314,7 @@ class CaptainDestination implements LogDestination {
 
   stopCapture(): string[] {
     this.capturing = false;
-    const logs = this.entries.filter((e) => e.type !== 'debug' && e.type !== 'html' && e.type !== 'multiline' && e.type !== 'operation').map((e) => `[${e.type}] ${e.content}`);
+    const logs = this.entries.filter((e) => e.type !== 'debug' && e.type !== 'html' && e.type !== 'multiline' && e.type !== 'details' && e.type !== 'operation').map((e) => `[${e.type}] ${e.content}`);
     this.entries = [];
     return logs;
   }