@tontoko/fast-playwright-mcp 0.0.4

package/lib/diagnostics/enhanced-error-handler.js

@@ -0,0 +1,376 @@
+import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/diagnostics/enhanced-error-handler.ts
+import { DiagnosticBase } from "./common/index.js";
+import { DiagnosticError } from "./diagnostic-error.js";
+import { DiagnosticLevelManager } from "./diagnostic-level.js";
+import { ElementDiscovery } from "./element-discovery.js";
+import { ErrorEnrichment } from "./error-enrichment.js";
+import { PageAnalyzer } from "./page-analyzer.js";
+
+class EnhancedErrorHandler extends DiagnosticBase {
+  pageAnalyzer;
+  elementDiscovery;
+  errorEnrichment;
+  diagnosticManager;
+  errorHistory = [];
+  maxErrorHistory;
+  constructor(page, diagnosticConfig) {
+    super(page, "EnhancedErrorHandler");
+    this.pageAnalyzer = new PageAnalyzer(page);
+    this.elementDiscovery = new ElementDiscovery(page);
+    this.errorEnrichment = new ErrorEnrichment(page);
+    this.diagnosticManager = new DiagnosticLevelManager(diagnosticConfig);
+    this.maxErrorHistory = diagnosticConfig?.maxErrorHistory ?? 100;
+  }
+  async performDispose() {
+    await this.pageAnalyzer.dispose();
+    await this.elementDiscovery.dispose();
+    await this.errorEnrichment.dispose();
+  }
+  async enhancePlaywrightError(options) {
+    const { error, operation, selector, context } = options;
+    if (this.diagnosticManager.shouldSkipDiagnostics()) {
+      return error;
+    }
+    if (selector && context?.searchCriteria && this.diagnosticManager.shouldEnableFeature("alternativeSuggestions")) {
+      const enrichedError = await this.errorEnrichment.enrichElementNotFoundError({
+        originalError: error,
+        selector,
+        searchCriteria: context.searchCriteria,
+        maxAlternatives: this.diagnosticManager.getMaxAlternatives()
+      });
+      return enrichedError;
+    }
+    if (error.message.includes("Timeout")) {
+      return this.enhanceTimeoutError({
+        error,
+        operation,
+        selector,
+        timeout: context?.timeout ?? 30000
+      });
+    }
+    let pageStructure;
+    if (this.diagnosticManager.shouldEnableFeature("pageAnalysis")) {
+      pageStructure = await this.pageAnalyzer.analyzePageStructure();
+    }
+    const suggestions = pageStructure ? this.generateGeneralSuggestions(error, operation, pageStructure) : [];
+    const enhancedError = new Error(error.message);
+    enhancedError.originalError = error;
+    if (pageStructure) {
+      enhancedError.pageStructure = pageStructure;
+    }
+    enhancedError.suggestions = suggestions;
+    return enhancedError;
+  }
+  async enhanceTimeoutError(options) {
+    const { error, operation, selector } = options;
+    const enrichedError = await this.errorEnrichment.enrichTimeoutError({
+      originalError: error,
+      operation,
+      selector
+    });
+    const contextInfo = this.analyzeFrameContext();
+    enrichedError.contextInfo = contextInfo;
+    return enrichedError;
+  }
+  async enhanceContextError(options) {
+    const { error, expectedContext } = options;
+    const contextInfo = this.analyzeFrameContext();
+    const pageStructure = await this.pageAnalyzer.analyzePageStructure();
+    const suggestions = [
+      `Expected element in ${expectedContext} context`,
+      `Found ${contextInfo.availableFrames} available frames`,
+      "Try switching to the correct frame context"
+    ];
+    if (pageStructure.iframes.detected) {
+      suggestions.push("element might be in a different frame - use frameLocator()");
+    }
+    const enhancedError = new Error(error.message);
+    enhancedError.originalError = error;
+    enhancedError.contextInfo = contextInfo;
+    enhancedError.pageStructure = pageStructure;
+    enhancedError.suggestions = suggestions;
+    return enhancedError;
+  }
+  async enhancePerformanceError(options) {
+    const { operation, executionTime, performanceThreshold } = options;
+    const pageStructure = await this.pageAnalyzer.analyzePageStructure();
+    const exceededThreshold = executionTime > performanceThreshold;
+    const performanceInfo = {
+      executionTime,
+      exceededThreshold,
+      threshold: performanceThreshold
+    };
+    const suggestions = [
+      `Operation took longer than expected (${executionTime}ms vs ${performanceThreshold}ms threshold)`,
+      "Consider optimizing page load performance",
+      "Check for heavy JavaScript execution or network delays"
+    ];
+    if (pageStructure.modalStates.blockedBy.length > 0) {
+      suggestions.push("Modal dialogs may be causing delays");
+    }
+    const error = new Error(`Performance issue: ${operation} operation exceeded threshold`);
+    error.performanceInfo = performanceInfo;
+    error.pageStructure = pageStructure;
+    error.suggestions = suggestions;
+    return error;
+  }
+  async enhanceToolError(options) {
+    const { toolName, error, toolArgs } = options;
+    const pageStructure = await this.pageAnalyzer.analyzePageStructure();
+    const toolContext = {
+      toolName,
+      toolArgs: toolArgs ?? {}
+    };
+    const suggestions = this.generateToolSpecificSuggestions(toolName, error, pageStructure);
+    const enhancedError = new Error(error.message);
+    enhancedError.originalError = error;
+    enhancedError.toolContext = toolContext;
+    enhancedError.pageStructure = pageStructure;
+    enhancedError.suggestions = suggestions;
+    return enhancedError;
+  }
+  analyzeFrameContext() {
+    const page = this.getPage();
+    const frames = page.frames();
+    const mainFrame = page.mainFrame();
+    return {
+      availableFrames: frames.length,
+      currentFrame: mainFrame.name() ?? "main"
+    };
+  }
+  generateGeneralSuggestions(error, operation, pageStructure) {
+    const suggestions = [];
+    if (pageStructure.modalStates.blockedBy.length > 0) {
+      suggestions.push(`Page has active modal - handle before performing ${operation}`);
+    }
+    if (pageStructure.iframes.detected) {
+      suggestions.push("Check if target element is inside an iframe");
+    }
+    if (error.message.includes("not found")) {
+      suggestions.push("Element selector might be incorrect or element not yet loaded");
+      suggestions.push("Try waiting for element to be visible before interacting");
+    }
+    return suggestions;
+  }
+  generateToolSpecificSuggestions(toolName, error, pageStructure) {
+    const suggestions = [];
+    switch (toolName) {
+      case "browser_click":
+        if (error.message.includes("not enabled")) {
+          suggestions.push("Element appears to be disabled");
+          suggestions.push("Wait for element to become enabled or check if it should be enabled");
+        }
+        if (error.message.includes("not visible")) {
+          suggestions.push("Element is not visible - check CSS display/visibility properties");
+        }
+        break;
+      case "browser_type":
+        if (error.message.includes("not editable")) {
+          suggestions.push("Element is not editable - ensure it is an input field");
+          suggestions.push("Check if element has readonly attribute");
+        }
+        break;
+      case "browser_select_option":
+        suggestions.push("Verify that the select element contains the specified option");
+        suggestions.push("Check option values and text content");
+        break;
+      default:
+        suggestions.push(`Consider tool-specific requirements for ${toolName}`);
+    }
+    if (pageStructure.modalStates.blockedBy.length > 0) {
+      suggestions.push(`Modal state blocking ${toolName} operation`);
+    }
+    return suggestions;
+  }
+  createDiagnosticError(error, component, operation, executionTime, memoryUsage) {
+    const diagnosticError = DiagnosticError.from(error, component, operation, {
+      executionTime,
+      memoryUsage,
+      performanceImpact: executionTime && executionTime > 1000 ? "high" : "low"
+    });
+    this.addToErrorHistory(diagnosticError, component);
+    return diagnosticError;
+  }
+  async processUnifiedError(error, component, operation, context) {
+    const startTime = Date.now();
+    try {
+      let diagnosticError;
+      if (error instanceof DiagnosticError) {
+        diagnosticError = error;
+      } else {
+        diagnosticError = this.createDiagnosticError(error, component, operation, context?.executionTime, context?.memoryUsage);
+      }
+      if (context?.performanceThreshold && context?.executionTime && context.executionTime > context.performanceThreshold) {
+        const perfError = DiagnosticError.performance(`Operation ${operation} exceeded performance threshold`, component, operation, context.executionTime, context.performanceThreshold);
+        diagnosticError.suggestions.push(...perfError.suggestions);
+      }
+      if (this.diagnosticManager.shouldEnableFeature("alternativeSuggestions")) {
+        const contextualSuggestions = await this.generateContextualSuggestions(diagnosticError, component, operation, context);
+        diagnosticError.suggestions.push(...contextualSuggestions);
+      }
+      const similarErrors = this.findSimilarErrors(diagnosticError, component);
+      if (similarErrors.length > 0) {
+        const patternSuggestions = this.generatePatternBasedSuggestions(similarErrors);
+        diagnosticError.suggestions.push(...patternSuggestions);
+      }
+      return diagnosticError;
+    } catch {
+      return DiagnosticError.from(error, component, operation, {
+        executionTime: Date.now() - startTime
+      });
+    }
+  }
+  async generateContextualSuggestions(_error, component, operation, context) {
+    const suggestions = [];
+    try {
+      const pageStructure = await this.pageAnalyzer.analyzePageStructure();
+      this.addComponentSpecificSuggestions(suggestions, component, pageStructure, context);
+      this.addOperationSpecificSuggestions(suggestions, operation, pageStructure);
+    } catch {}
+    return suggestions;
+  }
+  addComponentSpecificSuggestions(suggestions, component, pageStructure, context) {
+    switch (component) {
+      case "PageAnalyzer":
+        this.addPageAnalyzerSuggestions(suggestions, pageStructure);
+        break;
+      case "ElementDiscovery":
+        this.addElementDiscoverySuggestions(suggestions, pageStructure, context);
+        break;
+      case "ResourceManager":
+        this.addResourceManagerSuggestions(suggestions, context);
+        break;
+      default:
+        break;
+    }
+  }
+  addPageAnalyzerSuggestions(suggestions, pageStructure) {
+    if (pageStructure.elements.totalVisible > 1e4) {
+      suggestions.push("Page has many elements - consider using parallel analysis");
+    }
+    if (pageStructure.iframes.detected) {
+      suggestions.push("Multiple iframes detected - they may affect analysis performance");
+    }
+  }
+  addElementDiscoverySuggestions(suggestions, pageStructure, context) {
+    if (context?.selector && pageStructure.elements.missingAria > 0) {
+      suggestions.push("Many elements lack ARIA attributes - try text-based selectors");
+    }
+    if (pageStructure.modalStates.blockedBy.length > 0) {
+      suggestions.push("Modal dialogs may be hiding target elements");
+    }
+  }
+  addResourceManagerSuggestions(suggestions, context) {
+    if (context?.memoryUsage && typeof context.memoryUsage === "number" && context.memoryUsage > 50 * 1024 * 1024) {
+      suggestions.push("High memory usage detected - consider more aggressive cleanup");
+    }
+  }
+  addOperationSpecificSuggestions(suggestions, operation, pageStructure) {
+    if (operation.includes("parallel") && pageStructure.elements.totalVisible < 1000) {
+      suggestions.push("Parallel analysis may not be beneficial for simple pages");
+    }
+    if (operation.includes("timeout")) {
+      suggestions.push("Consider adjusting timeout thresholds based on page complexity");
+    }
+  }
+  addToErrorHistory(error, component) {
+    this.errorHistory.push({
+      error,
+      timestamp: Date.now(),
+      component,
+      resolved: false
+    });
+    if (this.errorHistory.length > this.maxErrorHistory) {
+      this.errorHistory = this.errorHistory.slice(-this.maxErrorHistory);
+    }
+  }
+  findSimilarErrors(error, component) {
+    const timeWindow = 300000;
+    const now = Date.now();
+    return this.errorHistory.filter((entry) => entry.component === component && entry.error.operation === error.operation && now - entry.timestamp < timeWindow).map((entry) => entry.error).slice(-5);
+  }
+  generatePatternBasedSuggestions(similarErrors) {
+    const suggestions = [];
+    if (similarErrors.length >= 3) {
+      suggestions.push(`This error has occurred ${similarErrors.length} times recently - consider reviewing the operation`);
+      const commonSuggestions = this.findCommonSuggestions(similarErrors);
+      if (commonSuggestions.length > 0) {
+        suggestions.push("Common resolution patterns:");
+        suggestions.push(...commonSuggestions.slice(0, 3));
+      }
+    }
+    return suggestions;
+  }
+  findCommonSuggestions(errors) {
+    const suggestionCounts = new Map;
+    for (const error of errors) {
+      for (const suggestion of error.suggestions) {
+        const count = suggestionCounts.get(suggestion) ?? 0;
+        suggestionCounts.set(suggestion, count + 1);
+      }
+    }
+    return Array.from(suggestionCounts.entries()).filter(([, count]) => count > 1).sort(([, a], [, b]) => b - a).map(([suggestion]) => suggestion);
+  }
+  markErrorResolved(errorId) {
+    const entry = this.errorHistory.find((e) => e.error.timestamp.toString() === errorId || e.error.message.includes(errorId));
+    if (entry) {
+      entry.resolved = true;
+    }
+  }
+  getErrorStatistics() {
+    const now = Date.now();
+    const recentTimeWindow = 600000;
+    const recentErrors = this.errorHistory.filter((e) => now - e.timestamp < recentTimeWindow);
+    const resolvedErrors = this.errorHistory.filter((e) => e.resolved);
+    const errorsByComponent = {
+      PageAnalyzer: 0,
+      ElementDiscovery: 0,
+      ResourceManager: 0,
+      ErrorHandler: 0,
+      ConfigManager: 0,
+      UnifiedSystem: 0,
+      InitializationManager: 0
+    };
+    const errorsByOperation = {};
+    for (const entry of this.errorHistory) {
+      errorsByComponent[entry.component]++;
+      const operation = entry.error.operation;
+      errorsByOperation[operation] = (errorsByOperation[operation] ?? 0) + 1;
+    }
+    return {
+      totalErrors: this.errorHistory.length,
+      errorsByComponent,
+      errorsByOperation,
+      resolutionRate: this.errorHistory.length > 0 ? resolvedErrors.length / this.errorHistory.length : 1,
+      recentErrorRate: recentErrors.length / Math.max(this.errorHistory.length, 1)
+    };
+  }
+  clearErrorHistory() {
+    this.errorHistory = [];
+  }
+  getRecentErrors(limit = 10) {
+    return this.errorHistory.slice(-limit);
+  }
+}
+export {
+  EnhancedErrorHandler
+};

package/lib/diagnostics/error-enrichment.js

@@ -0,0 +1,157 @@
+import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/diagnostics/error-enrichment.ts
+import { deduplicate } from "../utils/array-utils.js";
+import { createDisposableManager } from "../utils/disposable-manager.js";
+import { DiagnosticBase } from "./common/diagnostic-base.js";
+import { generateSuggestions } from "./common/error-enrichment-utils.js";
+import { ElementDiscovery } from "./element-discovery.js";
+import { PageAnalyzer } from "./page-analyzer.js";
+
+class ErrorEnrichment extends DiagnosticBase {
+  pageAnalyzer;
+  elementDiscovery;
+  disposableManager = createDisposableManager("ErrorEnrichment");
+  constructor(page) {
+    super(page, "ErrorEnrichment");
+    this.pageAnalyzer = this.disposableManager.register(new PageAnalyzer(page));
+    this.elementDiscovery = this.disposableManager.register(new ElementDiscovery(page));
+  }
+  async performDispose() {
+    await this.disposableManager.dispose();
+  }
+  async enrichElementNotFoundError(options) {
+    const { originalError, selector, searchCriteria, maxAlternatives } = options;
+    const [alternatives, pageStructure] = await Promise.all([
+      searchCriteria ? this.elementDiscovery.findAlternativeElements({
+        originalSelector: selector,
+        searchCriteria,
+        maxResults: maxAlternatives
+      }) : Promise.resolve([]),
+      this.pageAnalyzer.analyzePageStructure()
+    ]);
+    const suggestions = this.generateElementNotFoundSuggestions(pageStructure, alternatives);
+    const enrichedError = new Error(this.enhanceErrorMessage(originalError, alternatives));
+    enrichedError.originalError = originalError;
+    enrichedError.alternatives = alternatives;
+    enrichedError.pageStructure = pageStructure;
+    enrichedError.diagnosticInfo = pageStructure;
+    enrichedError.suggestions = suggestions;
+    return enrichedError;
+  }
+  async enrichTimeoutError(options) {
+    const { originalError, operation, selector } = options;
+    const pageStructure = await this.pageAnalyzer.analyzePageStructure();
+    const suggestions = this.generateTimeoutSuggestions(pageStructure, operation, selector);
+    const enrichedError = new Error(originalError.message);
+    enrichedError.originalError = originalError;
+    enrichedError.pageStructure = pageStructure;
+    enrichedError.diagnosticInfo = pageStructure;
+    enrichedError.suggestions = suggestions;
+    return enrichedError;
+  }
+  async enrichBatchFailureError(options) {
+    const { originalError, failedStep, executedSteps } = options;
+    const pageStructure = await this.pageAnalyzer.analyzePageStructure();
+    const suggestions = this.generateBatchFailureSuggestions(pageStructure, failedStep);
+    const enrichedError = new Error(originalError.message);
+    enrichedError.originalError = originalError;
+    enrichedError.pageStructure = pageStructure;
+    enrichedError.diagnosticInfo = pageStructure;
+    enrichedError.suggestions = suggestions;
+    enrichedError.batchContext = {
+      failedStep,
+      executedSteps
+    };
+    return enrichedError;
+  }
+  enhanceErrorMessage(originalError, alternatives) {
+    let message = originalError.message;
+    if (alternatives.length > 0) {
+      message += `
+
+Alternative elements found:`;
+      for (const [index, alt] of alternatives.entries()) {
+        message += `
+${index + 1}. ${alt.selector} (confidence: ${(alt.confidence * 100).toFixed(0)}%) - ${alt.reason}`;
+      }
+    }
+    return message;
+  }
+  generateElementNotFoundSuggestions(pageStructure, alternatives) {
+    const suggestions = [];
+    if (alternatives.length > 0) {
+      suggestions.push(`Try using one of the ${alternatives.length} alternative elements found`);
+      if (alternatives[0].confidence > 0.8) {
+        suggestions.push(`High confidence match available: ${alternatives[0].selector}`);
+      }
+    }
+    const commonSuggestions = generateSuggestions(new Error("Element not found"), {
+      operation: "findElement",
+      component: "ErrorEnrichment"
+    });
+    suggestions.push(...commonSuggestions);
+    if (pageStructure.iframes.detected) {
+      suggestions.push("Element might be inside an iframe");
+      if (pageStructure.iframes.inaccessible.length > 0) {
+        suggestions.push("Some iframes are not accessible - check cross-origin restrictions");
+      }
+    }
+    if (pageStructure.modalStates.blockedBy.length > 0) {
+      suggestions.push("Page has active modal dialog - handle it first");
+    }
+    if (pageStructure.elements.missingAria > 0) {
+      suggestions.push("Some elements lack proper ARIA attributes - consider using text-based selectors");
+    }
+    return deduplicate(suggestions);
+  }
+  generateTimeoutSuggestions(pageStructure, operation, selector) {
+    const commonSuggestions = generateSuggestions(new Error("timeout"), {
+      operation,
+      component: "ErrorEnrichment",
+      selector
+    });
+    const suggestions = [...commonSuggestions];
+    if (pageStructure.modalStates.blockedBy.length > 0) {
+      suggestions.push(`Page has active modal dialog - handle it before performing ${operation}`);
+    }
+    if (pageStructure.iframes.detected) {
+      suggestions.push("Element might be inside an iframe");
+    }
+    suggestions.push(`Wait for page load completion before performing ${operation}`);
+    return deduplicate(suggestions);
+  }
+  generateBatchFailureSuggestions(pageStructure, failedStep) {
+    const suggestions = [];
+    suggestions.push(`Batch execution failed at step ${failedStep.stepIndex} (${failedStep.toolName})`);
+    if (pageStructure.modalStates.blockedBy.length > 0) {
+      suggestions.push("Modal dialog detected - may block subsequent operations");
+    }
+    if (failedStep.selector) {
+      suggestions.push(`Failed selector: ${failedStep.selector} - check element availability`);
+    }
+    suggestions.push("Consider adding wait steps between operations");
+    suggestions.push("Verify page state changes after each navigation step");
+    return suggestions;
+  }
+}
+export {
+  ErrorEnrichment
+};