@mcptrail/webmcp-testing

Test your WebMCP tools without a flagged Chrome or a live model. It installs a mock navigator.modelContext, captures the tools your page registers, and gives you a driver to list, validate-args, invoke, and snapshot the toolset — so tools become plain unit tests.

Works with any runner (Vitest, Jest, Playwright, Node) in any DOM-ish environment.

Install

npm install -D @mcptrail/webmcp-testing

Usage

import { installModelContext } from "@mcptrail/webmcp-testing";

test("book_hotel books a room", async () => {
  const mcp = installModelContext();     // mocks navigator.modelContext

  renderMyApp();                         // your code calls navigator.modelContext.registerTool(...)

  expect(mcp.has("book_hotel")).toBe(true);

  const result = await mcp.call("book_hotel", { hotelId: "h1", guests: 2 });
  expect(result).toContain("Confirmation");
  expect(document.querySelector("#bookings")).toHaveTextContent("h1");

  mcp.uninstall();
});

Driver API

const mcp = installModelContext(options);

mcp.tools();                 // ToolDescriptor[] (name, description, inputSchema, annotations, readOnly)
mcp.tool(name);              // one descriptor
mcp.has(name);               // boolean
await mcp.call(name, args);  // run execute(args), await, return the result
mcp.validate(name, args);    // { valid, errors[] } against the tool's inputSchema
mcp.assertValid(name, args); // throw if invalid
mcp.snapshot();              // { tools[], hash } — serializable + a stable hash for drift assertions
mcp.reset();                 // clear the registry
mcp.uninstall();             // restore the previous modelContext
mcp.onRegister(cb);          // (tool) => void
mcp.onCall(cb);              // (name, args, result) => void

Options

| Option | Default | Notes | |--------|---------|-------| | strict | false | call() validates args against the schema and rejects on error | | target | navigator | object to receive .modelContext (created on globalThis if absent) | | alsoDocument | true | also set document.modelContext |

Arg validation

validate / assertValid / strict check args against a common JSON-Schema subset — type, required, enum, minimum/maximum, minLength/maxLength, nested objects and arrays. Catches "the model sent the wrong shape" in a test instead of production.

import { validateArgs } from "@mcptrail/webmcp-testing";
validateArgs(schema, args); // { valid, errors: [{ path, message }] }

Drift snapshots

snapshot() returns a sorted, serializable view of the toolset plus a stable hash — pair it with toMatchSnapshot(), or assert the hash is unchanged to catch an unexpected change to what your page exposes to agents.

Development

npm install
npm run typecheck
npm test          # Vitest + jsdom
npm run build     # tsup → dist (ESM + CJS + d.ts)

License

MIT © Zied Guetari