retestkit 1.4.1

package/src/playwright-client/index.ts

@@ -0,0 +1,392 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import type { Logger } from "../logger.js";
+import type { Config } from "../schemas/config.js";
+import {
+  type PlaywrightToolMapping,
+  type PlaywrightToolCallResult,
+  type PlaywrightSnapshot,
+  type PlaywrightScreenshot,
+  CANONICAL_TOOL_NAMES,
+  TOOL_NAME_VARIANTS,
+  REQUIRED_TOOLS,
+} from "./types.js";
+
+export type { PlaywrightToolMapping, PlaywrightSnapshot, PlaywrightScreenshot };
+
+export interface TypeOptions {
+  submit?: boolean;
+  slowly?: boolean;
+}
+
+export interface PlaywrightClient {
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  isConnected(): boolean;
+  getToolMapping(): PlaywrightToolMapping | null;
+  callTool(
+    canonicalName: keyof PlaywrightToolMapping,
+    args: Record<string, unknown>
+  ): Promise<PlaywrightToolCallResult>;
+  snapshot(): Promise<PlaywrightSnapshot>;
+  screenshot(): Promise<PlaywrightScreenshot>;
+  navigate(url: string): Promise<void>;
+  click(element: string, ref: string): Promise<void>;
+  type(element: string, ref: string, text: string, options?: TypeOptions): Promise<void>;
+  fill(element: string, ref: string, value: string): Promise<void>;
+  hover(element: string, ref: string): Promise<void>;
+  select(element: string, ref: string, values: string[]): Promise<void>;
+  evaluate(fn: string, element?: string, ref?: string): Promise<unknown>;
+  press(key: string): Promise<void>;
+  scroll(x: number, y: number): Promise<void>;
+  wait(ms: number): Promise<void>;
+}
+
+export function createPlaywrightClient(
+  config: Config,
+  logger: Logger
+): PlaywrightClient {
+  let client: Client | null = null;
+  let transport: StdioClientTransport | null = null;
+  let process: ChildProcess | null = null;
+  let toolMapping: PlaywrightToolMapping | null = null;
+  let connected = false;
+
+  async function discoverTools(): Promise<PlaywrightToolMapping> {
+    if (!client) {
+      throw new Error("Client not connected");
+    }
+
+    const response = await client.listTools();
+    const availableTools = new Set(response.tools.map((t) => t.name));
+    const mapping: Partial<PlaywrightToolMapping> = {};
+
+    logger.debug("Discovered Playwright MCP tools", {
+      count: response.tools.length,
+      tools: response.tools.map((t) => t.name),
+    });
+
+    for (const canonical of CANONICAL_TOOL_NAMES) {
+      const variants = TOOL_NAME_VARIANTS[canonical];
+      const found = variants.find((v) => availableTools.has(v));
+      if (found) {
+        mapping[canonical] = found;
+        logger.debug("Mapped tool", { canonical, actual: found });
+      }
+    }
+
+    // Check for required tools
+    const missingRequired = REQUIRED_TOOLS.filter((t) => !mapping[t]);
+    if (missingRequired.length > 0) {
+      logger.warn("Missing required Playwright tools", {
+        missing: missingRequired,
+      });
+    }
+
+    // Determine implementation variant
+    const sampleTool = Object.values(mapping)[0] || "";
+    let variant = "unknown";
+    if (sampleTool.startsWith("browser_")) {
+      variant = "microsoft";
+    } else if (sampleTool.startsWith("playwright_")) {
+      variant = "anthropic";
+    } else {
+      variant = "generic";
+    }
+
+    logger.info("Playwright MCP implementation detected", {
+      variant,
+      mappedTools: Object.keys(mapping).length,
+    });
+
+    return mapping as PlaywrightToolMapping;
+  }
+
+  async function callToolInternal(
+    toolName: string,
+    args: Record<string, unknown>
+  ): Promise<PlaywrightToolCallResult> {
+    if (!client) {
+      throw new Error("Client not connected");
+    }
+
+    logger.debug("Calling Playwright tool", { tool: toolName, args });
+
+    try {
+      const result = await client.callTool({ name: toolName, arguments: args });
+      return result as PlaywrightToolCallResult;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      logger.error("Playwright tool call failed", {
+        tool: toolName,
+        error: message,
+      });
+      return {
+        content: [{ type: "text", text: `Error: ${message}` }],
+        isError: true,
+      };
+    }
+  }
+
+  return {
+    async connect(): Promise<void> {
+      if (connected) {
+        logger.warn("Playwright client already connected");
+        return;
+      }
+
+      logger.info("Connecting to Playwright MCP server", {
+        command: config.playwrightMcpCommand,
+        args: config.playwrightMcpArgs,
+      });
+
+      transport = new StdioClientTransport({
+        command: config.playwrightMcpCommand,
+        args: config.playwrightMcpArgs,
+      });
+
+      client = new Client(
+        { name: "testing-mcp", version: "0.1.0" },
+        { capabilities: {} }
+      );
+
+      await client.connect(transport);
+      connected = true;
+
+      toolMapping = await discoverTools();
+
+      logger.info("Playwright MCP client connected");
+    },
+
+    async disconnect(): Promise<void> {
+      if (!connected) {
+        return;
+      }
+
+      logger.info("Disconnecting from Playwright MCP server");
+
+      try {
+        await client?.close();
+      } catch (error) {
+        logger.warn("Error closing client", {
+          error: error instanceof Error ? error.message : "Unknown error",
+        });
+      }
+
+      if (process) {
+        process.kill();
+        process = null;
+      }
+
+      client = null;
+      transport = null;
+      toolMapping = null;
+      connected = false;
+
+      logger.info("Playwright MCP client disconnected");
+    },
+
+    isConnected(): boolean {
+      return connected;
+    },
+
+    getToolMapping(): PlaywrightToolMapping | null {
+      return toolMapping;
+    },
+
+    async callTool(
+      canonicalName: keyof PlaywrightToolMapping,
+      args: Record<string, unknown>
+    ): Promise<PlaywrightToolCallResult> {
+      if (!toolMapping) {
+        throw new Error("Tool mapping not initialized");
+      }
+
+      const actualName = toolMapping[canonicalName];
+      if (!actualName) {
+        throw new Error(`Tool ${canonicalName} not available`);
+      }
+
+      return callToolInternal(actualName, args);
+    },
+
+    async snapshot(): Promise<PlaywrightSnapshot> {
+      const result = await this.callTool("snapshot", {});
+
+      if (result.isError) {
+        throw new Error(result.content[0]?.text || "Snapshot failed");
+      }
+
+      const text = result.content.find((c) => c.type === "text")?.text || "";
+      // Parse the snapshot response - format varies by implementation
+      try {
+        const parsed = JSON.parse(text);
+        return {
+          url: parsed.url || "",
+          title: parsed.title || "",
+          content: parsed.content || text,
+        };
+      } catch {
+        // Microsoft Playwright MCP returns markdown format:
+        // "- Page URL: https://example.com/\n- Page Title: Example\n- Page Snapshot:\n```yaml\n..."
+        // Extract URL and title from markdown format
+        let url = "";
+        let title = "";
+
+        const urlMatch = text.match(/Page URL:\s*(\S+)/);
+        if (urlMatch) {
+          url = urlMatch[1];
+        }
+
+        const titleMatch = text.match(/Page Title:\s*(.+?)(?:\n|$)/);
+        if (titleMatch) {
+          title = titleMatch[1].trim();
+        }
+
+        return {
+          url,
+          title,
+          content: text,
+        };
+      }
+    },
+
+    async screenshot(): Promise<PlaywrightScreenshot> {
+      const result = await this.callTool("screenshot", {});
+
+      if (result.isError) {
+        throw new Error(result.content[0]?.text || "Screenshot failed");
+      }
+
+      const imageContent = result.content.find((c) => c.type === "image");
+      if (!imageContent || !imageContent.data) {
+        throw new Error("No image data in screenshot response");
+      }
+
+      return {
+        data: imageContent.data,
+        mimeType: imageContent.mimeType || "image/png",
+      };
+    },
+
+    async navigate(url: string): Promise<void> {
+      const result = await this.callTool("navigate", { url });
+
+      if (result.isError) {
+        throw new Error(result.content[0]?.text || "Navigation failed");
+      }
+    },
+
+    async click(element: string, ref: string): Promise<void> {
+      const result = await this.callTool("click", { element, ref });
+
+      if (result.isError) {
+        throw new Error(result.content[0]?.text || "Click failed");
+      }
+    },
+
+    async type(element: string, ref: string, text: string, options?: { submit?: boolean; slowly?: boolean }): Promise<void> {
+      const result = await this.callTool("type", {
+        element,
+        ref,
+        text,
+        submit: options?.submit ?? false,
+        slowly: options?.slowly ?? false,
+      });
+
+      if (result.isError) {
+        throw new Error(result.content[0]?.text || "Type failed");
+      }
+    },
+
+    async fill(element: string, ref: string, value: string): Promise<void> {
+      // Microsoft Playwright MCP uses browser_type for fill operations
+      // The fill operation is essentially type without slowly mode
+      const result = await this.callTool("fill", {
+        element,
+        ref,
+        text: value,
+        submit: false,
+        slowly: false,
+      });
+
+      if (result.isError) {
+        throw new Error(result.content[0]?.text || "Fill failed");
+      }
+    },
+
+    async hover(element: string, ref: string): Promise<void> {
+      const result = await this.callTool("hover", { element, ref });
+
+      if (result.isError) {
+        throw new Error(result.content[0]?.text || "Hover failed");
+      }
+    },
+
+    async select(element: string, ref: string, values: string[]): Promise<void> {
+      const result = await this.callTool("select", { element, ref, values });
+
+      if (result.isError) {
+        throw new Error(result.content[0]?.text || "Select failed");
+      }
+    },
+
+    async evaluate(fn: string, element?: string, ref?: string): Promise<unknown> {
+      const args: Record<string, unknown> = { function: fn };
+      if (element) args.element = element;
+      if (ref) args.ref = ref;
+
+      const result = await this.callTool("evaluate", args);
+
+      if (result.isError) {
+        throw new Error(result.content[0]?.text || "Evaluate failed");
+      }
+
+      const text = result.content.find((c) => c.type === "text")?.text;
+      if (text) {
+        try {
+          return JSON.parse(text);
+        } catch {
+          return text;
+        }
+      }
+      return undefined;
+    },
+
+    async press(key: string): Promise<void> {
+      // Microsoft Playwright MCP browser_press_key takes only the key, no element
+      const result = await this.callTool("press", { key });
+
+      if (result.isError) {
+        throw new Error(result.content[0]?.text || "Press failed");
+      }
+    },
+
+    async scroll(x: number, y: number): Promise<void> {
+      // scroll may not exist in Microsoft implementation - try direct tool first
+      // If it fails, fall back to evaluate
+      if (toolMapping?.scroll) {
+        const result = await this.callTool("scroll", { x, y });
+        if (!result.isError) {
+          return;
+        }
+      }
+      // Fallback: use evaluate to scroll
+      await this.evaluate(`() => window.scrollTo(${x}, ${y})`);
+    },
+
+    async wait(ms: number): Promise<void> {
+      // wait may not exist in Microsoft implementation - try direct tool first
+      // If it fails, fall back to evaluate
+      if (toolMapping?.wait) {
+        const result = await this.callTool("wait", { ms });
+        if (!result.isError) {
+          return;
+        }
+      }
+      // Fallback: use evaluate to wait
+      await this.evaluate(`() => new Promise(resolve => setTimeout(resolve, ${ms}))`);
+    },
+  };
+}

package/src/playwright-client/types.ts

@@ -0,0 +1,99 @@
+export interface PlaywrightToolMapping {
+  snapshot: string;
+  screenshot: string;
+  click: string;
+  type: string;
+  navigate: string;
+  fill: string;
+  hover: string;
+  select: string;
+  evaluate: string;
+  press: string;
+  scroll: string;
+  wait: string;
+}
+
+export interface PlaywrightTool {
+  name: string;
+  description?: string;
+  inputSchema?: unknown;
+}
+
+export interface PlaywrightToolListResponse {
+  tools: PlaywrightTool[];
+}
+
+export interface PlaywrightToolCallResult {
+  content: Array<{
+    type: "text" | "image";
+    text?: string;
+    data?: string;
+    mimeType?: string;
+  }>;
+  isError?: boolean;
+}
+
+export interface PlaywrightSnapshot {
+  url: string;
+  title: string;
+  content: string;
+}
+
+export interface PlaywrightScreenshot {
+  data: string;
+  mimeType: string;
+}
+
+export const CANONICAL_TOOL_NAMES: (keyof PlaywrightToolMapping)[] = [
+  "snapshot",
+  "screenshot",
+  "click",
+  "type",
+  "navigate",
+  "fill",
+  "hover",
+  "select",
+  "evaluate",
+  "press",
+  "scroll",
+  "wait",
+];
+
+export const TOOL_NAME_VARIANTS: Record<
+  keyof PlaywrightToolMapping,
+  string[]
+> = {
+  snapshot: ["browser_snapshot", "playwright_snapshot", "snapshot"],
+  screenshot: [
+    "browser_take_screenshot",
+    "playwright_screenshot",
+    "screenshot",
+    "browser_screenshot",
+  ],
+  click: ["browser_click", "playwright_click", "click"],
+  type: ["browser_type", "playwright_type", "type"],
+  navigate: ["browser_navigate", "playwright_navigate", "navigate"],
+  // Note: Microsoft Playwright MCP uses browser_type for fill operations too
+  fill: ["browser_type", "browser_fill", "playwright_fill", "fill"],
+  hover: ["browser_hover", "playwright_hover", "hover"],
+  // Microsoft Playwright MCP uses browser_select_option
+  select: ["browser_select_option", "browser_select", "playwright_select", "select"],
+  evaluate: [
+    "browser_evaluate",
+    "browser_run_code",
+    "playwright_evaluate",
+    "evaluate",
+  ],
+  // Microsoft Playwright MCP uses browser_press_key
+  press: ["browser_press_key", "browser_press", "playwright_press", "press"],
+  // scroll and wait may not exist in Microsoft implementation - fallback to evaluate
+  scroll: ["browser_scroll", "playwright_scroll", "scroll"],
+  wait: ["browser_wait", "playwright_wait", "wait"],
+};
+
+export const REQUIRED_TOOLS: (keyof PlaywrightToolMapping)[] = [
+  "snapshot",
+  "screenshot",
+  "click",
+  "navigate",
+];