feat: implement take page snapshot command (#16)

Author: shadowusr

README.md

@@ -225,3 +225,21 @@ Type text into an input element on the page using semantic queries (`testing-lib
 **Note:** Provide either semantic query parameters OR selector, not both.
 
 </details>
+
+<details>
+<summary>Page Inspection</summary>
+
+### `takePageSnapshot`
+Capture a DOM snapshot of the current page with configurable filtering options.
+
+- **Parameters:**
+  - `includeTags` (array of strings, optional): HTML tags to include in the snapshot besides defaults
+  - `includeAttrs` (array of strings, optional): HTML attributes to include in the snapshot besides defaults
+  - `excludeTags` (array of strings, optional): HTML tags to exclude from the snapshot
+  - `excludeAttrs` (array of strings, optional): HTML attributes to exclude from the snapshot
+  - `truncateText` (boolean, optional): Whether to truncate long text content (default: true)
+  - `maxTextLength` (number, optional): Maximum length of text content before truncation
+
+**Note:** By default, only useful tags and attributes are included in snapshots. The response will indicate what was omitted. Use the filtering options only if you need specific content that's not included by default.
+
+</details>

src/tools/index.ts

@@ -3,5 +3,12 @@ import { navigate } from "./navigate.js";
 import { closeBrowser } from "./close-browser.js";
 import { clickOnElement } from "./click-on-element.js";
 import { typeIntoElement } from "./type-into-element.js";
+import { takePageSnapshot } from "./take-page-snapshot.js";
 
-export const tools = [navigate, closeBrowser, clickOnElement, typeIntoElement] as const satisfies ToolDefinition<any>[]; // eslint-disable-line @typescript-eslint/no-explicit-any
+export const tools = [
+    navigate,
+    closeBrowser,
+    clickOnElement,
+    typeIntoElement,
+    takePageSnapshot,
+] as const satisfies ToolDefinition<any>[]; // eslint-disable-line @typescript-eslint/no-explicit-any

src/tools/take-page-snapshot.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { ToolDefinition } from "../types.js";
+import { ToolCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { contextProvider } from "../context-provider.js";
+import { createBrowserStateResponse, createErrorResponse } from "../responses/index.js";
+
+export const takePageSnapshotSchema = {
+    includeTags: z.array(z.string()).optional().describe("HTML tags to include in the snapshot besides defaults"),
+    includeAttrs: z
+        .array(z.string())
+        .optional()
+        .describe("HTML attributes to include in the snapshot besides defaults"),
+    excludeTags: z.array(z.string()).optional().describe("HTML tags to exclude from the snapshot"),
+    excludeAttrs: z.array(z.string()).optional().describe("HTML attributes to exclude from the snapshot"),
+    truncateText: z.boolean().optional().describe("Whether to truncate long text content (default: true)"),
+    maxTextLength: z.number().positive().optional().describe("Maximum length of text content before truncation"),
+};
+
+const takePageSnapshotCb: ToolCallback<typeof takePageSnapshotSchema> = async args => {
+    try {
+        const context = contextProvider.getContext();
+        const browser = await context.browser.get();
+
+        const snapshotOptions = {
+            includeTags: args.includeTags,
+            includeAttrs: args.includeAttrs,
+            excludeTags: args.excludeTags,
+            excludeAttrs: args.excludeAttrs,
+            truncateText: args.truncateText,
+            maxTextLength: args.maxTextLength,
+        };
+
+        const testplaneCode = `const snapshot = await browser.unstable_captureDomSnapshot(${JSON.stringify(snapshotOptions, null, 2)});`;
+
+        return await createBrowserStateResponse(browser, {
+            action: "Page snapshot captured successfully",
+            testplaneCode,
+            snapshotOptions,
+        });
+    } catch (error) {
+        console.error("Error taking page snapshot:", error);
+        return createErrorResponse("Error taking page snapshot", error instanceof Error ? error : undefined);
+    }
+};
+
+export const takePageSnapshot: ToolDefinition<typeof takePageSnapshotSchema> = {
+    name: "takePageSnapshot",
+    description:
+        "Capture a DOM snapshot of the current page. Note: by default, only useful tags and attributes are included. Prefer to use defaults. Response contains info as to what was omitted. If you need more info, request a snapshot with more tags and attributes.",
+    schema: takePageSnapshotSchema,
+    cb: takePageSnapshotCb,
+};

test/tools/take-page-snapshot.test.ts

@@ -0,0 +1,78 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { describe, it, expect, beforeAll, beforeEach, afterEach, afterAll } from "vitest";
+import { startClient } from "../utils";
+import { INTEGRATION_TEST_TIMEOUT } from "../constants";
+import { PlaygroundServer } from "../test-server";
+
+describe(
+    "tools/takePageSnapshot",
+    () => {
+        let client: Client;
+        let playgroundUrl: string;
+        let testServer: PlaygroundServer;
+
+        beforeAll(async () => {
+            testServer = new PlaygroundServer();
+            playgroundUrl = await testServer.start();
+        }, 20000);
+
+        afterAll(async () => {
+            if (testServer) {
+                await testServer.stop();
+            }
+        });
+
+        beforeEach(async () => {
+            client = await startClient();
+        });
+
+        afterEach(async () => {
+            if (client) {
+                await client.close();
+            }
+        });
+
+        describe("takePageSnapshot tool availability", () => {
+            it("should list takePageSnapshot tool in available tools", async () => {
+                const tools = await client.listTools();
+
+                const snapshotTool = tools.tools.find(tool => tool.name === "takePageSnapshot");
+
+                expect(snapshotTool).toBeDefined();
+            });
+        });
+
+        describe("takePageSnapshot tool execution", () => {
+            it("should capture snapshot of playground page with expected content", async () => {
+                await client.callTool({
+                    name: "navigate",
+                    arguments: { url: playgroundUrl },
+                });
+
+                const result = await client.callTool({
+                    name: "takePageSnapshot",
+                    arguments: {},
+                });
+
+                expect(result.isError).toBe(false);
+                expect(result.content).toBeDefined();
+
+                const content = result.content as Array<{ type: string; text: string }>;
+                expect(content).toHaveLength(1);
+                expect(content[0].type).toBe("text");
+
+                const responseText = content[0].text;
+
+                expect(responseText).toContain("Element Click Test Playground");
+                expect(responseText).toContain("Role-based Elements");
+                expect(responseText).toContain("Submit Form");
+                expect(responseText).toContain("Text-based Elements");
+                expect(responseText).toContain("Form Elements");
+                expect(responseText).toContain("Email Address");
+                expect(responseText).toContain("Placeholder Elements");
+                expect(responseText).toContain("Enter your name");
+            });
+        });
+    },
+    INTEGRATION_TEST_TIMEOUT,
+);