Plugin Testing

Reference for test utilities, patterns, and lint enforcement for Velaclaw plugins.

Looking for test examples? The how-to guides include worked test examples: Channel plugin tests and Provider plugin tests.

Test utilities

Import: velaclaw/plugin-sdk/testing The testing subpath exports a narrow set of helpers for plugin authors:

import {
  buildDispatchInboundCaptureMock,
  shouldAckReaction,
  removeAckReactionAfterReply,
} from "velaclaw/plugin-sdk/testing";

Common exports

Export	Purpose
`shouldAckReaction`	Check whether a channel should add an ack reaction
`removeAckReactionAfterReply`	Remove ack reaction after reply delivery
`buildDispatchInboundCaptureMock`	Capture inbound dispatch calls in channel tests
`createCliRuntimeCapture`	Capture CLI runtime output in plugin command tests

Types

The testing subpath also re-exports types useful in test files:

import type {
  ChannelAccountSnapshot,
  ChannelGatewayContext,
  VelaclawConfig,
  PluginRuntime,
  RuntimeEnv,
} from "velaclaw/plugin-sdk/testing";

Testing target resolution

Target resolution tests should live with your plugin and cover your channel’s supported target syntax, allowFrom behavior, and error cases:

import { describe } from "vitest";

describe("my-channel target resolution", () => {
  it("should resolve @username targets", () => {
    // ...
  });

  it("should reject senders outside allowFrom", () => {
    // ...
  });
});

Testing patterns

Unit testing a channel plugin

import { describe, it, expect, vi } from "vitest";

describe("my-channel plugin", () => {
  it("should resolve account from config", () => {
    const cfg = {
      channels: {
        "my-channel": {
          token: "test-token",
          allowFrom: ["user1"],
        },
      },
    };

    const account = myPlugin.setup.resolveAccount(cfg, undefined);
    expect(account.token).toBe("test-token");
  });

  it("should inspect account without materializing secrets", () => {
    const cfg = {
      channels: {
        "my-channel": { token: "test-token" },
      },
    };

    const inspection = myPlugin.setup.inspectAccount(cfg, undefined);
    expect(inspection.configured).toBe(true);
    expect(inspection.tokenStatus).toBe("available");
    // No token value exposed
    expect(inspection).not.toHaveProperty("token");
  });
});

Unit testing a provider plugin

import { describe, it, expect } from "vitest";

describe("my-provider plugin", () => {
  it("should resolve dynamic models", () => {
    const model = myProvider.resolveDynamicModel({
      modelId: "custom-model-v2",
      // ... context
    });

    expect(model.id).toBe("custom-model-v2");
    expect(model.provider).toBe("my-provider");
    expect(model.api).toBe("openai-completions");
  });

  it("should return catalog when API key is available", async () => {
    const result = await myProvider.catalog.run({
      resolveProviderApiKey: () => ({ apiKey: "test-key" }),
      // ... context
    });

    expect(result?.provider?.models).toHaveLength(2);
  });
});

Mocking the plugin runtime

For code that uses createPluginRuntimeStore, mock the runtime in tests:

import { createPluginRuntimeStore } from "velaclaw/plugin-sdk/runtime-store";
import type { PluginRuntime } from "velaclaw/plugin-sdk/runtime-store";

const store = createPluginRuntimeStore<PluginRuntime>({
  pluginId: "test-plugin",
  errorMessage: "test runtime not set",
});

// In test setup
const mockRuntime = {
  agent: {
    resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent"),
    // ... other mocks
  },
  config: {
    loadConfig: vi.fn(),
    writeConfigFile: vi.fn(),
  },
  // ... other namespaces
} as unknown as PluginRuntime;

store.setRuntime(mockRuntime);

// After tests
store.clearRuntime();

Testing with per-instance stubs

Prefer per-instance stubs over prototype mutation:

// Preferred: per-instance stub
const client = new MyChannelClient();
client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" });

// Avoid: prototype mutation
// MyChannelClient.prototype.sendMessage = vi.fn();

Contract tests (in-repo plugins)

Bundled plugins have contract tests that verify registration ownership:

pnpm test -- src/plugins/contracts/

These tests assert:

Which plugins register which providers
Which plugins register which speech providers
Registration shape correctness
Runtime contract compliance

Running scoped tests

For a specific plugin:

pnpm test -- <bundled-plugin-root>/my-channel/

For contract tests only:

pnpm test -- src/plugins/contracts/shape.contract.test.ts
pnpm test -- src/plugins/contracts/auth.contract.test.ts
pnpm test -- src/plugins/contracts/runtime.contract.test.ts

Lint enforcement (in-repo plugins)

Three rules are enforced by pnpm check for in-repo plugins:

No monolithic root imports — velaclaw/plugin-sdk root barrel is rejected
No direct src/ imports — plugins cannot import ../../src/ directly
No self-imports — plugins cannot import their own plugin-sdk/<name> subpath

External plugins are not subject to these lint rules, but following the same patterns is recommended.

Test configuration

Velaclaw uses Vitest with V8 coverage thresholds. For plugin tests:

# Run all tests
pnpm test

# Run specific plugin tests
pnpm test -- <bundled-plugin-root>/my-channel/src/channel.test.ts

# Run with a specific test name filter
pnpm test -- <bundled-plugin-root>/my-channel/ -t "resolves account"

# Run with coverage
pnpm test:coverage

If local runs cause memory pressure:

VELACLAW_VITEST_MAX_WORKERS=1 pnpm test

SDK Overview — import conventions
SDK Channel Plugins — channel plugin interface
SDK Provider Plugins — provider plugin hooks
Building Plugins — getting started guide

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

Plugin Testing

Plugin Testing

Test utilities

Common exports

Types

Testing target resolution

Testing patterns

Unit testing a channel plugin

Unit testing a provider plugin

Mocking the plugin runtime

Testing with per-instance stubs

Contract tests (in-repo plugins)

Running scoped tests

Lint enforcement (in-repo plugins)

Test configuration

​Plugin Testing

​Test utilities

​Common exports

​Types

​Testing target resolution

​Testing patterns

​Unit testing a channel plugin

​Unit testing a provider plugin

​Mocking the plugin runtime

​Testing with per-instance stubs

​Contract tests (in-repo plugins)

​Running scoped tests

​Lint enforcement (in-repo plugins)

​Test configuration

​Related

Plugin Testing

Test utilities

Common exports

Types

Testing target resolution

Testing patterns

Unit testing a channel plugin

Unit testing a provider plugin

Mocking the plugin runtime

Testing with per-instance stubs

Contract tests (in-repo plugins)

Running scoped tests

Lint enforcement (in-repo plugins)

Test configuration

Related