OpenClaw Plugin Testing Utilities and Patterns

Reference material covering test utilities, patterns, and lint enforcement for OpenClaw plugins.

Tip

Need test examples? The how-to guides provide worked examples: Channel plugin tests and Provider plugin tests.

Test utilities

These subpaths act as repo-local source entrypoints for OpenClaw's bundled plugin tests. They are not exposed as package.json exports for third-party plugins, and they may rely on Vitest or other repo-only test dependencies.

import {
  shouldAckReaction,
  removeAckReactionAfterReply,
} from "openclaw/plugin-sdk/channel-feedback";
import { installCommonResolveTargetErrorCases } from "openclaw/plugin-sdk/channel-target-testing";
import { AUTH_PROFILE_RUNTIME_CONTRACT } from "openclaw/plugin-sdk/agent-runtime-test-contracts";
import { createTestPluginApi } from "openclaw/plugin-sdk/plugin-test-api";
import { expectChannelInboundContextContract } from "openclaw/plugin-sdk/channel-contract-testing";
import { createStartAccountContext } from "openclaw/plugin-sdk/channel-test-helpers";
import { describePluginRegistrationContract } from "openclaw/plugin-sdk/plugin-test-contracts";
import { registerSingleProviderPlugin } from "openclaw/plugin-sdk/plugin-test-runtime";
import { describeOpenAIProviderRuntimeContract } from "openclaw/plugin-sdk/provider-test-contracts";
import { getProviderHttpMocks } from "openclaw/plugin-sdk/provider-http-test-mocks";
import { createOpenClawTestState } from "openclaw/plugin-sdk/test-state";
import { withEnv, withFetchPreconnect, withServer } from "openclaw/plugin-sdk/test-env";
import { isLiveTestEnabled } from "openclaw/plugin-sdk/test-live";
import { createRequestCaptureJsonFetch } from "openclaw/plugin-sdk/test-media-understanding";
import {
  bundledPluginRoot,
  createCliRuntimeCapture,
  runDirectImportSmoke,
  typedCases,
} from "openclaw/plugin-sdk/test-fixtures";
import { mockNodeBuiltinModule } from "openclaw/plugin-sdk/test-node-mocks";

For bundled plugin tests, stick to these focused subpaths. The earlier openclaw/plugin-sdk/testing barrel was repo-local, omitted from shipped packages, and has since been removed. The previous openclaw/plugin-sdk/test-utils alias was also dropped at that time. pnpm run lint:plugins:no-extension-test-core-imports (scripts/check-no-extension-test-core-imports.ts) keeps extension tests on the focused test subpaths listed above.

Available exports

Contract suites for bundled plugins also rely on these SDK testing subpaths for test-only registry, manifest, public-artifact, and runtime fixture helpers. Suites that are core-only and depend on bundled OpenClaw inventory remain under src/plugins/contracts.

Types

Testing subpaths that are more focused also re-export types that come in handy within test files:

import type {
  ChannelAccountSnapshot,
  ChannelGatewayContext,
} from "openclaw/plugin-sdk/channel-contract";
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
import type { MockFn, PluginRuntime, RuntimeEnv } from "openclaw/plugin-sdk/plugin-test-runtime";

Testing target resolution

Add standard error cases for channel target resolution with installCommonResolveTargetErrorCases:

import { describe } from "vitest";
import { installCommonResolveTargetErrorCases } from "openclaw/plugin-sdk/channel-target-testing";

describe("my-channel target resolution", () => {
  installCommonResolveTargetErrorCases({
    resolveTarget: ({ to, mode, allowFrom }) => {
      // Your channel's target resolution logic
      return myChannelResolveTarget({ to, mode, allowFrom });
    },
    implicitAllowFrom: ["user1", "user2"],
  });

  // Add channel-specific test cases
  it("should resolve @username targets", () => {
    // ...
  });
});

Testing patterns

Testing registration contracts

When unit tests hand a manually written api mock to register(api), they skip OpenClaw's loader acceptance checks. For every registration surface your plugin relies on, add at least one smoke test backed by the loader, particularly for hooks and exclusive capabilities like memory.

If required metadata is absent, or a plugin invokes a capability API it does not own, the real loader rejects registration. As an example, api.registerHook(...) needs a hook name, while api.registerMemoryCapability(...) expects the plugin manifest or exported entry to declare kind: "memory".

Testing runtime config access

Go with the shared plugin runtime mock available from openclaw/plugin-sdk/plugin-test-runtime. Its runtime config helpers reflect the current snapshot and mutation APIs.

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 relies on createPluginRuntimeStore, mock the runtime during tests:

import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import type { PluginRuntime } from "openclaw/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: {
    current: vi.fn(() => ({}) as const),
    mutateConfigFile: vi.fn(),
    replaceConfigFile: vi.fn(),
  },
  // ... other namespaces
} as unknown as PluginRuntime;

store.setRuntime(mockRuntime);

// After tests
store.clearRuntime();

Testing with per-instance stubs

Use per-instance stubs rather than altering the prototype:

// 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)

Contract tests for bundled plugins confirm registration ownership:

pnpm test src/plugins/contracts/

These tests verify:

• 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-choice.contract.test.ts
pnpm test src/plugins/contracts/runtime-seams.contract.test.ts

Lint enforcement (in-repo plugins)

scripts/run-additional-boundary-checks.mts executes a collection of lint:plugins:* import-boundary validations during CI, though each one can also be invoked independently on a local machine:

These lint rules do not apply to external plugins, yet adopting the same conventions is advised.

Test configuration

Vitest 4, paired with informational V8 coverage reporting, is the testing setup OpenClaw relies on. For tests written against plugins:

# 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

Should memory pressure appear during local execution:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Related

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