feat: implement the time-travel-snapshot tool

packages/cli/package.json

@@ -26,6 +26,7 @@
   "license": "ISC",
   "dependencies": {
     "@testplane/testing-library": "^1.0.5",
+    "@rrweb/replay": "^2.0.0-alpha.18",
     "commander": "^14.0.3",
     "debug": "^4.3.4",
     "html-reporter": "^11.10.0-rc.2",

packages/cli/test/daemon.e2e.test.ts

@@ -124,7 +124,7 @@ describe("daemon e2e", () => {
         expect(r.code).toBe(0);
         expect(r.stdout).toContain(`Successfully navigated to ${playgroundUrl}`);
 
-        const snapshotPathMatch = r.stdout.match(/Saved to: (\S+\.(?:yml|html))/);
+        const snapshotPathMatch = r.stdout.match(/The snapshot was saved to: (\S+\.(?:yml|html))/);
         expect(snapshotPathMatch, "navigate response should reference a saved snapshot file").not.toBeNull();
         const snapshotContent = fs.readFileSync(snapshotPathMatch![1], "utf8");
         expect(snapshotContent).toContain("e2e-ok");
@@ -141,7 +141,7 @@ describe("daemon e2e", () => {
         expect(r.code).toBe(0);
         expect(r.stdout).toContain('Successfully selected option by value "jp"');
 
-        const snapshotPathMatch = r.stdout.match(/Saved to: (\S+\.(?:yml|html))/);
+        const snapshotPathMatch = r.stdout.match(/The snapshot was saved to: (\S+\.(?:yml|html))/);
         expect(snapshotPathMatch, "select response should reference a saved snapshot file").not.toBeNull();
         const snapshotContent = fs.readFileSync(snapshotPathMatch![1], "utf8");
         expect(snapshotContent).toContain("selected:jp");

packages/mcp/package.json

@@ -27,6 +27,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.11.2",
     "@testplane/testing-library": "^1.0.5",
+    "@rrweb/replay": "^2.0.0-alpha.18",
     "commander": "^13.1.0",
     "html-reporter": "^11.10.0-rc.2",
     "testplane": "^8.44.1-rc.1",

packages/mcp/test/server.e2e.test.ts

@@ -23,6 +23,7 @@ const EXPECTED_TOOL_NAMES = [
     // report tools
     "test-results",
     "inspect-result",
+    "time-travel-snapshot",
     // session tools
     "launch",
     "attach",
@@ -61,7 +62,7 @@ describe(
             const text = content.map(c => c.text).join("\n");
             expect(text).toContain(`Successfully navigated to ${playgroundUrl}`);
 
-            const snapshotPathMatch = text.match(/Saved to: (\S+\.(?:yml|html))/);
+            const snapshotPathMatch = text.match(/(?:Saved to:|The snapshot was saved to:) (\S+\.(?:yml|html))/);
             expect(snapshotPathMatch, "navigate response should reference a saved snapshot file").not.toBeNull();
             const snapshotContent = fs.readFileSync(snapshotPathMatch![1], "utf8");
             expect(snapshotContent).toContain("server-wiring-ok");

packages/tools/package.json

@@ -28,6 +28,9 @@
   "license": "ISC",
   "dependencies": {
     "@testplane/testing-library": "^1.0.5",
+    "@rrweb/replay": "^2.0.0-alpha.18",
+    "@rrweb/types": "^2.0.0-alpha.18",
+    "fflate": "^0.8.2",
     "html-reporter": "^11.10.0-rc.2",
     "lodash.escaperegexp": "^4.1.2",
     "testplane": "^8.44.1-rc.1",

packages/tools/src/index.ts

@@ -17,6 +17,7 @@ import { attachToBrowser } from "./tools/attach-to-browser.js";
 import { closeBrowser } from "./tools/close-browser.js";
 import { inspectResult } from "./tools/inspect-result/index.js";
 import { testResults } from "./tools/test-results/index.js";
+import { timeTravelSnapshot } from "./tools/time-travel-snapshot/index.js";
 
 // This function just ensures that every item on a type level is a Tool<something>. AFAIK the only way to do this.
 const typeCheckedTools = <const T extends readonly unknown[]>(
@@ -42,6 +43,7 @@ export const tools = typeCheckedTools([
     closeBrowser,
     testResults,
     inspectResult,
+    timeTravelSnapshot,
 ]);
 
 export { launchBrowserWithOptions, ToolKind };

packages/tools/src/responses/browser-helpers.ts

@@ -131,7 +131,13 @@ function formatNotesAsComments(notes: string[], fenceLanguage: "yaml" | "html"):
 
 export interface PageSnapshotResult {
     content: string;
-    fenceLanguage: "yaml" | "html";
+    fenceLanguage: "yaml" | "html" | "diff";
+}
+
+export const INLINE_SNAPSHOT_MAX_LENGTH = 32_000;
+
+export function isPageSnapshotTooLargeForInline(snapshot: PageSnapshotResult): boolean {
+    return snapshot.content.length > INLINE_SNAPSHOT_MAX_LENGTH;
 }
 
 export async function getPageSnapshot(
@@ -152,21 +158,34 @@ export interface SavedPageSnapshot {
     filePath: string;
 }
 
-export async function savePageSnapshotToFile(
-    browser: WdioBrowser,
-    options: CaptureSnapshotOptions = {},
-): Promise<SavedPageSnapshot | null> {
-    const result = await getPageSnapshot(browser, options);
-    if (!result) return null;
-
+async function savePageSnapshotToFile(snapshot: PageSnapshotResult): Promise<SavedPageSnapshot> {
     const dir = path.join(os.tmpdir(), ".testplane", "snapshots");
     await fs.mkdir(dir, { recursive: true });
 
     const timestamp = formatTimestamp();
-    const extension = result.fenceLanguage === "html" ? "html" : "yml";
+    const extension = snapshot.fenceLanguage === "html" ? "html" : snapshot.fenceLanguage === "diff" ? "diff" : "yml";
     const filePath = path.join(dir, `${timestamp}-${randomUUID()}.${extension}`);
 
-    await fs.writeFile(filePath, result.content, "utf8");
+    await fs.writeFile(filePath, snapshot.content, "utf8");
 
     return { filePath };
 }
+
+/** Format a snapshot as a response string, optionally saving it to a file if it is too large for inline display. */
+export async function convertSnapshotToResponse(
+    snapshot: PageSnapshotResult,
+    { forceSaveToFile = false }: { forceSaveToFile?: boolean } = {},
+): Promise<string> {
+    if (forceSaveToFile) {
+        const saved = await savePageSnapshotToFile(snapshot);
+        return `The snapshot was saved to: ${saved.filePath}`;
+    }
+
+    if (!isPageSnapshotTooLargeForInline(snapshot)) {
+        return "```" + snapshot.fenceLanguage + "\n" + snapshot.content + "\n```";
+    }
+
+    const saved = await savePageSnapshotToFile(snapshot);
+
+    return `The snapshot is too large to include inline (${snapshot.content.length} characters; limit ${INLINE_SNAPSHOT_MAX_LENGTH}), so it was saved to: ${saved.filePath}`;
+}

packages/tools/src/responses/index.ts

@@ -1,6 +1,11 @@
 import { WdioBrowser } from "testplane";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { CaptureSnapshotOptions, getPageSnapshot, getBrowserTabs, savePageSnapshotToFile } from "./browser-helpers.js";
+import {
+    CaptureSnapshotOptions,
+    getPageSnapshot,
+    getBrowserTabs,
+    convertSnapshotToResponse,
+} from "./browser-helpers.js";
 
 export type ToolResponse = CallToolResult;
 
@@ -55,21 +60,14 @@ export async function createBrowserStateResponse(
     }
 
     if (options.isSnapshotNeeded !== false) {
-        if (options.inlineSnapshot) {
-            const snapshot = await getPageSnapshot(browser, options.snapshotOptions);
-            if (snapshot) {
-                sections.push("## Current Tab Snapshot");
-                sections.push("```" + snapshot.fenceLanguage + "\n" + snapshot.content + "\n```");
-            }
+        const snapshot = await getPageSnapshot(browser, options.snapshotOptions);
+        if (!snapshot) {
+            sections.push("## Current Tab Snapshot");
+            sections.push("No snapshot captured");
         } else {
-            const saved = await savePageSnapshotToFile(browser, options.snapshotOptions);
-            if (saved) {
-                sections.push("## Current Tab Snapshot");
-                sections.push(
-                    `Saved to: ${saved.filePath}\n` +
-                        `Note: some tags/attributes may be omitted and text may be truncated — see the comments at the top of the file for details.`,
-                );
-            }
+            const response = await convertSnapshotToResponse(snapshot, { forceSaveToFile: !options.inlineSnapshot });
+            sections.push("## Current Tab Snapshot");
+            sections.push(response);
         }
     }