diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index 0b0fb7644..479db6afe 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "d462d1faf2aa0722683062c0ff522cfa7d130360", - "syncedAt": "2026-04-27T23:16:05.646Z" + "sha": "90b6665dedddf2c2629cac01aba81ec383033f36", + "syncedAt": "2026-04-27T23:25:58.272Z" } diff --git a/docs/.generated/plugin-sdk-api-baseline.sha256 b/docs/.generated/plugin-sdk-api-baseline.sha256 index e7ce9fedc..2c3002c6c 100644 --- a/docs/.generated/plugin-sdk-api-baseline.sha256 +++ b/docs/.generated/plugin-sdk-api-baseline.sha256 @@ -1,2 +1,2 @@ -7a2039df8cfdcfea0fbc82bbe425c96631ab27b2210c932c6e3f17d380aff350 plugin-sdk-api-baseline.json -ea9f134bc2a1aa17e8abf8f1335daaa927b2272c972523b9d0bd05bf4ac8e149 plugin-sdk-api-baseline.jsonl +0736a1666860383e3e5f8ada181c016455d8304a2852ac6966355765f799add4 plugin-sdk-api-baseline.json +761cdb609547f5912513e5714d8b0ec8fff2b29905690af376cc5bdd74f2c279 plugin-sdk-api-baseline.jsonl diff --git a/docs/plugins/sdk-subpaths.md b/docs/plugins/sdk-subpaths.md index c8edeb628..714beea85 100644 --- a/docs/plugins/sdk-subpaths.md +++ b/docs/plugins/sdk-subpaths.md @@ -23,6 +23,7 @@ For the plugin authoring guide, see [Plugin SDK overview](/plugins/sdk-overview) | `plugin-sdk/config-schema` | `OpenClawSchema` | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | | `plugin-sdk/testing` | Public plugin test fixtures, provider registration/catalog helpers, wizard contract hooks, and bundled-plugin contract maintenance helpers | +| `plugin-sdk/plugin-test-api` | Minimal `OpenClawPluginApi` mock builder for direct plugin registration unit tests | | `plugin-sdk/migration` | Migration provider item helpers such as `createMigrationItem`, reason constants, item status markers, redaction helpers, and `summarizeMigrationItems` | | `plugin-sdk/migration-runtime` | Runtime migration helpers such as `copyMigrationFileItem` and `writeMigrationReport` | @@ -260,6 +261,7 @@ For the plugin authoring guide, see [Plugin SDK overview](/plugins/sdk-overview) | `plugin-sdk/web-media` | Shared remote/local media loading helpers | | `plugin-sdk/zod` | Re-exported `zod` for plugin SDK consumers | | `plugin-sdk/testing` | Public extension test helpers including plugin registry/runtime mocks, provider registration capture, setup-wizard helpers, fetch/env/temp/time fixtures, schema/media/live-test helpers, `installCommonResolveTargetErrorCases`, `writeSkill`, `createTestRegistry`, and live generation env loading. Extension `*.test-support.ts` helpers stay on this or focused SDK subpaths, not core internals | + | `plugin-sdk/plugin-test-api` | Minimal `createTestPluginApi` helper for direct plugin registration unit tests without importing repo test helper bridges | diff --git a/docs/plugins/sdk-testing.md b/docs/plugins/sdk-testing.md index e79c958cc..95b410a90 100644 --- a/docs/plugins/sdk-testing.md +++ b/docs/plugins/sdk-testing.md @@ -19,7 +19,11 @@ plugins. ## Test utilities -**Import:** `openclaw/plugin-sdk/testing` +**General import:** `openclaw/plugin-sdk/testing` + +**Plugin API mock import:** `openclaw/plugin-sdk/plugin-test-api` + +**Channel contract import:** `openclaw/plugin-sdk/channel-contract-testing` The testing subpath exports a narrow set of helpers for plugin authors: @@ -29,44 +33,51 @@ import { shouldAckReaction, removeAckReactionAfterReply, } from "openclaw/plugin-sdk/testing"; +import { createTestPluginApi } from "openclaw/plugin-sdk/plugin-test-api"; +import { expectChannelInboundContextContract } from "openclaw/plugin-sdk/channel-contract-testing"; ``` ### Available exports -| Export | Purpose | -| ------------------------------------------- | ------------------------------------------------------- | -| `installCommonResolveTargetErrorCases` | Shared test cases for target resolution error handling | -| `shouldAckReaction` | Check whether a channel should add an ack reaction | -| `removeAckReactionAfterReply` | Remove ack reaction after reply delivery | -| `createTestRegistry` | Build a channel plugin registry fixture | -| `createEmptyPluginRegistry` | Build an empty plugin registry fixture | -| `setActivePluginRegistry` | Install a registry fixture for plugin runtime tests | -| `createRequestCaptureJsonFetch` | Capture JSON fetch requests in media helper tests | -| `withFetchPreconnect` | Run fetch tests with preconnect hooks installed | -| `withEnv` / `withEnvAsync` | Temporarily patch environment variables | -| `createTempHomeEnv` / `withTempDir` | Create isolated filesystem test fixtures | -| `createMockServerResponse` | Create a minimal HTTP server response mock | -| `registerSingleProviderPlugin` | Register one provider plugin in loader smoke tests | -| `registerProviderPlugin` | Capture all provider kinds from one plugin | -| `registerProviderPlugins` | Capture provider registrations across multiple plugins | -| `requireRegisteredProvider` | Assert that a provider collection contains an id | -| `runProviderCatalog` | Execute a provider catalog hook with test dependencies | -| `resolveProviderWizardOptions` | Resolve provider setup wizard choices in contract tests | -| `resolveProviderModelPickerEntries` | Resolve provider model-picker entries in contract tests | -| `buildProviderPluginMethodChoice` | Build provider wizard choice ids for assertions | -| `setProviderWizardProvidersResolverForTest` | Inject provider wizard providers for isolated tests | -| `createProviderUsageFetch` | Build provider usage fetch fixtures | -| `useFrozenTime` / `useRealTime` | Freeze and restore timers for time-sensitive tests | -| `createRuntimeEnv` | Build a mocked CLI/plugin runtime environment | -| `createTestWizardPrompter` | Build a mocked setup wizard prompter | -| `createPluginSetupWizardStatus` | Build setup status helpers for channel plugins | -| `createRuntimeTaskFlow` | Create isolated runtime task-flow state | -| `typedCases` | Preserve literal types for table-driven tests | +| Export | Purpose | +| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | +| `createTestPluginApi` | Build a minimal plugin API mock for direct registration unit tests. Import from `plugin-sdk/plugin-test-api` | +| `expectChannelInboundContextContract` | Assert channel inbound context shape. Import from `plugin-sdk/channel-contract-testing` | +| `installChannelOutboundPayloadContractSuite` | Install channel outbound payload contract cases. Import from `plugin-sdk/channel-contract-testing` | +| `installCommonResolveTargetErrorCases` | Shared test cases for target resolution error handling | +| `shouldAckReaction` | Check whether a channel should add an ack reaction | +| `removeAckReactionAfterReply` | Remove ack reaction after reply delivery | +| `createTestRegistry` | Build a channel plugin registry fixture | +| `createEmptyPluginRegistry` | Build an empty plugin registry fixture | +| `setActivePluginRegistry` | Install a registry fixture for plugin runtime tests | +| `createRequestCaptureJsonFetch` | Capture JSON fetch requests in media helper tests | +| `withFetchPreconnect` | Run fetch tests with preconnect hooks installed | +| `withEnv` / `withEnvAsync` | Temporarily patch environment variables | +| `createTempHomeEnv` / `withTempDir` | Create isolated filesystem test fixtures | +| `createMockServerResponse` | Create a minimal HTTP server response mock | +| `registerSingleProviderPlugin` | Register one provider plugin in loader smoke tests | +| `registerProviderPlugin` | Capture all provider kinds from one plugin | +| `registerProviderPlugins` | Capture provider registrations across multiple plugins | +| `requireRegisteredProvider` | Assert that a provider collection contains an id | +| `runProviderCatalog` | Execute a provider catalog hook with test dependencies | +| `resolveProviderWizardOptions` | Resolve provider setup wizard choices in contract tests | +| `resolveProviderModelPickerEntries` | Resolve provider model-picker entries in contract tests | +| `buildProviderPluginMethodChoice` | Build provider wizard choice ids for assertions | +| `setProviderWizardProvidersResolverForTest` | Inject provider wizard providers for isolated tests | +| `createProviderUsageFetch` | Build provider usage fetch fixtures | +| `useFrozenTime` / `useRealTime` | Freeze and restore timers for time-sensitive tests | +| `createRuntimeEnv` | Build a mocked CLI/plugin runtime environment | +| `createTestWizardPrompter` | Build a mocked setup wizard prompter | +| `createPluginSetupWizardStatus` | Build setup status helpers for channel plugins | +| `createRuntimeTaskFlow` | Create isolated runtime task-flow state | +| `typedCases` | Preserve literal types for table-driven tests | -Bundled-plugin contract suites also use this subpath for test-only registry, -manifest, public-artifact, and runtime fixture helpers. Keep new extension tests -on `openclaw/plugin-sdk/testing` or a narrower documented SDK subpath rather -than importing repo `src/**` files directly. +Bundled-plugin contract suites also use SDK testing subpaths for test-only +registry, manifest, public-artifact, and runtime fixture helpers. Keep new +extension tests on `openclaw/plugin-sdk/testing` or a narrower documented SDK +subpath such as `plugin-sdk/plugin-test-api` or +`plugin-sdk/channel-contract-testing` rather than importing repo `src/**` files +directly. ### Types