@wdio/mcp 3.4.3 → 3.5.0

package/README.md

@@ -797,6 +797,44 @@ The generated script reconstructs the full session — including capabilities, n
 standalone `import { remote } from 'webdriverio'` file. For BrowserStack sessions it includes the full try/catch/finally
 with automatic session result marking.
 
+### Trace Recording
+
+Passing `trace: true` to `start_session` produces a Playwright-compatible `.trace` zip in the `.trace/` directory when
+the session closes. The zip is playable at [player.vibium.dev](https://player.vibium.dev) and shows a filmstrip of
+screenshots alongside the action timeline.
+
+**How screenshots are timed**
+
+Appium's `takeScreenshot` round-trip takes 700–1300 ms on a local emulator, which is long enough for the previous
+action's animations to settle. We exploit this: each screenshot is captured **before** the next action fires, so what
+the Appium server returns is already the settled result of the prior action.
+
+The tricky part is making the trace player show that screenshot under the right action. The player associates a
+`screencast-frame` event with whichever action's time window contains the frame's `timestamp` field. If the timestamp
+is set to "now" (capture time), it falls before the current action's `startTime` and the player labels it as the
+*before* state of the next action — one action out of sync.
+
+The fix: stamp each `screencast-frame` with `lastAfterEndTime` — the `endTime` of the action that just completed. That
+places the frame inside the previous action's window, so the player shows it as the result of that action, not the
+precursor to the next one.
+
+```
+Timeline (monotonic ms):
+
+  prev.endTime ← frame timestamp stamped here
+        │
+        │   [screenshot captured here — shows settled state after prev action]
+        │
+  curr.startTime
+        │
+        │   [action executes]
+        │
+  curr.endTime ← next frame will be stamped here
+```
+
+The final screenshot at session close is stamped with the last action's `endTime`, so it renders under that action
+rather than appearing as an orphaned frame after the timeline ends.
+
 ## Troubleshooting
 
 **Browser automation not working?**

package/lib/server.js

@@ -46,7 +46,7 @@ var package_default = {
     type: "git",
     url: "git://github.com/webdriverio/mcp.git"
   },
-  version: "3.4.2",
+  version: "3.4.4",
   description: "MCP server with WebdriverIO for browser and mobile app automation (iOS/Android via Appium)",
   main: "./lib/server.js",
   module: "./lib/server.js",
@@ -59,10 +59,15 @@ var package_default = {
     "./snapshot": {
       import: "./lib/snapshot.js",
       types: "./lib/snapshot.d.ts"
+    },
+    "./trace": {
+      import: "./lib/trace.js",
+      types: "./lib/trace.d.ts"
     }
   },
   bin: {
-    "wdio-mcp": "lib/server.js"
+    "wdio-mcp": "lib/server.js",
+    "wdio-show-trace": "lib/show-trace.js"
   },
   license: "MIT",
   publishConfig: {
@@ -95,11 +100,14 @@ var package_default = {
     sharp: "^0.34.5",
     webdriverio: "^9.27.0",
     xpath: "^0.0.34",
+    yazl: "^3.3.1",
     zod: "^4.3.6"
   },
   devDependencies: {
     "@release-it/conventional-changelog": "^10.0.6",
     "@types/node": "^20.19.37",
+    "@types/yauzl": "^2.10.3",
+    "@types/yazl": "^3.3.1",
     "@wdio/eslint": "^0.1.3",
     "@wdio/types": "^9.27.0",
     eslint: "^9.39.4",
@@ -111,7 +119,8 @@ var package_default = {
     tsup: "^8.5.1",
     tsx: "^4.21.0",
     typescript: "~5.9.3",
-    vitest: "^4.1.2"
+    vitest: "^4.1.2",
+    yauzl: "^3.3.0"
   },
   packageManager: "pnpm@10.32.1",
   pnpm: {
@@ -119,7 +128,7 @@ var package_default = {
       "release-it>undici": "^6.24.0",
       "basic-ftp": "^5.3.1",
       lodash: "^4.18.1",
-      hono: "^4.12.17",
+      hono: "^4.12.18",
       "@hono/node-server": "^1.19.14",
       "fast-xml-parser": "^5.7.3",
       defu: "^6.1.7",
@@ -2116,6 +2125,230 @@ function withRecording(toolName, callback) {
   };
 }
 
+// src/trace/recorder.ts
+init_state();
+import sharp from "sharp";
+
+// src/trace/state.ts
+import { createRequire } from "module";
+var require2 = createRequire(import.meta.url);
+var { version: LIBRARY_VERSION } = require2("../../package.json");
+var traceSessions = /* @__PURE__ */ new Map();
+function createTraceSession(sessionId, browserName, viewport, title, sessionType = "browser") {
+  const prefix = sessionId.slice(0, 8);
+  const session = {
+    sessionId,
+    startWallTime: Date.now(),
+    startHrTime: process.hrtime.bigint(),
+    pageId: `page@${prefix}`,
+    contextId: `context@${prefix}`,
+    callCounter: 0,
+    events: [],
+    screenshots: [],
+    browserName,
+    viewport,
+    sessionType,
+    lastAfterEndTime: 0,
+    screenshotChain: Promise.resolve()
+  };
+  session.events.push({
+    version: 8,
+    type: "context-options",
+    origin: "library",
+    libraryName: "@wdio/mcp",
+    libraryVersion: LIBRARY_VERSION,
+    browserName,
+    platform: process.platform === "darwin" ? "darwin" : process.platform === "win32" ? "windows" : "linux",
+    wallTime: session.startWallTime,
+    monotonicTime: 0,
+    sdkLanguage: "javascript",
+    title,
+    contextId: session.contextId,
+    options: { viewport }
+  });
+  traceSessions.set(sessionId, session);
+  return session;
+}
+function getTraceSession(sessionId) {
+  return traceSessions.get(sessionId);
+}
+function deleteTraceSession(sessionId) {
+  traceSessions.delete(sessionId);
+}
+function getMonotonicMs(session) {
+  return Number((process.hrtime.bigint() - session.startHrTime) / 1000000n);
+}
+
+// src/trace/tool-mapping.ts
+var TOOL_MAP = {
+  navigate: { class: "Page", method: "navigate" },
+  click_element: { class: "Element", method: "click" },
+  set_value: { class: "Element", method: "fill" },
+  scroll: { class: "Page", method: "scroll" },
+  tap_element: { class: "Element", method: "tap" },
+  swipe: { class: "Page", method: "swipe" },
+  drag_and_drop: { class: "Element", method: "dragTo" },
+  execute_script: { class: "Page", method: "evaluate" },
+  launch_chrome: { class: "Browser", method: "launch" }
+};
+function mapToolToTraceAction(toolName) {
+  return TOOL_MAP[toolName] ?? null;
+}
+function extractSelectorLabel(selector) {
+  const uiautomator = selector.match(/\.(?:text|description|textContains)\("([^"]+)"\)/);
+  if (uiautomator) return uiautomator[1];
+  if (selector.startsWith("~")) return selector.slice(1);
+  const predicate = selector.match(/(?:label|name|value)\s*==\s*"([^"]+)"/);
+  if (predicate) return predicate[1];
+  const xpath2 = selector.match(/@(?:text|label|name|content-desc)="([^"]+)"/);
+  if (xpath2) return xpath2[1];
+  return selector;
+}
+function formatActionTitle(action, params) {
+  const { class: cls, method } = action;
+  const firstKey = Object.keys(params)[0];
+  const firstVal = Object.values(params)[0];
+  if (firstVal === void 0) return `${cls}.${method}()`;
+  const raw = String(firstVal);
+  const label = firstKey === "selector" ? extractSelectorLabel(raw) : raw;
+  return `${cls}.${method}("${label.slice(0, 80)}")`;
+}
+
+// src/trace/recorder.ts
+function startTrace(sessionId, capabilities, sessionType = "browser", browserViewport) {
+  let browserName;
+  let viewport;
+  let title;
+  if (sessionType === "browser") {
+    browserName = String(capabilities.browserName ?? "chromium");
+    viewport = browserViewport ?? { width: 1920, height: 1080 };
+    title = String(capabilities.browserName ?? browserName);
+  } else {
+    browserName = "chromium";
+    const deviceName = String(capabilities["appium:deviceName"] ?? capabilities.deviceName ?? "device");
+    const platformVersion = capabilities["appium:platformVersion"] ?? capabilities.platformVersion ?? "";
+    title = `${sessionType} - ${deviceName}${platformVersion ? ` (${platformVersion})` : ""}`;
+    viewport = sessionType === "ios" ? { width: 390, height: 844 } : { width: 412, height: 915 };
+  }
+  createTraceSession(sessionId, browserName, viewport, title, sessionType);
+}
+function endTrace(_sessionId) {
+}
+async function recordInitialNavigation(sessionId, url) {
+  const traceSession = getTraceSession(sessionId);
+  if (!traceSession) return;
+  const callId = `call@${++traceSession.callCounter}`;
+  const startTime = getMonotonicMs(traceSession);
+  traceSession.events.push({
+    type: "before",
+    callId,
+    startTime,
+    class: "Page",
+    method: "navigate",
+    pageId: traceSession.pageId,
+    params: { url },
+    title: `Page.navigate("${url.slice(0, 80)}")`
+  });
+  await captureScreenshot(traceSession);
+  const navEndTime = getMonotonicMs(traceSession);
+  traceSession.events.push({
+    type: "after",
+    callId,
+    endTime: navEndTime
+  });
+  traceSession.lastAfterEndTime = navEndTime;
+}
+function withTrace(toolName, callback) {
+  return async (params, extra) => {
+    const state2 = getState();
+    const sessionId = state2.currentSession;
+    if (!sessionId) return callback(params, extra);
+    const metadata = state2.sessionMetadata.get(sessionId);
+    if (!metadata?.trace) return callback(params, extra);
+    const traceSession = getTraceSession(sessionId);
+    if (!traceSession) return callback(params, extra);
+    const action = mapToolToTraceAction(toolName);
+    if (!action) return callback(params, extra);
+    await captureScreenshot(traceSession);
+    if (traceSession.sessionType !== "browser") {
+      await new Promise((r) => setTimeout(r, 50));
+    }
+    const callId = `call@${++traceSession.callCounter}`;
+    const startTime = getMonotonicMs(traceSession);
+    traceSession.events.push({
+      type: "before",
+      callId,
+      startTime,
+      class: action.class,
+      method: action.method,
+      pageId: traceSession.pageId,
+      params,
+      title: formatActionTitle(action, params)
+    });
+    let result;
+    let actionError;
+    try {
+      result = await callback(params, extra);
+      if (result.isError) {
+        const text = result.content?.find((c) => c.type === "text")?.text;
+        actionError = text ? String(text) : "unknown error";
+      }
+    } catch (e) {
+      actionError = String(e);
+      const errorEndTime = getMonotonicMs(traceSession);
+      traceSession.events.push({
+        type: "after",
+        callId,
+        endTime: errorEndTime,
+        error: { message: actionError }
+      });
+      traceSession.lastAfterEndTime = errorEndTime;
+      throw e;
+    }
+    const endTime = getMonotonicMs(traceSession);
+    traceSession.events.push({
+      type: "after",
+      callId,
+      endTime,
+      ...actionError ? { error: { message: actionError } } : {}
+    });
+    traceSession.lastAfterEndTime = endTime;
+    return result;
+  };
+}
+function captureTraceScreenshot(sessionId, browser) {
+  const traceSession = getTraceSession(sessionId);
+  if (!traceSession) return;
+  const p = captureScreenshot(traceSession, browser);
+  traceSession.screenshotChain = traceSession.screenshotChain.then(() => p);
+}
+async function captureScreenshot(traceSession, browser) {
+  try {
+    const b = browser ?? getBrowser();
+    const base64 = await b.takeScreenshot();
+    const inputBuffer = Buffer.from(base64, "base64");
+    const image = sharp(inputBuffer);
+    const metadata = await image.metadata();
+    const width = metadata.width ?? 1280;
+    const height = metadata.height ?? 720;
+    const jpegBuffer = await image.jpeg({ quality: 60 }).toBuffer();
+    const wallTimestamp = traceSession.startWallTime + getMonotonicMs(traceSession);
+    const resourceName = `${traceSession.pageId}-${wallTimestamp}.jpeg`;
+    traceSession.screenshots.push({ resourceName, data: jpegBuffer, width, height });
+    traceSession.events.push({
+      type: "screencast-frame",
+      pageId: traceSession.pageId,
+      sha1: resourceName,
+      width,
+      height,
+      // Stamp at the previous action's endTime so the player shows this frame
+      // as the result of that action, not as the "before" state of the next one.
+      timestamp: traceSession.lastAfterEndTime
+    });
+  } catch {
+  }
+}
+
 // src/resources/browserstack-local.resource.ts
 function getLocalBinaryInfo() {
   const platform2 = process.platform;
@@ -2833,12 +3066,12 @@ var accessibilityResource = {
 
 // src/resources/screenshot.resource.ts
 init_state();
-import sharp from "sharp";
+import sharp2 from "sharp";
 var MAX_DIMENSION = 2e3;
 var MAX_FILE_SIZE_BYTES = 1024 * 1024;
 async function processScreenshot(screenshotBase64) {
   const inputBuffer = Buffer.from(screenshotBase64, "base64");
-  let image = sharp(inputBuffer);
+  let image = sharp2(inputBuffer);
   const metadata = await image.metadata();
   const width = metadata.width ?? 0;
   const height = metadata.height ?? 0;
@@ -3044,6 +3277,8 @@ import { z as z14 } from "zod";
 
 // src/session/lifecycle.ts
 init_state();
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
+import { join as join3 } from "path";
 
 // src/providers/local-browser.provider.ts
 var LocalBrowserProvider = class {
@@ -3410,7 +3645,47 @@ function getProvider(providerName, platform2) {
   return platform2 === "browser" ? localBrowserProvider : localAppiumProvider;
 }
 
+// src/trace/zip-writer.ts
+import yazl from "yazl";
+function buildTraceZip(session) {
+  return new Promise((resolve, reject) => {
+    const zipFile = new yazl.ZipFile();
+    const traceNdjson = session.events.map((e) => JSON.stringify(e)).join("\n");
+    const traceBuffer = Buffer.from(traceNdjson, "utf8");
+    zipFile.addBuffer(traceBuffer, "trace.trace");
+    zipFile.addBuffer(Buffer.alloc(0), "trace.network");
+    for (const screenshot of session.screenshots) {
+      zipFile.addBuffer(screenshot.data, `resources/${screenshot.resourceName}`);
+    }
+    zipFile.end();
+    const chunks = [];
+    zipFile.outputStream.on("data", (chunk) => chunks.push(chunk));
+    zipFile.outputStream.on("end", () => resolve(Buffer.concat(chunks)));
+    zipFile.outputStream.on("error", reject);
+  });
+}
+
 // src/session/lifecycle.ts
+async function finalizeTrace(sessionId, browser) {
+  endTrace(sessionId);
+  captureTraceScreenshot(sessionId, browser);
+  const traceSession = getTraceSession(sessionId);
+  if (!traceSession) return;
+  try {
+    await traceSession.screenshotChain;
+    const traceDir = join3(process.cwd(), ".trace");
+    mkdirSync2(traceDir, { recursive: true });
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+    const outPath = join3(traceDir, `${timestamp}-${sessionId.slice(0, 8)}.zip`);
+    const zipBuffer = await buildTraceZip(traceSession);
+    writeFileSync2(outPath, zipBuffer);
+    console.error(`[TRACE] Saved to ${outPath}`);
+  } catch (e) {
+    console.error("[TRACE] Failed to save trace:", e);
+  } finally {
+    deleteTraceSession(sessionId);
+  }
+}
 function getSessionResult(history) {
   const errorStep = history?.steps.find((s) => s.status === "error");
   return errorStep ? { status: "failed", reason: errorStep.error } : { status: "passed" };
@@ -3447,6 +3722,9 @@ function registerSession(sessionId, browser, metadata, historyEntry) {
     const oldMetadata = state2.sessionMetadata.get(oldSessionId);
     if (oldBrowser) {
       void (async () => {
+        if (oldMetadata?.trace) {
+          await finalizeTrace(oldSessionId, oldBrowser);
+        }
         if (oldMetadata?.provider) {
           const oldHistory = state2.sessionHistory.get(oldSessionId);
           const provider = getProvider(oldMetadata.provider, oldMetadata.type);
@@ -3470,6 +3748,9 @@ async function closeSession(sessionId, detach, isAttached, force) {
     history.endedAt = (/* @__PURE__ */ new Date()).toISOString();
   }
   const metadata = state2.sessionMetadata.get(sessionId);
+  if (metadata?.trace) {
+    await finalizeTrace(sessionId, browser);
+  }
   if (force || !detach && !isAttached) {
     if (metadata?.provider) {
       try {
@@ -3524,6 +3805,7 @@ var startSessionToolDefinition = {
     noReset: coerceBoolean.optional().describe("Preserve app data between sessions"),
     fullReset: coerceBoolean.optional().describe("Uninstall app before/after session"),
     newCommandTimeout: z14.number().min(0).optional().default(300).describe("Appium command timeout in seconds"),
+    trace: coerceBoolean.optional().default(false).describe("Enable trace recording \u2014 produces a Playwright-compatible zip saved to .trace/ on close_session, playable at player.vibium.dev."),
     attach: coerceBoolean.optional().default(false).describe("Attach to existing Chrome instead of launching"),
     attachConfig: z14.object({
       port: z14.number().optional().default(9222),
@@ -3630,7 +3912,8 @@ async function startBrowserSession(args) {
     capabilities: mergedCapabilities,
     isAttached: false,
     provider: args.provider ?? "local",
-    tunnelHandle
+    tunnelHandle,
+    trace: args.trace ?? false
   };
   registerSession(sessionId, wdioBrowser, sessionMetadata, {
     sessionId,
@@ -3639,6 +3922,9 @@ async function startBrowserSession(args) {
     capabilities: mergedCapabilities,
     steps: []
   });
+  if (args.trace) {
+    startTrace(sessionId, mergedCapabilities, "browser", { width: windowWidth, height: windowHeight });
+  }
   let sizeNote = "";
   try {
     await wdioBrowser.setWindowSize(windowWidth, windowHeight);
@@ -3648,6 +3934,9 @@ Note: Unable to set window size (${windowWidth}x${windowHeight}). ${e}`;
   }
   if (navigationUrl) {
     await wdioBrowser.url(navigationUrl);
+    if (args.trace) {
+      await recordInitialNavigation(sessionId, navigationUrl);
+    }
   }
   const modeText = effectiveHeadless ? "headless" : "headed";
   const urlText = navigationUrl ? ` and navigated to ${navigationUrl}` : "";
@@ -3682,7 +3971,8 @@ async function startMobileSession(args) {
     capabilities: mergedCapabilities,
     isAttached: shouldAutoDetach,
     provider: args.provider ?? "local",
-    tunnelHandle
+    tunnelHandle,
+    trace: args.trace ?? false
   };
   registerSession(sessionId, browser, metadata, {
     sessionId,
@@ -3692,6 +3982,9 @@ async function startMobileSession(args) {
     appiumConfig: { hostname: serverConfig.hostname, port: serverConfig.port, path: serverConfig.path },
     steps: []
   });
+  if (args.trace) {
+    startTrace(sessionId, mergedCapabilities, sessionType);
+  }
   const appInfo = appPath ? `
 App: ${appPath}` : "\nApp: (connected to running app)";
   const detachNote = shouldAutoDetach ? "\n\n(Auto-detach enabled: session will be preserved on close. Use close_session({ detach: false }) to force terminate.)" : "";
@@ -3729,7 +4022,8 @@ async function attachBrowserSession(args) {
     type: "browser",
     capabilities,
     isAttached: true,
-    provider: "local"
+    provider: "local",
+    trace: args.trace ?? false
   };
   registerSession(sessionId, browser, sessionMetadata, {
     sessionId,
@@ -3738,10 +4032,19 @@ async function attachBrowserSession(args) {
     capabilities,
     steps: []
   });
+  if (args.trace) {
+    startTrace(sessionId, capabilities, "browser", { width: 1920, height: 1080 });
+  }
   if (navigationUrl) {
     await browser.url(navigationUrl);
+    if (args.trace) {
+      await recordInitialNavigation(sessionId, navigationUrl);
+    }
   } else if (activeTabUrl) {
     await restoreAndSwitchToActiveTab(browser, activeTabUrl, allTabUrls);
+    if (args.trace) {
+      await recordInitialNavigation(sessionId, activeTabUrl);
+    }
   }
   const title = await browser.getTitle();
   const url = await browser.getUrl();
@@ -4094,26 +4397,27 @@ function createServer() {
       );
     }
   };
+  const instrument = (name, cb) => withTrace(name, withRecording(name, cb));
   registerTool(startSessionToolDefinition, withRecording("start_session", startSessionTool));
   registerTool(closeSessionToolDefinition, closeSessionTool);
-  registerTool(launchChromeToolDefinition, withRecording("launch_chrome", launchChromeTool));
+  registerTool(launchChromeToolDefinition, instrument("launch_chrome", launchChromeTool));
   registerTool(emulateDeviceToolDefinition, emulateDeviceTool);
-  registerTool(navigateToolDefinition, withRecording("navigate", navigateTool));
+  registerTool(navigateToolDefinition, instrument("navigate", navigateTool));
   registerTool(switchTabToolDefinition, switchTabTool);
   registerTool(switchFrameToolDefinition, switchFrameTool);
-  registerTool(scrollToolDefinition, withRecording("scroll", scrollTool));
-  registerTool(clickToolDefinition, withRecording("click_element", clickTool));
-  registerTool(setValueToolDefinition, withRecording("set_value", setValueTool));
+  registerTool(scrollToolDefinition, instrument("scroll", scrollTool));
+  registerTool(clickToolDefinition, instrument("click_element", clickTool));
+  registerTool(setValueToolDefinition, instrument("set_value", setValueTool));
   registerTool(setCookieToolDefinition, setCookieTool);
   registerTool(deleteCookiesToolDefinition, deleteCookiesTool);
-  registerTool(tapElementToolDefinition, withRecording("tap_element", tapElementTool));
-  registerTool(swipeToolDefinition, withRecording("swipe", swipeTool));
-  registerTool(dragAndDropToolDefinition, withRecording("drag_and_drop", dragAndDropTool));
+  registerTool(tapElementToolDefinition, instrument("tap_element", tapElementTool));
+  registerTool(swipeToolDefinition, instrument("swipe", swipeTool));
+  registerTool(dragAndDropToolDefinition, instrument("drag_and_drop", dragAndDropTool));
   registerTool(switchContextToolDefinition, switchContextTool);
   registerTool(rotateDeviceToolDefinition, rotateDeviceTool);
   registerTool(hideKeyboardToolDefinition, hideKeyboardTool);
   registerTool(setGeolocationToolDefinition, setGeolocationTool);
-  registerTool(executeScriptToolDefinition, withRecording("execute_script", executeScriptTool));
+  registerTool(executeScriptToolDefinition, instrument("execute_script", executeScriptTool));
   registerTool(getElementsToolDefinition, getElementsTool);
   registerTool(listAppsToolDefinition, listAppsTool);
   registerTool(uploadAppToolDefinition, uploadAppTool);