Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Riferimento per utility di test, pattern e applicazione del lint per i plugin di OpenClaw.
Cerchi esempi di test? Le guide pratiche includono esempi di test svolti: Test dei plugin di canale e Test dei plugin provider.

Utility di test

Questi sottopercorsi degli helper di test sono entrypoint sorgente locali al repository per i test dei plugin inclusi in OpenClaw. Non sono export del pacchetto per plugin di terze parti. Import del mock dell’API del Plugin: openclaw/plugin-sdk/plugin-test-api Import del contratto del runtime dell’agente: openclaw/plugin-sdk/agent-runtime-test-contracts Import del contratto del canale: openclaw/plugin-sdk/channel-contract-testing Import dell’helper di test del canale: openclaw/plugin-sdk/channel-test-helpers Import del test del target del canale: openclaw/plugin-sdk/channel-target-testing Import del contratto del Plugin: openclaw/plugin-sdk/plugin-test-contracts Import del test del runtime del Plugin: openclaw/plugin-sdk/plugin-test-runtime Import del contratto del provider: openclaw/plugin-sdk/provider-test-contracts Import del mock HTTP del provider: openclaw/plugin-sdk/provider-http-test-mocks Import dei test di ambiente/rete: openclaw/plugin-sdk/test-env Import della fixture generica: openclaw/plugin-sdk/test-fixtures Import del mock integrato di Node: openclaw/plugin-sdk/test-node-mocks Preferisci i sottopercorsi mirati di seguito per i nuovi test dei plugin. Il barrel ampio openclaw/plugin-sdk/testing è solo compatibilità legacy. Le protezioni del repository rifiutano nuovi import reali da plugin-sdk/testing e plugin-sdk/test-utils; quei nomi restano solo come superfici di compatibilità deprecate per i test dei record di compatibilità.
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 { withEnv, withFetchPreconnect, withServer } from "openclaw/plugin-sdk/test-env";
import {
  bundledPluginRoot,
  createCliRuntimeCapture,
  typedCases,
} from "openclaw/plugin-sdk/test-fixtures";
import { mockNodeBuiltinModule } from "openclaw/plugin-sdk/test-node-mocks";

Export disponibili

EsportazioneScopo
createTestPluginApiCrea un mock minimale dell’API Plugin per test unitari di registrazione diretta. Importare da plugin-sdk/plugin-test-api
AUTH_PROFILE_RUNTIME_CONTRACTFixture condivisa del contratto del profilo di autenticazione per adattatori del runtime nativo degli agenti. Importare da plugin-sdk/agent-runtime-test-contracts
DELIVERY_NO_REPLY_RUNTIME_CONTRACTFixture condivisa del contratto di soppressione della consegna per adattatori del runtime nativo degli agenti. Importare da plugin-sdk/agent-runtime-test-contracts
OUTCOME_FALLBACK_RUNTIME_CONTRACTFixture condivisa del contratto di classificazione fallback per adattatori del runtime nativo degli agenti. Importare da plugin-sdk/agent-runtime-test-contracts
createParameterFreeToolCrea fixture di schema per strumenti dinamici per test dei contratti del runtime nativo. Importare da plugin-sdk/agent-runtime-test-contracts
expectChannelInboundContextContractVerifica la forma del contesto inbound del canale. Importare da plugin-sdk/channel-contract-testing
installChannelOutboundPayloadContractSuiteInstalla casi di contratto per i payload outbound del canale. Importare da plugin-sdk/channel-contract-testing
createStartAccountContextCrea contesti del ciclo di vita dell’account del canale. Importare da plugin-sdk/channel-test-helpers
installChannelActionsContractSuiteInstalla casi generici di contratto per le azioni sui messaggi del canale. Importare da plugin-sdk/channel-test-helpers
installChannelSetupContractSuiteInstalla casi generici di contratto per la configurazione del canale. Importare da plugin-sdk/channel-test-helpers
installChannelStatusContractSuiteInstalla casi generici di contratto per lo stato del canale. Importare da plugin-sdk/channel-test-helpers
expectDirectoryIdsVerifica gli id della directory del canale da una funzione di elenco directory. Importare da plugin-sdk/channel-test-helpers
assertBundledChannelEntriesVerifica che gli entrypoint dei canali inclusi espongano il contratto pubblico previsto. Importare da plugin-sdk/channel-test-helpers
formatEnvelopeTimestampFormatta timestamp di envelope deterministici. Importare da plugin-sdk/channel-test-helpers
expectPairingReplyTextVerifica il testo di risposta dell’abbinamento del canale ed estrae il relativo codice. Importare da plugin-sdk/channel-test-helpers
describePluginRegistrationContractInstalla controlli del contratto di registrazione Plugin. Importare da plugin-sdk/plugin-test-contracts
registerSingleProviderPluginRegistra un singolo Plugin provider nei test smoke del loader. Importare da plugin-sdk/plugin-test-runtime
registerProviderPluginAcquisisce tutti i tipi di provider da un Plugin. Importare da plugin-sdk/plugin-test-runtime
registerProviderPluginsAcquisisce le registrazioni dei provider su più Plugin. Importare da plugin-sdk/plugin-test-runtime
requireRegisteredProviderVerifica che una raccolta di provider contenga un id. Importare da plugin-sdk/plugin-test-runtime
createRuntimeEnvCrea un ambiente runtime CLI/Plugin mockato. Importare da plugin-sdk/plugin-test-runtime
createPluginSetupWizardStatusCrea helper di stato della configurazione per Plugin di canale. Importare da plugin-sdk/plugin-test-runtime
describeOpenAIProviderRuntimeContractInstalla controlli del contratto runtime della famiglia di provider. Importare da plugin-sdk/provider-test-contracts
expectPassthroughReplayPolicyVerifica che le policy di replay del provider passino senza modifiche strumenti e metadati di proprietà del provider. Importare da plugin-sdk/provider-test-contracts
runRealtimeSttLiveTestEsegue un test live del provider STT realtime con fixture audio condivise. Importare da plugin-sdk/provider-test-contracts
normalizeTranscriptForMatchNormalizza l’output della trascrizione live prima delle asserzioni fuzzy. Importare da plugin-sdk/provider-test-contracts
expectExplicitVideoGenerationCapabilitiesVerifica che i provider video dichiarino capacità esplicite per la modalità di generazione. Importare da plugin-sdk/provider-test-contracts
expectExplicitMusicGenerationCapabilitiesVerifica che i provider musicali dichiarino capacità esplicite di generazione/modifica. Importare da plugin-sdk/provider-test-contracts
mockSuccessfulDashscopeVideoTaskInstalla una risposta di attività video riuscita compatibile con DashScope. Importare da plugin-sdk/provider-test-contracts
getProviderHttpMocksAccede ai mock Vitest HTTP/autenticazione del provider attivabili esplicitamente. Importare da plugin-sdk/provider-http-test-mocks
installProviderHttpMockCleanupReimposta i mock HTTP/autenticazione del provider dopo ogni test. Importare da plugin-sdk/provider-http-test-mocks
installCommonResolveTargetErrorCasesCasi di test condivisi per la gestione degli errori di risoluzione del target. Importare da plugin-sdk/channel-target-testing
shouldAckReactionControlla se un canale deve aggiungere una reazione di conferma. Importare da plugin-sdk/channel-feedback
removeAckReactionAfterReplyRimuove la reazione di conferma dopo la consegna della risposta. Importare da plugin-sdk/channel-feedback
createTestRegistryCrea una fixture del registro dei Plugin di canale. Importare da plugin-sdk/plugin-test-runtime o plugin-sdk/channel-test-helpers
createEmptyPluginRegistryCrea una fixture di registro Plugin vuota. Importare da plugin-sdk/plugin-test-runtime o plugin-sdk/channel-test-helpers
setActivePluginRegistryInstalla una fixture di registro per i test del runtime Plugin. Importare da plugin-sdk/plugin-test-runtime o plugin-sdk/channel-test-helpers
createRequestCaptureJsonFetchAcquisisce richieste fetch JSON nei test degli helper multimediali. Importare da plugin-sdk/test-env
withServerEsegue test su un server HTTP locale usa e getta. Importare da plugin-sdk/test-env
createMockIncomingRequestCrea un oggetto minimale di richiesta HTTP in ingresso. Importare da plugin-sdk/test-env
withFetchPreconnectEsegue test fetch con hook di preconnessione installati. Importare da plugin-sdk/test-env
withEnv / withEnvAsyncApplica temporaneamente patch alle variabili d’ambiente. Importare da plugin-sdk/test-env
createTempHomeEnv / withTempHome / withTempDirCrea fixture di test del filesystem isolate. Importare da plugin-sdk/test-env
createMockServerResponseCrea un mock minimale di risposta del server HTTP. Importare da plugin-sdk/test-env
createCliRuntimeCaptureAcquisisce l’output del runtime CLI nei test. Importare da plugin-sdk/test-fixtures
importFreshModuleImporta un modulo ESM con un token di query nuovo per bypassare la cache dei moduli. Importare da plugin-sdk/test-fixtures
bundledPluginRoot / bundledPluginFileRisolve percorsi di fixture sorgente o dist dei Plugin inclusi. Importare da plugin-sdk/test-fixtures
mockNodeBuiltinModuleInstalla mock Vitest mirati per moduli incorporati Node. Importare da plugin-sdk/test-node-mocks
createSandboxTestContextCrea contesti di test sandbox. Importare da plugin-sdk/test-fixtures
writeSkillScrive fixture di skill. Importare da plugin-sdk/test-fixtures
makeAgentAssistantMessageCrea fixture di messaggi della trascrizione degli agenti. Importare da plugin-sdk/test-fixtures
peekSystemEvents / resetSystemEventsForTestIspeziona e reimposta fixture degli eventi di sistema. Importare da plugin-sdk/test-fixtures
sanitizeTerminalTextSanifica l’output del terminale per le asserzioni. Importare da plugin-sdk/test-fixtures
countLines / hasBalancedFencesVerifica la forma dell’output di suddivisione in chunk. Importare da plugin-sdk/test-fixtures
runProviderCatalogEsegue un hook del catalogo provider con dipendenze di test
resolveProviderWizardOptionsRisolve le scelte della procedura guidata di configurazione del provider nei test di contratto
resolveProviderModelPickerEntriesRisolve le voci del selettore di modelli del provider nei test di contratto
buildProviderPluginMethodChoiceCrea id di scelta della procedura guidata del provider per le asserzioni
setProviderWizardProvidersResolverForTestInietta provider della procedura guidata del provider per test isolati
createProviderUsageFetchCrea fixture per il recupero dell’utilizzo del provider
useFrozenTime / useRealTimeBlocca e ripristina i timer per i test sensibili al tempo. Importa da plugin-sdk/test-env
createTestWizardPrompterCrea un prompter fittizio per la procedura guidata di configurazione
createRuntimeTaskFlowCrea uno stato runtime isolato del flusso di attività
typedCasesPreserva i tipi letterali per i test basati su tabelle. Importa da plugin-sdk/test-fixtures
Le suite di contratto dei plugin in bundle usano anche i sottopercorsi di test dell’SDK per helper solo per test relativi a registry, manifest, artefatti pubblici e fixture di runtime. Le suite solo core che dipendono dall’inventario OpenClaw in bundle restano in src/plugins/contracts. Mantieni i nuovi test delle estensioni su un sottopercorso SDK mirato e documentato, come plugin-sdk/plugin-test-api, plugin-sdk/channel-contract-testing, plugin-sdk/agent-runtime-test-contracts, plugin-sdk/channel-test-helpers, plugin-sdk/plugin-test-contracts, plugin-sdk/plugin-test-runtime, plugin-sdk/provider-test-contracts, plugin-sdk/provider-http-test-mocks, plugin-sdk/test-env o plugin-sdk/test-fixtures, invece di importare direttamente il barrel di compatibilità ampio plugin-sdk/testing, i file src/** del repo o i bridge test/helpers/* del repo.

Tipi

I sottopercorsi di test mirati riesportano anche tipi utili nei file di test:
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";

Risoluzione dei target di test

Usa installCommonResolveTargetErrorCases per aggiungere casi di errore standard per la risoluzione dei target del canale:
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", () => {
    // ...
  });
});

Pattern di test

Test dei contratti di registrazione

I test unitari che passano a register(api) un mock api scritto a mano non esercitano i gate di accettazione del loader di OpenClaw. Aggiungi almeno uno smoke test basato sul loader per ogni superficie di registrazione da cui dipende il tuo plugin, in particolare hook e capability esclusive come la memoria. Il loader reale fa fallire la registrazione del plugin quando mancano metadati obbligatori o quando un plugin chiama un’API di capability che non possiede. Per esempio, api.registerHook(...) richiede un nome di hook, e api.registerMemoryCapability(...) richiede che il manifest del plugin o l’entry esportata dichiari kind: "memory".

Test dell’accesso alla configurazione di runtime

Preferisci il mock condiviso del runtime del plugin da openclaw/plugin-sdk/channel-test-helpers quando testi i plugin di canale in bundle. I suoi mock deprecati runtime.config.loadConfig() e runtime.config.writeConfigFile(...) generano un errore per impostazione predefinita, così i test intercettano nuovi usi delle API di compatibilità. Sovrascrivi questi mock solo quando il test copre esplicitamente il comportamento di compatibilità legacy.

Test unitario di un plugin di canale

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");
  });
});

Test unitario di un plugin provider

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);
  });
});

Mock del runtime del plugin

Per il codice che usa createPluginRuntimeStore, esegui il mock del runtime nei test:
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();

Test con stub per istanza

Preferisci gli stub per istanza alla mutazione del prototipo:
// Preferred: per-instance stub
const client = new MyChannelClient();
client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" });

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

Test di contratto (plugin nel repo)

I plugin in bundle hanno test di contratto che verificano la proprietà della registrazione:
pnpm test -- src/plugins/contracts/
Questi test verificano:
  • Quali plugin registrano quali provider
  • Quali plugin registrano quali provider vocali
  • Correttezza della forma della registrazione
  • Conformità al contratto di runtime

Esecuzione di test con ambito limitato

Per un plugin specifico:
pnpm test -- <bundled-plugin-root>/my-channel/
Solo per i test di contratto:
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

Applicazione del lint (plugin nel repo)

Tre regole sono applicate da pnpm check per i plugin nel repo:
  1. Nessun import monolitico dalla root — il barrel root openclaw/plugin-sdk viene rifiutato
  2. Nessun import diretto da src/ — i plugin non possono importare direttamente ../../src/
  3. Nessun self-import — i plugin non possono importare il proprio sottopercorso plugin-sdk/<name>
I plugin esterni non sono soggetti a queste regole di lint, ma è consigliato seguire gli stessi pattern.

Configurazione dei test

OpenClaw usa Vitest con soglie di copertura V8. Per i test dei plugin:
# 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
Se le esecuzioni locali causano pressione sulla memoria:
OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Correlati