@_nazmiforreal/agent-browser-mcp 0.2.0

package/tests/integration.test.ts

@@ -0,0 +1,467 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { EventEmitter } from "events";
+
+// Create a shared mock process factory
+function createMockProcess(exitCode = 0) {
+  const stdout = new EventEmitter();
+  const stderr = new EventEmitter();
+
+  const mockProc = {
+    stdout,
+    stderr,
+    on: vi.fn((event: string, callback: Function) => {
+      if (event === "close") {
+        setImmediate(() => callback(exitCode));
+      }
+      return mockProc;
+    }),
+  };
+
+  return mockProc;
+}
+
+// Mock child_process at module level with factory
+const mockSpawn = vi.fn();
+vi.mock("child_process", () => ({
+  spawn: mockSpawn,
+}));
+
+describe("Integration Tests", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    mockSpawn.mockReset();
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("Full workflow scenarios", () => {
+    it("should handle a complete navigation workflow", async () => {
+      const mockProc = createMockProcess();
+      mockSpawn.mockReturnValue(mockProc);
+
+      const { execBrowser } = await import("../src/tools/executor.js");
+
+      const navPromise = execBrowser("navigate", { url: "https://example.com" });
+      mockProc.stdout.emit("data", "Navigated to https://example.com");
+      const navResult = await navPromise;
+
+      expect(navResult).toContain("Navigated");
+      expect(mockSpawn).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.arrayContaining(["open", "https://example.com"]),
+        expect.any(Object)
+      );
+    });
+
+    it("should handle form filling workflow", async () => {
+      const mockProc = createMockProcess();
+      mockSpawn.mockReturnValue(mockProc);
+
+      const { execBrowser } = await import("../src/tools/executor.js");
+
+      // Fill email field
+      const fillPromise = execBrowser("fill", {
+        selector: "#email",
+        value: "test@example.com",
+      });
+      mockProc.stdout.emit("data", "Filled #email");
+      await fillPromise;
+
+      expect(mockSpawn).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.arrayContaining(["fill", "#email", "test@example.com"]),
+        expect.any(Object)
+      );
+    });
+
+    it("should handle screenshot workflow", async () => {
+      const mockProc = createMockProcess();
+      mockSpawn.mockReturnValue(mockProc);
+
+      const { execBrowser } = await import("../src/tools/executor.js");
+
+      const screenshotPromise = execBrowser("screenshot", {
+        path: "/tmp/test-screenshot.png",
+        fullPage: true,
+      });
+      mockProc.stdout.emit("data", "Screenshot saved to /tmp/test-screenshot.png");
+      const result = await screenshotPromise;
+
+      expect(result).toContain("Screenshot saved");
+      expect(mockSpawn).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.arrayContaining(["screenshot", "/tmp/test-screenshot.png", "-f"]),
+        expect.any(Object)
+      );
+    });
+
+    it("should handle session management", async () => {
+      const mockProc = createMockProcess();
+      mockSpawn.mockReturnValue(mockProc);
+
+      const { execBrowser } = await import("../src/tools/executor.js");
+
+      // Create new session
+      const createPromise = execBrowser("new_session", {
+        viewport: { width: 1920, height: 1080 },
+      });
+      mockProc.stdout.emit("data", "session-abc123");
+      const sessionId = await createPromise;
+
+      expect(sessionId).toBe("session-abc123");
+    });
+
+    it("should pass sessionId to execBrowser", async () => {
+      const mockProc = createMockProcess();
+      mockSpawn.mockReturnValue(mockProc);
+
+      const { execBrowser } = await import("../src/tools/executor.js");
+
+      const navPromise = execBrowser("navigate", { url: "https://example.com" }, "sess-123");
+      mockProc.stdout.emit("data", "Navigated");
+      await navPromise;
+
+      expect(mockSpawn).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.arrayContaining(["open", "--session", "sess-123"]),
+        expect.objectContaining({
+          env: expect.objectContaining({
+            AGENT_BROWSER_SESSION: "sess-123",
+          }),
+        })
+      );
+    });
+  });
+
+  describe("Error scenarios", () => {
+    it("should handle element not found error", async () => {
+      const mockProc = createMockProcess(1);
+      mockSpawn.mockReturnValue(mockProc);
+
+      const { execBrowser } = await import("../src/tools/executor.js");
+
+      const clickPromise = execBrowser("click", { selector: "#non-existent" });
+      mockProc.stderr.emit("data", "Element not found: #non-existent");
+
+      await expect(clickPromise).rejects.toThrow("Element not found");
+    });
+
+    it("should handle navigation timeout", async () => {
+      const mockProc = createMockProcess(1);
+      mockSpawn.mockReturnValue(mockProc);
+
+      const { execBrowser } = await import("../src/tools/executor.js");
+
+      const navPromise = execBrowser("wait_for_navigation", { timeout: 100 });
+      mockProc.stderr.emit("data", "Timeout exceeded");
+
+      await expect(navPromise).rejects.toThrow("Timeout");
+    });
+
+    it("should handle invalid selector", async () => {
+      const mockProc = createMockProcess(1);
+      mockSpawn.mockReturnValue(mockProc);
+
+      const { execBrowser } = await import("../src/tools/executor.js");
+
+      const clickPromise = execBrowser("click", { selector: "::invalid::" });
+      mockProc.stderr.emit("data", "Invalid selector syntax");
+
+      await expect(clickPromise).rejects.toThrow("Invalid selector");
+    });
+
+    it("should handle spawn error", async () => {
+      const stdout = new EventEmitter();
+      const stderr = new EventEmitter();
+
+      const mockProc = {
+        stdout,
+        stderr,
+        on: vi.fn((event: string, callback: Function) => {
+          if (event === "error") {
+            setImmediate(() => callback(new Error("Command not found")));
+          }
+          return mockProc;
+        }),
+      };
+      mockSpawn.mockReturnValue(mockProc);
+
+      const { execBrowser } = await import("../src/tools/executor.js");
+
+      const promise = execBrowser("navigate", { url: "https://example.com" });
+      await expect(promise).rejects.toThrow("Failed to execute agent-browser");
+    });
+  });
+
+  describe("Concurrent operations", () => {
+    it("should handle multiple parallel operations", async () => {
+      // Create separate mock processes for each call
+      const mockProcs = [createMockProcess(), createMockProcess(), createMockProcess()];
+      let callIndex = 0;
+      mockSpawn.mockImplementation(() => mockProcs[callIndex++]);
+
+      const { execBrowser } = await import("../src/tools/executor.js");
+
+      // Start multiple operations in parallel
+      const operations = [
+        execBrowser("get_url", {}),
+        execBrowser("get_title", {}),
+        execBrowser("get_text", {}),
+      ];
+
+      // Emit results for each
+      mockProcs[0].stdout.emit("data", "https://example.com");
+      mockProcs[1].stdout.emit("data", "Example Domain");
+      mockProcs[2].stdout.emit("data", "Hello World");
+
+      const results = await Promise.all(operations);
+
+      expect(results).toHaveLength(3);
+      expect(results[0]).toBe("https://example.com");
+      expect(results[1]).toBe("Example Domain");
+      expect(results[2]).toBe("Hello World");
+    });
+  });
+});
+
+describe("Edge Cases", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    mockSpawn.mockReset();
+  });
+
+  describe("Special characters handling", () => {
+    it("should handle selectors with special characters", async () => {
+      const mockProc = createMockProcess();
+      mockSpawn.mockReturnValue(mockProc);
+
+      const { execBrowser } = await import("../src/tools/executor.js");
+
+      const promise = execBrowser("click", {
+        selector: '[data-testid="submit-btn"]',
+      });
+      mockProc.stdout.emit("data", "Clicked");
+      await promise;
+
+      expect(mockSpawn).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.arrayContaining(["click", '[data-testid="submit-btn"]']),
+        expect.any(Object)
+      );
+    });
+
+    it("should handle URLs with query parameters", async () => {
+      const mockProc = createMockProcess();
+      mockSpawn.mockReturnValue(mockProc);
+
+      const { execBrowser } = await import("../src/tools/executor.js");
+
+      const promise = execBrowser("navigate", {
+        url: "https://example.com/search?q=hello&page=1",
+      });
+      mockProc.stdout.emit("data", "Navigated");
+      await promise;
+
+      expect(mockSpawn).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.arrayContaining(["open", "https://example.com/search?q=hello&page=1"]),
+        expect.any(Object)
+      );
+    });
+
+    it("should handle text with newlines", async () => {
+      const mockProc = createMockProcess();
+      mockSpawn.mockReturnValue(mockProc);
+
+      const { execBrowser } = await import("../src/tools/executor.js");
+
+      const promise = execBrowser("fill", {
+        selector: "#textarea",
+        value: "Line 1\nLine 2\nLine 3",
+      });
+      mockProc.stdout.emit("data", "Filled");
+      await promise;
+
+      expect(mockSpawn).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.arrayContaining(["fill", "#textarea", "Line 1\nLine 2\nLine 3"]),
+        expect.any(Object)
+      );
+    });
+
+    it("should handle unicode characters", async () => {
+      const mockProc = createMockProcess();
+      mockSpawn.mockReturnValue(mockProc);
+
+      const { execBrowser } = await import("../src/tools/executor.js");
+
+      const promise = execBrowser("type", {
+        selector: "#input",
+        text: "Hello 世界",
+      });
+      mockProc.stdout.emit("data", "Typed");
+      await promise;
+
+      expect(mockSpawn).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.arrayContaining(["type", "#input", "Hello 世界"]),
+        expect.any(Object)
+      );
+    });
+  });
+
+  describe("Empty and null values", () => {
+    it("should handle empty string values", async () => {
+      const mockProc = createMockProcess();
+      mockSpawn.mockReturnValue(mockProc);
+
+      const { execBrowser } = await import("../src/tools/executor.js");
+
+      const promise = execBrowser("fill", {
+        selector: "#input",
+        value: "",
+      });
+      mockProc.stdout.emit("data", "Cleared");
+      await promise;
+
+      expect(mockSpawn).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.arrayContaining(["fill", "#input", ""]),
+        expect.any(Object)
+      );
+    });
+
+    it("should handle empty response from browser", async () => {
+      const mockProc = createMockProcess();
+      mockSpawn.mockReturnValue(mockProc);
+
+      const { execBrowser } = await import("../src/tools/executor.js");
+
+      const promise = execBrowser("get_text", { selector: "#empty" });
+      // Don't emit any stdout data - let it close with empty output
+
+      const result = await promise;
+      expect(result).toBe("Command executed successfully");
+    });
+  });
+
+  describe("Large data handling", () => {
+    it("should handle large HTML response", async () => {
+      const mockProc = createMockProcess();
+      mockSpawn.mockReturnValue(mockProc);
+
+      const { execBrowser } = await import("../src/tools/executor.js");
+
+      const promise = execBrowser("get_html", {});
+
+      // Simulate large HTML response
+      const largeHtml = "<html>" + "<div>".repeat(10000) + "</div>".repeat(10000) + "</html>";
+      mockProc.stdout.emit("data", largeHtml);
+
+      const result = await promise;
+      expect(result.length).toBeGreaterThan(100000);
+    });
+
+    it("should handle multiple cookies", async () => {
+      const mockProc = createMockProcess();
+      mockSpawn.mockReturnValue(mockProc);
+
+      const { execBrowser } = await import("../src/tools/executor.js");
+
+      const cookies = Array.from({ length: 50 }, (_, i) => ({
+        name: `cookie_${i}`,
+        value: `value_${i}`,
+        domain: ".example.com",
+      }));
+
+      const promise = execBrowser("set_cookies", { cookies });
+      mockProc.stdout.emit("data", "50 cookies set");
+
+      const result = await promise;
+      expect(result).toContain("50 cookies");
+
+      // Verify first cookie was passed as positional args
+      expect(mockSpawn).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.arrayContaining(["cookies", "set", "cookie_0", "value_0"]),
+        expect.any(Object)
+      );
+    });
+  });
+
+  describe("Boolean and object options", () => {
+    it("should only include boolean flag when true", async () => {
+      const mockProc = createMockProcess();
+      mockSpawn.mockReturnValue(mockProc);
+
+      const { execBrowser } = await import("../src/tools/executor.js");
+
+      const promise = execBrowser("screenshot", { fullPage: true });
+      mockProc.stdout.emit("data", "Done");
+      await promise;
+
+      expect(mockSpawn).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.arrayContaining(["screenshot", "-f"]),
+        expect.any(Object)
+      );
+    });
+
+    it("should not include boolean flag when false", async () => {
+      const mockProc = createMockProcess();
+      mockSpawn.mockReturnValue(mockProc);
+
+      const { execBrowser } = await import("../src/tools/executor.js");
+
+      const promise = execBrowser("screenshot", { fullPage: false, path: "/tmp/shot.png" });
+      mockProc.stdout.emit("data", "Done");
+      await promise;
+
+      const callArgs = mockSpawn.mock.calls[0][1];
+      expect(callArgs).not.toContain("-f");
+      expect(callArgs).toContain("/tmp/shot.png");
+    });
+
+    it("should pass viewport as JSON object", async () => {
+      const mockProc = createMockProcess();
+      mockSpawn.mockReturnValue(mockProc);
+
+      const { execBrowser } = await import("../src/tools/executor.js");
+
+      const viewport = { width: 1920, height: 1080 };
+      const promise = execBrowser("new_session", { viewport });
+      mockProc.stdout.emit("data", "session-123");
+      await promise;
+
+      expect(mockSpawn).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.arrayContaining(["session"]),
+        expect.any(Object)
+      );
+    });
+  });
+});
+
+describe("CamelCase to kebab-case conversion", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    mockSpawn.mockReset();
+  });
+
+  it("should convert camelCase options to kebab-case flags", async () => {
+    const mockProc = createMockProcess();
+    mockSpawn.mockReturnValue(mockProc);
+
+    const { execBrowser } = await import("../src/tools/executor.js");
+
+    const promise = execBrowser("screenshot", { fullPage: true });
+    mockProc.stdout.emit("data", "Done");
+    await promise;
+
+    const callArgs = mockSpawn.mock.calls[0][1];
+    expect(callArgs).toContain("-f");
+    expect(callArgs).not.toContain("--fullPage");
+  });
+});

package/tests/server.test.ts

@@ -0,0 +1,224 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// Mock the executor module
+vi.mock("../src/tools/executor.js", () => ({
+  execBrowser: vi.fn().mockResolvedValue("Success"),
+  checkAgentBrowser: vi.fn().mockResolvedValue(true),
+}));
+
+describe("MCP Server", () => {
+  describe("server initialization", () => {
+    it("should create McpServer with correct metadata", () => {
+      const server = new McpServer({
+        name: "agent-browser-mcp",
+        version: "0.1.0",
+      });
+
+      expect(server).toBeDefined();
+    });
+
+    it("should have tool registration method", () => {
+      const server = new McpServer({
+        name: "agent-browser-mcp",
+        version: "0.1.0",
+      });
+
+      expect(typeof server.tool).toBe("function");
+    });
+  });
+
+  describe("tool registration integration", () => {
+    let server: McpServer;
+    let toolCalls: Array<{ name: string; description: string }>;
+
+    beforeEach(async () => {
+      toolCalls = [];
+      server = {
+        tool: vi.fn((name, description) => {
+          toolCalls.push({ name, description });
+        }),
+      } as unknown as McpServer;
+
+      const { registerBrowserTools } = await import("../src/tools/browser.js");
+      registerBrowserTools(server);
+    });
+
+    it("should register tools with descriptive names", () => {
+      const toolNames = toolCalls.map((t) => t.name);
+
+      // All tools should have browser_ prefix
+      expect(toolNames.every((name) => name.startsWith("browser_"))).toBe(true);
+    });
+
+    it("should provide meaningful descriptions for all tools", () => {
+      toolCalls.forEach((tool) => {
+        expect(tool.description).toBeDefined();
+        expect(tool.description.length).toBeGreaterThan(10);
+      });
+    });
+
+    it("should register navigation tools with correct descriptions", () => {
+      const navigateTool = toolCalls.find((t) => t.name === "browser_navigate");
+      expect(navigateTool?.description).toContain("Navigate");
+
+      const goBackTool = toolCalls.find((t) => t.name === "browser_go_back");
+      expect(goBackTool?.description).toContain("back");
+    });
+
+    it("should register interaction tools with correct descriptions", () => {
+      const clickTool = toolCalls.find((t) => t.name === "browser_click");
+      expect(clickTool?.description.toLowerCase()).toContain("click");
+
+      const fillTool = toolCalls.find((t) => t.name === "browser_fill");
+      expect(fillTool?.description.toLowerCase()).toContain("fill");
+    });
+  });
+});
+
+describe("Tool Schema Validation", () => {
+  it("should validate URL in browser_navigate", async () => {
+    const { z } = await import("zod");
+
+    const schema = z.object({
+      url: z.string().url(),
+      sessionId: z.string().optional(),
+    });
+
+    // Valid URL
+    expect(() => schema.parse({ url: "https://example.com" })).not.toThrow();
+
+    // Invalid URL
+    expect(() => schema.parse({ url: "not-a-url" })).toThrow();
+  });
+
+  it("should validate scroll direction enum", async () => {
+    const { z } = await import("zod");
+
+    const schema = z.object({
+      direction: z.enum(["up", "down", "left", "right"]),
+      amount: z.number().optional(),
+    });
+
+    // Valid directions
+    expect(() => schema.parse({ direction: "up" })).not.toThrow();
+    expect(() => schema.parse({ direction: "down" })).not.toThrow();
+    expect(() => schema.parse({ direction: "left" })).not.toThrow();
+    expect(() => schema.parse({ direction: "right" })).not.toThrow();
+
+    // Invalid direction
+    expect(() => schema.parse({ direction: "diagonal" })).toThrow();
+  });
+
+  it("should validate wait state enum", async () => {
+    const { z } = await import("zod");
+
+    const schema = z.object({
+      selector: z.string(),
+      state: z.enum(["attached", "detached", "visible", "hidden"]).optional(),
+    });
+
+    // Valid states
+    expect(() => schema.parse({ selector: "#el", state: "visible" })).not.toThrow();
+    expect(() => schema.parse({ selector: "#el", state: "hidden" })).not.toThrow();
+
+    // Invalid state
+    expect(() => schema.parse({ selector: "#el", state: "loading" })).toThrow();
+  });
+
+  it("should validate cookie schema", async () => {
+    const { z } = await import("zod");
+
+    const cookieSchema = z.object({
+      name: z.string(),
+      value: z.string(),
+      domain: z.string().optional(),
+      path: z.string().optional(),
+      expires: z.number().optional(),
+      httpOnly: z.boolean().optional(),
+      secure: z.boolean().optional(),
+      sameSite: z.enum(["Strict", "Lax", "None"]).optional(),
+    });
+
+    const schema = z.object({
+      cookies: z.array(cookieSchema),
+    });
+
+    // Valid cookie
+    expect(() =>
+      schema.parse({
+        cookies: [
+          {
+            name: "session",
+            value: "abc123",
+            domain: ".example.com",
+            httpOnly: true,
+            sameSite: "Strict",
+          },
+        ],
+      })
+    ).not.toThrow();
+
+    // Invalid sameSite
+    expect(() =>
+      schema.parse({
+        cookies: [{ name: "test", value: "val", sameSite: "Invalid" }],
+      })
+    ).toThrow();
+  });
+
+  it("should validate viewport schema", async () => {
+    const { z } = await import("zod");
+
+    const schema = z.object({
+      viewport: z
+        .object({
+          width: z.number(),
+          height: z.number(),
+        })
+        .optional(),
+    });
+
+    // Valid viewport
+    expect(() =>
+      schema.parse({
+        viewport: { width: 1920, height: 1080 },
+      })
+    ).not.toThrow();
+
+    // Invalid viewport (missing height)
+    expect(() =>
+      schema.parse({
+        viewport: { width: 1920 },
+      })
+    ).toThrow();
+  });
+});
+
+describe("Response Format", () => {
+  it("should return MCP-compliant response format", async () => {
+    vi.mock("../src/tools/executor.js", () => ({
+      execBrowser: vi.fn().mockResolvedValue("Test result"),
+    }));
+
+    const mockServer = {
+      tool: vi.fn((name, description, schema, handler) => {
+        // Store handler for testing
+        (mockServer as any).handlers = (mockServer as any).handlers || {};
+        (mockServer as any).handlers[name] = handler;
+      }),
+    } as unknown as McpServer;
+
+    const { registerBrowserTools } = await import("../src/tools/browser.js");
+    registerBrowserTools(mockServer);
+
+    const handler = (mockServer as any).handlers["browser_navigate"];
+    const result = await handler({ url: "https://example.com" });
+
+    // Verify MCP response format
+    expect(result).toHaveProperty("content");
+    expect(Array.isArray(result.content)).toBe(true);
+    expect(result.content[0]).toHaveProperty("type", "text");
+    expect(result.content[0]).toHaveProperty("text");
+  });
+});

package/vitest.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: ["src/**/*.test.ts", "tests/**/*.test.ts"],
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "json", "html"],
+      include: ["src/**/*.ts"],
+      exclude: ["src/**/*.test.ts", "src/**/*.d.ts"],
+    },
+  },
+});