src/plugin-sdk/test-helpers/contracts-testkit.ts

/**
 * Core plugin SDK contract-test fixture builders and registration helpers.
 */
import type { OpenClawConfig } from "../../config/config.js";
import type { PluginRegistryParams } from "../../plugins/registry-types.js";
import { createPluginRegistry, type PluginRecord } from "../../plugins/registry.js";
import type { PluginRuntime } from "../../plugins/runtime/types.js";
import { createPluginRecord } from "../../plugins/status.test-helpers.js";
import {
  registerProviderPlugins as registerProviders,
  requireRegisteredProvider as requireProvider,
} from "../../test-utils/plugin-registration.js";
import type { OpenClawPluginApi } from "../plugin-entry.js";
export { assertNoImportTimeSideEffects } from "./import-side-effects.js";

export { registerProviders, requireProvider };

/** Creates a minimal plugin registry fixture with quiet logger defaults. */
export function createPluginRegistryFixture(
  config = {} as OpenClawConfig,
  params: {
    allowProcessHomeSessionCatalogs?: boolean;
    hostServices?: PluginRegistryParams["hostServices"];
  } = {},
) {
  return {
    config,
    registry: createPluginRegistry({
      logger: {
        info() {},
        warn() {},
        error() {},
        debug() {},
      },
      runtime: {} as PluginRuntime,
      allowProcessHomeSessionCatalogs: params.allowProcessHomeSessionCatalogs ?? true,
      ...(params.hostServices ? { hostServices: params.hostServices } : {}),
    }),
  };
}

/** Registers one plugin record against a registry fixture and invokes its register hook. */
export function registerTestPlugin(params: {
  registry: ReturnType<typeof createPluginRegistry>;
  config: OpenClawConfig;
  record: PluginRecord;
  register(api: OpenClawPluginApi): void;
}) {
  params.registry.registry.plugins.push(params.record);
  params.register(
    params.registry.createApi(params.record, {
      config: params.config,
      hookPolicy: params.config.plugins?.entries?.[params.record.id]?.hooks,
    }),
  );
}

/** Registers a virtual plugin record for tests that do not need a real package path. */
export function registerVirtualTestPlugin(params: {
  registry: ReturnType<typeof createPluginRegistry>;
  config: OpenClawConfig;
  id: string;
  name: string;
  source?: string;
  kind?: PluginRecord["kind"];
  contracts?: PluginRecord["contracts"];
  register(this: void, api: OpenClawPluginApi): void;
}) {
  registerTestPlugin({
    registry: params.registry,
    config: params.config,
    record: createPluginRecord({
      id: params.id,
      name: params.name,
      source: params.source ?? `/virtual/${params.id}/index.ts`,
      ...(params.kind ? { kind: params.kind } : {}),
      ...(params.contracts ? { contracts: params.contracts } : {}),
    }),
    register: params.register,
  });
}