browsecraft 0.4.0 → 0.5.0

package/README.md

@@ -341,12 +341,14 @@ Everything works without AI. These features enhance the experience when availabl
 | Feature | What it does |
 | --- | --- |
 | Self-healing selectors | When a CSS selector breaks, suggests a replacement using page context |
+| AI failure diagnosis | Analyzes failures with page context and suggests fixes |
 | Test generation | Generates test code from a natural-language description |
 | Visual regression | Compares screenshots pixel-by-pixel, with optional AI semantic analysis |
 | Auto-step generation | Writes BDD step definitions from `.feature` files automatically |
+| Persistent AI cache | Caches AI results on disk to avoid redundant API calls |
 
 ```js
-import { healSelector, generateTest, compareScreenshots } from 'browsecraft-ai';
+import { healSelector, generateTest, compareScreenshots, diagnoseFailure } from 'browsecraft-ai';
 ```
 
 ## Examples
@@ -371,15 +373,16 @@ node test.mjs --maximized  # full screen
 
 ## Architecture
 
-Five npm packages, one monorepo:
+Six npm packages, one monorepo:
 
 | Package | Role |
 | --- | --- |
-| `browsecraft` | Main package. Page API, Browser, config, CLI. |
-| `browsecraft-bdd` | Gherkin parser, step registry, executor, hooks, tags, TS-native BDD. |
+| `browsecraft` | Main package. Page API, Browser, config, CLI, adaptive timing, self-healing. |
+| `browsecraft-bdd` | Gherkin parser, step registry, executor, hooks, tags, TS-native BDD, 38 built-in steps, AI auto-steps. |
 | `browsecraft-bidi` | WebDriver BiDi protocol client and browser launcher. |
-| `browsecraft-runner` | Test file discovery, execution, reporter types. |
-| `browsecraft-ai` | Self-healing selectors, test generation, visual diff. |
+| `browsecraft-runner` | Event bus, multi-browser worker pool, parallel scheduler, result aggregator, failure classification, smart retry. |
+| `browsecraft-ai` | Self-healing selectors, AI failure diagnosis, test generation, visual diff, persistent cache. |
+| `create-browsecraft` | Project scaffolding CLI (`npm init browsecraft`). Zero dependencies. |
 
 Most users only need `browsecraft`. Add `browsecraft-bdd` for BDD, `browsecraft-ai` for AI features.
 

package/dist/{chunk-P3F7FGFM.js → chunk-GAN2YUTJ.js}

@@ -31,6 +31,42 @@ function resolveConfig(userConfig) {
     viewport: userConfig.viewport ?? DEFAULTS.viewport
   };
 }
+function resolveAIConfig(ai) {
+  if (ai === "off") return null;
+  if (typeof ai === "object") return ai;
+  const explicitProvider = process.env.BROWSECRAFT_AI_PROVIDER;
+  if (explicitProvider) {
+    switch (explicitProvider.toLowerCase()) {
+      case "github-models":
+      case "github":
+        return { provider: "github-models" };
+      case "openai":
+        return { provider: "openai" };
+      case "anthropic":
+        return { provider: "anthropic" };
+      case "ollama":
+        return { provider: "ollama" };
+      default:
+        console.warn(
+          `[browsecraft] Unknown AI provider "${explicitProvider}". Supported: github-models, openai, anthropic, ollama`
+        );
+        return null;
+    }
+  }
+  if (process.env.OPENAI_API_KEY) {
+    return { provider: "openai" };
+  }
+  if (process.env.ANTHROPIC_API_KEY) {
+    return { provider: "anthropic" };
+  }
+  if (process.env.BROWSECRAFT_GITHUB_TOKEN || process.env.GITHUB_TOKEN) {
+    return { provider: "github-models" };
+  }
+  if (process.env.OLLAMA_HOST) {
+    return { provider: "ollama" };
+  }
+  return null;
+}
 
 // src/errors.ts
 var BrowsecraftError = class extends Error {
@@ -130,6 +166,78 @@ var NetworkError = class extends BrowsecraftError {
 var TimeoutError = class extends BrowsecraftError {
   name = "TimeoutError";
 };
+function classifyFailure(error) {
+  if (!(error instanceof Error)) {
+    return { category: "unknown", retryable: true, description: "Non-Error thrown" };
+  }
+  if (error instanceof ElementNotFoundError) {
+    return {
+      category: "element",
+      retryable: true,
+      description: "Element not found \u2014 page may still be loading or selector changed"
+    };
+  }
+  if (error instanceof ElementNotActionableError) {
+    return {
+      category: "actionability",
+      retryable: true,
+      description: `Element not actionable (${error.reason}) \u2014 may become ready`
+    };
+  }
+  if (error instanceof NetworkError) {
+    return {
+      category: "network",
+      retryable: true,
+      description: "Network failure \u2014 may be transient"
+    };
+  }
+  if (error instanceof TimeoutError) {
+    return {
+      category: "timeout",
+      retryable: true,
+      description: "Timed out \u2014 environment may be slow or element delayed"
+    };
+  }
+  const name = error.name ?? "";
+  if (name === "AssertionError" || name === "AssertionError [ERR_ASSERTION]" || name === "ERR_ASSERTION" || error.constructor?.name === "AssertionError") {
+    return {
+      category: "assertion",
+      retryable: false,
+      description: "Assertion failed \u2014 retrying won't help"
+    };
+  }
+  const msg = error.message ?? "";
+  const lowerMsg = msg.toLowerCase();
+  if (lowerMsg.includes("expected") && (lowerMsg.includes("to equal") || lowerMsg.includes("to be") || lowerMsg.includes("to have") || lowerMsg.includes("to match") || lowerMsg.includes("to contain") || lowerMsg.includes("but got") || lowerMsg.includes("but received"))) {
+    return {
+      category: "assertion",
+      retryable: false,
+      description: "Assertion failed \u2014 retrying won't help"
+    };
+  }
+  if (name === "SyntaxError" || name === "ReferenceError" || name === "TypeError" || name === "RangeError") {
+    return {
+      category: "script",
+      retryable: false,
+      description: `${name} \u2014 likely a code bug, retrying won't help`
+    };
+  }
+  if (lowerMsg.includes("timed out") || lowerMsg.includes("timeout")) {
+    return {
+      category: "timeout",
+      retryable: true,
+      description: "Timed out \u2014 environment may be slow"
+    };
+  }
+  if (lowerMsg.includes("econnrefused") || lowerMsg.includes("econnreset") || lowerMsg.includes("enotfound") || lowerMsg.includes("fetch failed") || lowerMsg.includes("network")) {
+    return {
+      category: "network",
+      retryable: true,
+      description: "Network failure \u2014 may be transient"
+    };
+  }
+  return { category: "unknown", retryable: true, description: "Unknown error \u2014 will retry" };
+}
 function formatElementState(state) {
   if (!state.found) return "Element state: NOT FOUND in DOM";
   const lines = ["Element state:"];
@@ -680,6 +788,10 @@ var Page = class {
   interceptIds = [];
   /** @internal -- event listener unsubscribe functions for cleanup */
   eventCleanups = [];
+  /** @internal -- adaptive timing: multiplier derived from environment speed */
+  timingMultiplier = 1;
+  /** @internal -- whether timing has been calibrated */
+  timingCalibrated = false;
   constructor(session, contextId, config) {
     this.session = session;
     this.contextId = contextId;
@@ -699,11 +811,17 @@ var Page = class {
   async goto(url, options) {
     const fullUrl = this.resolveURL(url);
     const waitUntil = options?.waitUntil ?? "complete";
+    const navStart = Date.now();
     await this.session.browsingContext.navigate({
       context: this.contextId,
       url: fullUrl,
       wait: waitUntil
     });
+    if (!this.timingCalibrated) {
+      this.timingCalibrated = true;
+      const elapsed = Date.now() - navStart;
+      this.timingMultiplier = Math.max(1, Math.min(5, elapsed / 800));
+    }
   }
   /**
    * Reload the current page.
@@ -746,7 +864,7 @@ var Page = class {
    */
   async click(target, options) {
     const timeout = options?.timeout ?? this.config.timeout;
-    const located = await locateElement(this.session, this.contextId, target, { timeout });
+    const located = await this.locateWithHealing(target, "click", { timeout });
     await this.ensureActionable(located, "click", target, { timeout });
     await this.scrollIntoViewAndClick(located, options);
   }
@@ -762,7 +880,7 @@ var Page = class {
   async fill(target, value, options) {
     const timeout = options?.timeout ?? this.config.timeout;
     const resolvedTarget = typeof target === "string" ? { label: target, name: target } : target;
-    const located = await locateElement(this.session, this.contextId, resolvedTarget, { timeout });
+    const located = await this.locateWithHealing(resolvedTarget, "fill", { timeout });
     await this.ensureActionable(located, "fill", target, { timeout });
     const ref = this.getSharedRef(located.node);
     await this.session.script.callFunction({
@@ -801,7 +919,7 @@ var Page = class {
   async type(target, text, options) {
     const timeout = options?.timeout ?? this.config.timeout;
     const resolvedTarget = typeof target === "string" ? { label: target, name: target } : target;
-    const located = await locateElement(this.session, this.contextId, resolvedTarget, { timeout });
+    const located = await this.locateWithHealing(resolvedTarget, "type", { timeout });
     await this.ensureActionable(located, "type", target, { timeout });
     const ref = this.getSharedRef(located.node);
     await this.session.script.callFunction({
@@ -830,7 +948,7 @@ var Page = class {
   async select(target, value, options) {
     const timeout = options?.timeout ?? this.config.timeout;
     const resolvedTarget = typeof target === "string" ? { label: target, name: target } : target;
-    const located = await locateElement(this.session, this.contextId, resolvedTarget, { timeout });
+    const located = await this.locateWithHealing(resolvedTarget, "select", { timeout });
     await this.ensureActionable(located, "select", target, { timeout });
     const ref = this.getSharedRef(located.node);
     await this.session.script.callFunction({
@@ -858,7 +976,7 @@ var Page = class {
    */
   async check(target, options) {
     const timeout = options?.timeout ?? this.config.timeout;
-    const located = await locateElement(this.session, this.contextId, target, { timeout });
+    const located = await this.locateWithHealing(target, "check", { timeout });
     await this.ensureActionable(located, "check", target, { timeout });
     const ref = this.getSharedRef(located.node);
     const result = await this.session.script.callFunction({
@@ -877,7 +995,7 @@ var Page = class {
    */
   async uncheck(target, options) {
     const timeout = options?.timeout ?? this.config.timeout;
-    const located = await locateElement(this.session, this.contextId, target, { timeout });
+    const located = await this.locateWithHealing(target, "uncheck", { timeout });
     await this.ensureActionable(located, "uncheck", target, { timeout });
     const ref = this.getSharedRef(located.node);
     const result = await this.session.script.callFunction({
@@ -900,7 +1018,7 @@ var Page = class {
    */
   async hover(target, options) {
     const timeout = options?.timeout ?? this.config.timeout;
-    const located = await locateElement(this.session, this.contextId, target, { timeout });
+    const located = await this.locateWithHealing(target, "hover", { timeout });
     await this.ensureActionable(located, "hover", target, { timeout });
     const ref = this.getSharedRef(located.node);
     await this.session.script.callFunction({
@@ -1234,7 +1352,7 @@ var Page = class {
    */
   async tap(target, options) {
     const timeout = options?.timeout ?? this.config.timeout;
-    const located = await locateElement(this.session, this.contextId, target, { timeout });
+    const located = await this.locateWithHealing(target, "tap", { timeout });
     await this.ensureActionable(located, "tap", target, { timeout });
     const ref = this.getSharedRef(located.node);
     await this.session.script.callFunction({
@@ -1270,7 +1388,7 @@ var Page = class {
   async focus(target, options) {
     const timeout = options?.timeout ?? this.config.timeout;
     const resolvedTarget = typeof target === "string" ? { label: target, name: target } : target;
-    const located = await locateElement(this.session, this.contextId, resolvedTarget, { timeout });
+    const located = await this.locateWithHealing(resolvedTarget, "focus", { timeout });
     await this.ensureActionable(located, "focus", target, { timeout, enabled: false });
     const ref = this.getSharedRef(located.node);
     await this.session.script.callFunction({
@@ -1290,7 +1408,7 @@ var Page = class {
   async blur(target, options) {
     const timeout = options?.timeout ?? this.config.timeout;
     const resolvedTarget = typeof target === "string" ? { label: target, name: target } : target;
-    const located = await locateElement(this.session, this.contextId, resolvedTarget, { timeout });
+    const located = await this.locateWithHealing(resolvedTarget, "blur", { timeout });
     const ref = this.getSharedRef(located.node);
     await this.session.script.callFunction({
       functionDeclaration: "function(el) { el.blur(); }",
@@ -1308,7 +1426,7 @@ var Page = class {
    */
   async innerText(target, options) {
     const timeout = options?.timeout ?? this.config.timeout;
-    const located = await locateElement(this.session, this.contextId, target, { timeout });
+    const located = await this.locateWithHealing(target, "innerText", { timeout });
     const ref = this.getSharedRef(located.node);
     const result = await this.session.script.callFunction({
       functionDeclaration: 'function(el) { return el.innerText || ""; }',
@@ -1327,7 +1445,7 @@ var Page = class {
    */
   async innerHTML(target, options) {
     const timeout = options?.timeout ?? this.config.timeout;
-    const located = await locateElement(this.session, this.contextId, target, { timeout });
+    const located = await this.locateWithHealing(target, "innerHTML", { timeout });
     const ref = this.getSharedRef(located.node);
     const result = await this.session.script.callFunction({
       functionDeclaration: 'function(el) { return el.innerHTML || ""; }',
@@ -1347,7 +1465,7 @@ var Page = class {
   async inputValue(target, options) {
     const timeout = options?.timeout ?? this.config.timeout;
     const resolvedTarget = typeof target === "string" ? { label: target, name: target } : target;
-    const located = await locateElement(this.session, this.contextId, resolvedTarget, { timeout });
+    const located = await this.locateWithHealing(resolvedTarget, "inputValue", { timeout });
     const ref = this.getSharedRef(located.node);
     const result = await this.session.script.callFunction({
       functionDeclaration: 'function(el) { return el.value ?? ""; }',
@@ -1367,7 +1485,7 @@ var Page = class {
   async selectOption(target, values, options) {
     const timeout = options?.timeout ?? this.config.timeout;
     const resolvedTarget = typeof target === "string" ? { label: target, name: target } : target;
-    const located = await locateElement(this.session, this.contextId, resolvedTarget, { timeout });
+    const located = await this.locateWithHealing(resolvedTarget, "selectOption", { timeout });
     await this.ensureActionable(located, "selectOption", target, { timeout });
     const ref = this.getSharedRef(located.node);
     const valuesArray = Array.isArray(values) ? values : [values];
@@ -1431,7 +1549,7 @@ var Page = class {
    * ```
    */
   async waitForSelector(target, options) {
-    const timeout = options?.timeout ?? this.config.timeout;
+    const timeout = this.adaptTimeout(options?.timeout ?? this.config.timeout);
     const state = options?.state ?? "visible";
     if (state === "hidden") {
       await waitFor(
@@ -1561,7 +1679,7 @@ var Page = class {
   async see(target, options) {
     const timeout = options?.timeout ?? this.config.timeout;
     const startTime = Date.now();
-    const located = await locateElement(this.session, this.contextId, target, { timeout });
+    const located = await this.locateWithHealing(target, "see", { timeout });
     const ref = this.getSharedRef(located.node);
     const elapsed = Date.now() - startTime;
     const remaining = Math.max(timeout - elapsed, 5e3);
@@ -1751,10 +1869,137 @@ var Page = class {
   // -----------------------------------------------------------------------
   // Private helpers
   // -----------------------------------------------------------------------
+  /**
+   * Locate an element with automatic self-healing on failure.
+   *
+   * When locateElement() throws ElementNotFoundError, this method:
+   * 1. Captures a lightweight DOM snapshot of the page
+   * 2. Calls healSelector() to find a likely replacement
+   * 3. If healed, retries with the new selector and logs a warning
+   *
+   * Zero user configuration. Zero new API. Just smarter element finding.
+   */
+  async locateWithHealing(target, action, options) {
+    const adaptedOptions = { timeout: this.adaptTimeout(options.timeout) };
+    try {
+      return await locateElement(this.session, this.contextId, target, adaptedOptions);
+    } catch (err) {
+      if (!(err instanceof ElementNotFoundError)) throw err;
+      const selectorText = this.extractSelector(target);
+      if (!selectorText) throw err;
+      try {
+        const aiPkg = "browsecraft-ai";
+        const { healSelector } = await import(aiPkg);
+        const snapshot = await this.captureSnapshot();
+        const aiConfig = resolveAIConfig(this.config.ai);
+        const result = await healSelector(selectorText, snapshot, {
+          context: `${action} action on ${typeof target === "string" ? target : selectorText}`,
+          useAI: aiConfig !== null,
+          provider: aiConfig ? {
+            provider: aiConfig.provider,
+            token: "token" in aiConfig ? aiConfig.token : void 0,
+            baseUrl: "baseUrl" in aiConfig ? aiConfig.baseUrl : void 0
+          } : void 0
+        });
+        if (result.healed && result.selector) {
+          console.warn(
+            `\u26A0 [browsecraft] Self-healed: '${selectorText}' \u2192 '${result.selector}' (${result.method}, ${(result.confidence * 100).toFixed(0)}% confidence)`
+          );
+          return await locateElement(
+            this.session,
+            this.contextId,
+            { selector: result.selector },
+            adaptedOptions
+          );
+        }
+      } catch {
+      }
+      throw err;
+    }
+  }
+  /**
+   * Capture a lightweight DOM snapshot for self-healing.
+   * Extracts interactive elements with their attributes for matching.
+   */
+  async captureSnapshot() {
+    const [url, title] = await Promise.all([this.url(), this.title()]);
+    const result = await this.session.script.callFunction({
+      functionDeclaration: `function() {
+				const selectors = 'button, a, input, select, textarea, [role], [data-testid], [data-test-id], [aria-label], label, h1, h2, h3, h4, h5, h6, img, nav, form';
+				const els = document.querySelectorAll(selectors);
+				const elements = [];
+
+				for (const el of els) {
+					if (elements.length >= 100) break;
+
+					const rect = el.getBoundingClientRect();
+					if (rect.width === 0 && rect.height === 0) continue;
+
+					const id = el.id || undefined;
+					const classes = el.className && typeof el.className === 'string'
+						? el.className.split(/\\s+/).filter(Boolean)
+						: undefined;
+					const text = (el.innerText || '').trim().slice(0, 200) || undefined;
+					const ariaLabel = el.getAttribute('aria-label') || undefined;
+					const role = el.getAttribute('role') || undefined;
+					const type = el.getAttribute('type') || undefined;
+					const name = el.getAttribute('name') || undefined;
+					const placeholder = el.getAttribute('placeholder') || undefined;
+					const href = el.tagName === 'A' ? el.getAttribute('href') || undefined : undefined;
+					const testId = el.getAttribute('data-testid') || el.getAttribute('data-test-id') || undefined;
+
+					// Generate a unique selector
+					let selector;
+					if (id) selector = '#' + id;
+					else if (testId) selector = '[data-testid="' + testId + '"]';
+					else {
+						const tag = el.tagName.toLowerCase();
+						const nth = Array.from(el.parentNode?.children || []).indexOf(el);
+						selector = tag + (classes && classes.length ? '.' + classes[0] : '') + ':nth-child(' + (nth + 1) + ')';
+					}
+
+					elements.push({
+						tag: el.tagName.toLowerCase(),
+						id, classes, text, ariaLabel, role, type, name, placeholder, href, testId, selector
+					});
+				}
+				return elements;
+			}`,
+      target: { context: this.contextId },
+      awaitPromise: false
+    });
+    let elements = [];
+    if (result.type === "success" && result.result?.type === "array") {
+      const arr = result.result.value;
+      elements = arr.map((item) => this.deserializeRemoteValue(item)).filter(
+        (e) => e !== null && typeof e === "object" && "tag" in e && "selector" in e
+      );
+    }
+    return { url, title, elements };
+  }
+  /**
+   * Extract a CSS selector string from a target, if applicable.
+   * Only returns a value for selector-based or CSS-like targets.
+   */
+  extractSelector(target) {
+    if (typeof target === "string") {
+      return target.match(/^[#.\[]/) || target.includes(":") ? target : null;
+    }
+    return target.selector ?? target.testId ? `[data-testid="${target.testId}"]` : null;
+  }
   /**
    * Ensure an element is actionable (visible + enabled) before interacting.
    * Throws a rich ElementNotActionableError if it's not ready within the timeout.
    */
+  /**
+   * Apply the adaptive timing multiplier to a timeout.
+   * On slow environments, timeouts automatically scale up so tests don't
+   * flake. On fast machines the multiplier stays 1.0 — no overhead.
+   * @internal
+   */
+  adaptTimeout(ms) {
+    return Math.round(ms * this.timingMultiplier);
+  }
   async ensureActionable(located, action, target, options) {
     const ref = this.getSharedRef(located.node);
     const targetDesc = typeof target === "string" ? target : describeTarget2(target);
@@ -1763,7 +2008,7 @@ var Page = class {
       this.contextId,
       ref,
       targetDesc,
-      { timeout: Math.min(options.timeout, 5e3) },
+      { timeout: this.adaptTimeout(Math.min(options.timeout, 5e3)) },
       {
         visible: true,
         enabled: options.enabled !== false
@@ -2356,11 +2601,13 @@ var Browser = class _Browser {
     try {
       const result = await this.session.send("browser.createUserContext", {});
       const userContext = result.userContext;
+      await this.closeOrphanBlankTabs();
       return new BrowserContext(this.session, this.config, userContext);
     } catch (err) {
       console.warn(
         `[browsecraft] Warning: browser.createUserContext is not supported. Pages will share cookies/storage. ${err instanceof Error ? err.message : String(err)}`
       );
+      await this.closeOrphanBlankTabs();
       return new BrowserContext(this.session, this.config, null);
     }
   }
@@ -2381,6 +2628,27 @@ var Browser = class _Browser {
   getConfig() {
     return { ...this.config };
   }
+  /**
+   * Close any about:blank tabs that aren't tracked as pages.
+   * Chrome (and some other browsers) always opens with an initial blank tab.
+   * When we create an isolated context, that tab can't be reused (wrong context)
+   * and just sits there as a ghost window. This method cleans it up.
+   * @internal
+   */
+  async closeOrphanBlankTabs() {
+    try {
+      const tree = await this.session.browsingContext.getTree();
+      const contexts = tree.contexts ?? [];
+      for (const ctx of contexts) {
+        const alreadyTracked = this.pages.some((p) => p.contextId === ctx.context);
+        if (!alreadyTracked && ctx.url === "about:blank") {
+          await this.session.browsingContext.close({ context: ctx.context }).catch(() => {
+          });
+        }
+      }
+    } catch {
+    }
+  }
   /**
    * Try to find and reuse an existing about:blank tab (Chrome opens one on startup).
    * Returns the context ID if found, or null if no idle tab exists.
@@ -2417,10 +2685,10 @@ var BrowserContext = class {
   }
   /** Create a new page in this context. */
   async newPage() {
-    const params = { type: "tab" };
-    if (this.userContext) {
-      params.userContext = this.userContext;
-    }
+    const params = {
+      type: "tab",
+      ...this.userContext ? { userContext: this.userContext } : {}
+    };
     const result = await this.session.browsingContext.create(params);
     const contextId = result.context;
     await applyViewport(this.session, contextId, this.config);
@@ -2645,6 +2913,6 @@ async function captureScreenshot(page, testCase, outputDir) {
   return filePath;
 }
 
-export { BrowsecraftError, Browser, BrowserContext, ElementHandle, ElementNotActionableError, ElementNotFoundError, NetworkError, Page, TimeoutError, afterAll, afterEach, beforeAll, beforeEach, defineConfig, describe, resetTestState, resolveConfig, runAfterAllHooks, runTest, sleep, test, testRegistry, waitFor };
-//# sourceMappingURL=chunk-P3F7FGFM.js.map
-//# sourceMappingURL=chunk-P3F7FGFM.js.map
+export { BrowsecraftError, Browser, BrowserContext, ElementHandle, ElementNotActionableError, ElementNotFoundError, NetworkError, Page, TimeoutError, afterAll, afterEach, beforeAll, beforeEach, classifyFailure, defineConfig, describe, resetTestState, resolveAIConfig, resolveConfig, runAfterAllHooks, runTest, sleep, test, testRegistry, waitFor };
+//# sourceMappingURL=chunk-GAN2YUTJ.js.map
+//# sourceMappingURL=chunk-GAN2YUTJ.js.map