explorbot 0.5.1 → 0.5.3

package/src/ai/rerunner.ts

@@ -1,5 +1,5 @@
 import { existsSync } from 'node:fs';
-import { relative, resolve } from 'node:path';
+import { dirname, relative, resolve } from 'node:path';
 import { tool } from 'ai';
 import { createBashTool } from 'bash-tool';
 import chalk from 'chalk';
@@ -19,6 +19,7 @@ import { createDebug, tag } from '../utils/logger.ts';
 import { loop } from '../utils/loop.ts';
 import { RulesLoader } from '../utils/rules-loader.ts';
 import { isInternalStep } from '../utils/step-analyzer.ts';
+import { ensureCodeceptResolvable } from '../utils/test-files.ts';
 import type { Agent, AgentDeps } from './agent.ts';
 import { toolExecutionLabel } from './conversation.ts';
 import type { Navigator } from './navigator.ts';
@@ -135,6 +136,7 @@ export class Rerunner extends TaskAgent implements Agent {
       codeceptjs.container.createMocha();
       const mocha = codeceptjs.container.mocha();
       mocha.reporter(class {});
+      ensureCodeceptResolvable(dirname(absPath));
       mocha.files = [absPath];
       mocha.loadFiles();
 

package/src/ai/rules.ts

@@ -237,7 +237,7 @@ export const unexpectedPopupRule = dedent`
   If a modal/popup appeared that you didn't expect, dismiss it first before continuing with original task.
   If elements become hidden or unclickable (timeout errors on visible elements), a dialog or overlay may have appeared on top.
   If a click error mentions "intercepts pointer events", another element is covering the target — dismiss it first.
-  If buttons are disabled unexpectedly, check if a popup is blocking interaction or if required form fields are empty.
+  If buttons are disabled unexpectedly, trust any explanation the app gives (tooltip, hint text) over your own guess; otherwise check for a blocking popup or empty required fields.
 
   Dismiss strategy (try in order):
   1. I.pressKey('Escape') — press Escape to dismiss

package/src/ai/tester.ts

@@ -324,7 +324,12 @@ export class Tester extends TaskAgent implements Agent {
               const guidance = await this.pilot.reviewNewPage(task, currentState, conversation);
               if (guidance) nextStep += `\n\n${guidance}`;
             } else if (this.shouldAnalyzeProgress(iteration, currentState) && this.pilot) {
-              const guidance = await this.pilot.analyzeProgress(task, currentState, conversation);
+              let guidance: string;
+              if (this.isStruggling) {
+                guidance = await this.pilot.analyzeProgress(task, currentState, conversation);
+              } else {
+                guidance = await this.pilot.periodicAnalyzeProgress(task, currentState, conversation);
+              }
               if (guidance) nextStep += `\n\n${guidance}`;
               this.consecutiveFailures = 0;
               this.lastAnalyzedStateHash = currentState.hash;
@@ -486,13 +491,16 @@ export class Tester extends TaskAgent implements Agent {
       this.regionTransitioned = false;
       return true;
     }
-    if (this.consecutiveFailures >= 3) return true;
-    if (this.consecutiveEmptyResults >= 2) return true;
+    if (this.isStruggling) return true;
     if (iteration % this.progressCheckInterval !== 0) return false;
     if (this.lastAnalyzedStateHash === currentState.hash) return false;
     return true;
   }
 
+  private get isStruggling(): boolean {
+    return this.consecutiveFailures >= 3 || this.consecutiveEmptyResults >= 2;
+  }
+
   private shouldStopForStalledExecution(task: Test, previousState: ActionResult, toolExecutions: any[]): boolean {
     if (task.hasFinished) return false;
 
@@ -744,6 +752,16 @@ export class Tester extends TaskAgent implements Agent {
   }
 
   getSystemMessage(): string {
+    let judgeRule = '';
+    if (this.agentTools?.judge) {
+      judgeRule = dedent`
+        <judge_rule>
+        For a quick judgement about the current page (did the last action already take effect, which element the scenario means), ask judge() before see().
+        Keep see() for what only a screenshot shows.
+        </judge_rule>
+      `;
+    }
+
     return dedent`
     <role>
     You are a senior test automation engineer with expertise in CodeceptJS and exploratory testing.
@@ -843,6 +861,8 @@ export class Tester extends TaskAgent implements Agent {
 
     ${capabilityGroundingRule}
 
+    ${judgeRule}
+
     ${dataProtectionRules}
 
     ${this.provider.getSystemPromptForAgent('tester', this.stateManager.getCurrentState()?.url) || ''}

package/src/ai/tools.ts

@@ -16,7 +16,7 @@ import { compactErrorMessage, normalizeInlineText, truncate } from '../utils/str
 import { WebElement } from '../utils/web-element.ts';
 import type { ToolDeps } from './agent.ts';
 import { createJudgeTool } from './judge-tool.ts';
-import { JUDGE_PAGE_CAP, type Judge, UNDECIDED } from './judge.ts';
+import { JUDGE_PAGE_CAP, type Judge } from './judge.ts';
 import { Navigator } from './navigator.ts';
 import { Researcher } from './researcher.ts';
 import { sectionContextRule } from './rules.ts';
@@ -113,13 +113,20 @@ export function createCodeceptJSTools({ explorer, stateManager, judge }: ToolDep
 
         for (let i = 0; i < commands.length; i++) {
           const command = transformContainsCommand(commands[i]);
-          const success = await action.attempt(command, explanation);
+          let success = await action.attempt(command, explanation);
 
           const attempt: { command: string; success: boolean; error?: string } = { command, success };
           if (action.lastError) attempt.error = errorText(action.lastError);
           attempts.push(attempt);
 
-          if (!ambiguityError && action.lastError?.name === 'MultipleElementsFound') ambiguityError = action.lastError;
+          if (!ambiguityError && action.lastError?.name === 'MultipleElementsFound') {
+            ambiguityError = action.lastError;
+            if (judge) {
+              const labels = (await extractWebElements(ambiguityError))?.map((el) => el.label) || [];
+              const index = await judge.pick(PICK_ELEMENT_QUESTION, labels, { intent: explanation, task: task.description });
+              if (index) success = await action.attemptExactElementIndex(command, index, explanation);
+            }
+          }
 
           if (success) {
             const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, command);
@@ -149,19 +156,22 @@ export function createCodeceptJSTools({ explorer, stateManager, judge }: ToolDep
         await commitNote(activeNote, TestResult.FAILED, toolResult, action);
 
         const suggestion = clickFailureSuggestion(attempts);
+        const data: Record<string, any> = { ...toolResult, attempts, suggestion };
+        const clickError = ambiguityError || action.lastError;
+
+        for (const disabled of attempts.filter((a) => a.error?.includes('not enabled'))) {
+          const hoverCommand = disabled.command.replace('I.click(', 'I.moveCursorTo(');
+          const beforeHover = ActionResult.fromState(stateManager.getCurrentState()!);
+          if (!(await action.attempt(hoverCommand, 'Hover the disabled element to reveal why it is disabled'))) continue;
+          const hoverResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(beforeHover, hoverCommand);
+          const shown = hoverResult.pageDiff?.messages;
+          if (!shown?.length) break;
+          data.disabledReason = shown;
+          data.suggestion = `Element is DISABLED. Hovering it showed: "${shown.join(' | ')}". That is why — act on it or report it, do not guess another cause.`;
+          break;
+        }
 
-        return failedToolResult(
-          'click',
-          'All click commands failed',
-          {
-            ...toolResult,
-            attempts,
-            suggestion,
-          },
-          ambiguityError || action.lastError,
-          judge,
-          explanation
-        );
+        return failedToolResult('click', 'All click commands failed', data, clickError);
       },
     }),
 
@@ -1309,10 +1319,13 @@ export async function failedToolResult(action: string, message: string, data?: R
     result.suggestion = getMultipleElementsSuggestion();
     result.multipleElementsDetected = true;
     result.elements = formatElementList(matched);
-    const labels = (matched || []).map((element) => `${element.text || 'no text'} — ${element.html}`);
-    const pick = await judge?.decide('Which listed element does the intent name?', [...labels, UNDECIDED], { intent });
-    if (!pick?.value) return result;
-    const index = labels.indexOf(pick.value) + 1;
+    if (!judge || !matched) return result;
+    const index = await judge.pick(
+      PICK_ELEMENT_QUESTION,
+      matched.map((el) => el.label),
+      { intent }
+    );
+    if (!index) return result;
     result.suggestion = `Element ${index} is the one meant. Repeat the action with step.opts({ elementIndex: ${index} }) as the last argument.`;
     return result;
   }
@@ -1333,6 +1346,7 @@ function getMultipleElementsSuggestion(): string {
     reuse the same locator with step.opts({ elementIndex: N }) as the last argument.
     A match reported as not visible can never be acted on — pick one that is.
     If none of them is the element you want, narrow the locator with a container or its full unique text.
+    If the matches cannot be told apart, click the one you mean by appearance with visualClick().
     If the list is missing, call xpathCheck() to see what the locator matches.
   `;
 }
@@ -1347,7 +1361,7 @@ export function clickFailureSuggestion(attempts: Array<{ error?: string }>): str
   const errors = attempts.map((a) => a.error || '');
 
   if (errors.some((e) => e.includes('not enabled'))) {
-    return 'Element exists but is DISABLED — clicking it again cannot work. A precondition is unmet: a required field is empty, nothing is selected, or a dialog is blocking. Satisfy it, then retry.';
+    return 'Element exists but is DISABLED — clicking it again cannot work. Find the precondition the page shows as unmet, then retry.';
   }
 
   if (errors.some((e) => e.includes('intercepts pointer events'))) {
@@ -1379,6 +1393,7 @@ const MAX_DISAMBIGUATE_ELEMENTS = 10;
 const MAX_DISAMBIGUATE_TEXT = 80;
 const MAX_DISAMBIGUATE_HTML = 300;
 const MULTIPLE_ELEMENTS_PATTERN = 'multiple elements';
+const PICK_ELEMENT_QUESTION = 'Which listed element does the intent name?';
 
 async function extractWebElements(error: Error | null | undefined): Promise<MatchedElement[] | null> {
   if (!error || error.name !== 'MultipleElementsFound') return null;
@@ -1393,7 +1408,7 @@ async function extractWebElements(error: Error | null | undefined): Promise<Matc
       const html = truncate(cleanHtmlSnippet(await elements[i].toOuterHTML()), MAX_DISAMBIGUATE_HTML);
       const text = truncate(normalizeInlineText((await elements[i].getText()) || ''), MAX_DISAMBIGUATE_TEXT);
       const visible = await Promise.resolve(elements[i].isVisible?.()).catch(() => undefined);
-      result.push({ xpath, html, text, visible });
+      result.push({ xpath, html, text, visible, label: `${text || 'no text'} — ${html}` });
     } catch (e) {
       debugLog('Failed to get details for element %d: %s', i, e);
     }
@@ -1443,5 +1458,6 @@ interface MatchedElement {
   xpath: string;
   html: string;
   text: string;
+  label: string;
   visible?: boolean;
 }

package/src/config.ts

@@ -185,7 +185,7 @@ interface AIConfig {
   vision?: boolean;
   visionModel?: any;
   agenticModel?: any;
-  decisionModel?: { provider: string; model: string; tool?: boolean; direct?: boolean };
+  decisionModel?: { provider: string; model: string; tool?: boolean; direct?: boolean; threshold?: number };
   retryAttempts?: number;
   retryDelay?: number;
   maxParallelRequests?: number;
@@ -327,6 +327,7 @@ export class ConfigParser {
   private site: SiteRecord | null = null;
   private siteStartPath = '/';
   private siteConfigPath: string | null = null;
+  private runBase: RunBase | null = null;
 
   private constructor() {}
 
@@ -368,6 +369,7 @@ export class ConfigParser {
     if (this.config && !options?.config && !options?.path && this.runtimeTarget === target) {
       return this.config;
     }
+    this.runBase = parseRunBase(options?.baseUrl);
 
     // Store the initial working directory for reference
     if (!process.env.INITIAL_CWD) {
@@ -404,14 +406,21 @@ export class ConfigParser {
         let envUrl = options?.baseUrl;
         if (!envUrl && target?.startsWith('http')) envUrl = target;
 
-        const outputRoot = resolveOutputRoot(process.env.EXPLORBOT_URL || envUrl);
+        if (options?.baseUrl) {
+          const envOrigin = URL.parse(process.env.EXPLORBOT_URL || '')?.origin;
+          const baseOrigin = URL.parse(options.baseUrl)?.origin;
+          if (envOrigin && envOrigin !== baseOrigin) {
+            tag('warning').log(`--base-url ${baseOrigin} selects the site for this run — EXPLORBOT_URL ${envOrigin} is ignored`);
+          }
+        }
+        const outputRoot = resolveOutputRoot(options?.baseUrl || process.env.EXPLORBOT_URL || envUrl);
         loadedConfig = await this.buildEnvConfig(envUrl, outputRoot);
         sourcePath = join(outputRoot, 'explorbot.config.js');
 
         log(`Configuration built from EXPLORBOT_* environment variables. Output: ${outputRoot}`);
       }
 
-      let config = this.resolveConfig(loadedConfig as ExplorbotConfig, options);
+      let config = this.resolveConfig(loadedConfig as ExplorbotConfig);
       await resolveConfigModels(config.ai);
       this.site = null;
       this.siteConfigPath = null;
@@ -484,6 +493,22 @@ export class ConfigParser {
     return this.siteConfigPath;
   }
 
+  public applyBasePath(target: string): string {
+    const base = this.runBase?.path;
+    if (!base) return target;
+    if (!target.startsWith('/')) return target;
+    if (target === base || target.startsWith(`${base}/`) || target.startsWith(`${base}?`)) return target;
+    return `${base}${target}`;
+  }
+
+  public getBaseQuery(): string {
+    return this.runBase?.query || '';
+  }
+
+  public getBasePath(): string {
+    return this.runBase?.path || '';
+  }
+
   public resolveTargetPath(target?: string): string {
     if (!this.site) {
       const configured = this.config?.playwright?.url || this.config?.web?.url;
@@ -492,12 +517,13 @@ export class ConfigParser {
       if (targetOrigin && baseOrigin && targetOrigin !== baseOrigin) {
         tag('warning').log(`Exploring ${targetOrigin} but base URL is ${baseOrigin}. Relative navigation resolves against the base URL — set web.url to ${targetOrigin} to avoid it.`);
       }
-      return target || '/';
+      return this.applyBasePath(target || '/');
     }
     if (!target) return this.siteStartPath;
 
     const resolved = resolveSiteTarget(target, this.site.url);
     if (resolved.baseUrl !== this.site.url) return target;
+    if (target.startsWith('/')) return this.applyBasePath(resolved.path);
     return resolved.path;
   }
 
@@ -524,6 +550,7 @@ export class ConfigParser {
       ConfigParser.instance.site = null;
       ConfigParser.instance.siteStartPath = '/';
       ConfigParser.instance.siteConfigPath = null;
+      ConfigParser.instance.runBase = null;
     }
   }
 
@@ -694,15 +721,15 @@ export class ConfigParser {
     }
   }
 
-  private resolveConfig(config: ExplorbotConfig, options?: { baseUrl?: string }): ExplorbotConfig {
+  private resolveConfig(config: ExplorbotConfig): ExplorbotConfig {
     if (config.web?.url && !config.playwright?.url) {
       config.playwright = config.playwright || { browser: 'chromium', url: '' };
       config.playwright.url = config.web.url;
     }
 
-    if (options?.baseUrl) {
+    if (this.runBase) {
       config.playwright = config.playwright || { browser: 'chromium', url: '' };
-      config.playwright.url = options.baseUrl;
+      config.playwright.url = this.runBase.origin;
     }
 
     resolveLangfuse(config.ai);
@@ -936,8 +963,23 @@ export async function createModel(provider: string, modelId: string): Promise<an
   return (await info.load())(modelId);
 }
 
+function parseRunBase(baseUrl?: string): RunBase | null {
+  if (!baseUrl) return null;
+
+  const url = URL.parse(baseUrl);
+  if (!url) throw new Error(`Base URL must be a full URL like https://app.example.com/team/acme, got "${baseUrl}"`);
+
+  return { origin: url.origin, path: url.pathname.replace(/\/+$/, ''), query: url.search };
+}
+
 type ModelRole = 'model' | 'visionModel' | 'agenticModel';
 
+interface RunBase {
+  origin: string;
+  path: string;
+  query: string;
+}
+
 interface ConfiguredModel {
   name: string;
   provider: string;

package/src/explorbot.ts

@@ -517,6 +517,8 @@ export class ExplorBot {
   setCurrentPlan(plan?: Plan): void {
     this.currentPlan = plan;
     if (!plan) return;
+    if (plan.url) plan.url = this.configParser.applyBasePath(plan.url);
+    for (const test of plan.tests) test.startUrl = this.configParser.applyBasePath(test.startUrl);
     if (!this.sessionPlans.includes(plan)) {
       this.sessionPlans.push(plan);
     }

package/src/explorer.ts

@@ -6,7 +6,7 @@ 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 { Browser, BrowserContextOptions, Page } from 'playwright';
+import type { Browser, BrowserContextOptions, Page, Route } from 'playwright';
 import { ActionResult } from './action-result.ts';
 import Action from './action.js';
 import type { RequestStore } from './api/request-store.ts';
@@ -103,6 +103,7 @@ class Explorer {
     if (!this.playwrightHelper) {
       throw new Error('Playwright helper not available');
     }
+    this.applyBasePathToHelper();
     await this.connectOrLaunchBrowser();
     const hasSession = !this.options?.attachedBrowser && this.options?.session && existsSync(this.options.session);
     await this.openContextPage();
@@ -163,7 +164,7 @@ class Explorer {
 
   async visit(url: string, opts: CaptureOpts = {}): Promise<ActionResult> {
     return this.runWithRecovery('visit', async () => {
-      const action = await this.visitOnce(url);
+      const action = await this.visitOnce(ConfigParser.getInstance().applyBasePath(url));
       if (opts.screenshot) return action.capturePageState({ includeScreenshot: true });
       return action.getActionResult() ?? action.capturePageState();
     });
@@ -347,6 +348,7 @@ class Explorer {
     const attached = this.options?.attachedBrowser;
     if (!attached) {
       await this.playwrightHelper._createContextPage(this.createBrowserContextOptions());
+      await this.pinBaseQuery();
       return;
     }
 
@@ -356,6 +358,39 @@ class Explorer {
     this.playwrightHelper.browserContext = context;
     await this.playwrightHelper._setPage(page);
     debugLog(`Adopted attached browser page: ${page.url()}`);
+    await this.pinBaseQuery();
+  }
+
+  private applyBasePathToHelper(): void {
+    if (!ConfigParser.getInstance().getBasePath()) return;
+
+    const helper = this.playwrightHelper;
+    const original = helper.amOnPage.bind(helper);
+    helper.amOnPage = (url: string) => original(ConfigParser.getInstance().applyBasePath(url));
+  }
+
+  private async pinBaseQuery(): Promise<void> {
+    const query = ConfigParser.getInstance().getBaseQuery();
+    if (!query) return;
+
+    const pinned = new URLSearchParams(query);
+    const origin = URL.parse(this.config.playwright.url)?.origin;
+
+    await this.playwrightHelper.browserContext.route('**/*', async (route: Route) => {
+      const request = route.request();
+      if (request.resourceType() !== 'document') return route.continue();
+
+      const url = URL.parse(request.url());
+      if (!url || url.origin !== origin) return route.continue();
+
+      const missing = [...pinned].filter(([key]) => !url.searchParams.has(key));
+      if (!missing.length) return route.continue();
+
+      for (const [key, value] of missing) url.searchParams.set(key, value);
+      return route.continue({ url: url.toString() });
+    });
+
+    tag('info').log(`Every page load of ${origin} carries ${query}`);
   }
 
   private createBrowserContextOptions(): BrowserContextOptions {

package/src/global-config.ts

@@ -131,7 +131,7 @@ export function resolveSiteTarget(target?: string, defaultBaseUrl?: string): Sit
   }
 
   if (raw.startsWith('/')) {
-    const base = defaultBaseUrl || process.env.EXPLORBOT_URL;
+    const base = process.env.EXPLORBOT_URL || defaultBaseUrl;
     if (!base) {
       throw new Error(withSites(`Cannot resolve path "${raw}" without a site.`));
     }

package/src/utils/test-files.ts

@@ -1,4 +1,5 @@
-import { existsSync, readdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, symlinkSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import path from 'node:path';
 import chalk from 'chalk';
 import { highlight } from 'cli-highlight';
@@ -9,6 +10,8 @@ import store from 'codeceptjs/lib/store';
 import figureSet from 'figures';
 import { ConfigParser } from '../config.ts';
 
+const nodeRequire = createRequire(import.meta.url);
+
 export function listTestFiles(testsDir: string): string[] {
   if (!existsSync(testsDir)) return [];
 
@@ -17,10 +20,32 @@ export function listTestFiles(testsDir: string): string[] {
     .map((f) => path.resolve(testsDir, f));
 }
 
+/**
+ * Generated tests import `codeceptjs/steps`, but in global mode they lie in ~/.explorbot,
+ * far from any node_modules. Link the bot's own codeceptjs next to them so Node resolves it.
+ */
+export function ensureCodeceptResolvable(dir: string): void {
+  const link = path.join(dir, 'node_modules', 'codeceptjs');
+  if (existsSync(link)) return;
+  let target: string;
+  try {
+    target = path.dirname(nodeRequire.resolve('codeceptjs/package.json'));
+  } catch {
+    return;
+  }
+  try {
+    mkdirSync(path.dirname(link), { recursive: true });
+    symlinkSync(target, link, process.platform === 'win32' ? 'junction' : 'dir');
+  } catch {
+    // Best effort: a project install already resolves codeceptjs without the link.
+  }
+}
+
 export function loadTestSuites(testsDir: string): any[] {
   const jsFiles = listTestFiles(testsDir);
   if (jsFiles.length === 0) return [];
 
+  ensureCodeceptResolvable(testsDir);
   codeceptjs.container.createMocha();
   const mocha = codeceptjs.container.mocha();
   mocha.files = jsFiles;
@@ -93,6 +118,7 @@ export async function dryRunTestFile(filePath: string): Promise<void> {
   codeceptjs.container.createMocha();
   const mocha = codeceptjs.container.mocha();
   mocha.reporter(class {});
+  ensureCodeceptResolvable(path.dirname(absPath));
   mocha.files = [absPath];
   mocha.loadFiles();