| title | Testing & Validation Harness |
|---|---|
| description | Testing Weavetab plugins offline using @weavetab/sdk/testing, simulating tool calls, commands, and mock CDP sessions. |
| product | sdk |
| section | sdk-plugins |
| order | 6 |
| icon | CheckCircle |
| slug | plugin-testing |
The @weavetab/sdk/testing module provides an offline testing harness for unit and integration testing Weavetab plugins. You do not need to launch Chrome or connect to an MCP client to verify tool handlers, CLI commands, or lifecycle hooks.
Import helpers from @weavetab/sdk/testing:
import {
simulateToolCall,
simulateCommandCall,
simulateHook,
createMockContext,
createMockSession,
} from "@weavetab/sdk/testing";| Utility | Description |
|---|---|
simulateToolCall(tool, args, ctxOrOpts?) |
Invokes a defineTool handler with tab, desktop, storage, extension, config, logger, and session (omits tab/session when requiresSession: false). |
simulateCommandCall(command, args, ctx?) |
Invokes a defineCommand handler with args, session/getSession, and a mock PluginContext (defaults to createMockContext()). |
simulateHook(hookFn, ...args) |
Executes a middleware hook (onBeforeAction, etc.) and returns modified result or block payload. |
createMockContext(overrides?) |
Generates an in-memory PluginContext with mock storage (including list() and pruneExpired()), tab, desktop, extension, scoped logger, and mock CLI/MCP registries. |
createMockSession(opts?) |
Generates a mock CDP session with programmable session.Runtime.evaluate return values. |
Here is a complete unit test using Node's native test runner (node:test and node:assert):
// tests/extractor.test.ts
import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { simulateToolCall, createMockSession, createMockContext } from "@weavetab/sdk/testing";
import { tableExtractor } from "../src/tools/extractor.js";
describe("tableExtractor tool", () => {
it("extracts clean table rows from page DOM", async () => {
// 1. Create a mock session that simulates document.querySelector in page
const mockSession = createMockSession({
evaluate: async (code: string) => {
return [
["Header 1", "Header 2"],
["Row 1 Col 1", "Row 1 Col 2"],
];
},
});
const ctx = createMockContext({ name: "test-plugin" });
// 2. Simulate tool invocation
const res = await simulateToolCall(
tableExtractor,
{ selector: "#data-table", maxRows: 10, cleanWhitespace: true },
{ session: mockSession, context: ctx }
);
// 3. Verify tool response content
assert.equal(res.content[0].type, "text");
const parsed = JSON.parse(res.content[0].text);
assert.equal(parsed.rowCount, 2);
assert.deepEqual(parsed.rows[0], ["Header 1", "Header 2"]);
});
});Use simulateCommandCall to test terminal command handlers:
// tests/commands.test.ts
import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { simulateCommandCall, createMockContext } from "@weavetab/sdk/testing";
import { migrateCommand } from "../src/commands/migrate.js";
describe("migrateCommand CLI", () => {
it("executes dry-run without writing changes", async () => {
const ctx = createMockContext({
name: "test-db-plugin",
config: { env: "test" },
});
const res = await simulateCommandCall(
migrateCommand,
{ "dry-run": true },
ctx
);
assert.equal(res.dryRun, true);
assert.equal(res.applied.length, 2);
});
});createMockContext provides an in-memory PluginStorage implementation so tests do not write to the user's home directory:
it("persists key-value data in storage", async () => {
const ctx = createMockContext();
await ctx.storage.set("token", "xyz_123");
assert.equal(await ctx.storage.get("token"), "xyz_123");
await ctx.storage.setJSON("settings", { retries: 5 });
const settings = await ctx.storage.getJSON<{ retries: number }>("settings");
assert.equal(settings?.retries, 5);
});Verify that security filters block unwanted actions:
it("blocks unencrypted HTTP navigations in onBeforeAction hook", async () => {
const hook = async (tool: string, args: any) => {
if (tool === "browser_navigate" && args.url?.startsWith("http://")) {
return { __blocked: true, reason: "Insecure navigation." };
}
};
const blocked = await simulateHook(hook, "browser_navigate", { url: "http://insecure.local" });
assert.equal(blocked?.__blocked, true);
const allowed = await simulateHook(hook, "browser_navigate", { url: "https://secure.com" });
assert.equal(allowed, undefined);
});