github-mirrors/openclaw
1
0
Fork 0
mirror of https://fastgit.cc/github.com/openclaw/openclaw synced 2026-04-30 14:02:56 +08:00
Code Issues Packages Projects Releases Wiki Activity

refactor: split generic plugin test fixtures

Browse Source
This commit is contained in:
Peter Steinberger
2026-04-28 01:21:29 +01:00
parent e508d81f79
commit 56875c4d32
22 changed files with 105 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
CHANGELOG.md
View File

@@ -15,6 +15,7 @@ Docs: https://docs.openclaw.ai
- Gateway/runtime: reuse the current plugin metadata snapshot for provider discovery so repeated model-provider discovery avoids rebuilding plugin manifest metadata. Thanks @shakkernerd.
- Gateway/startup: pass the plugin metadata snapshot from config validation into plugin bootstrap so startup reuses one manifest product instead of rebuilding plugin metadata. Thanks @shakkernerd.
- Plugin SDK/testing: promote bundled plugin/provider/channel contract helpers to focused SDK test subpaths and retire the repo-only `test/helpers/plugins` TypeScript bridge. Thanks @vincentkoc.
- Plugin SDK/testing: add a focused generic fixture subpath for CLI capture, sandbox, skill, agent-message, system-event, terminal, chunking, auth-token, and typed-case helpers. Thanks @vincentkoc.
- Plugin SDK/testing: add focused plugin runtime and environment fixture subpaths so plugin tests can avoid the broad `plugin-sdk/testing` barrel for common setup helpers. Thanks @vincentkoc.
- Plugin SDK/testing: add a focused `plugin-sdk/plugin-test-api` helper subpath and move bundled plugin registration tests off the repo-only plugin API bridge. Thanks @vincentkoc.
- Plugin SDK: add generic host hooks for session state, next-turn context, trusted tool policy, UI descriptors, events, scheduler cleanup, and run-scoped plugin context. (#72287) Thanks @100yenadmin.

4
docs/.generated/plugin-sdk-api-baseline.sha256
View File

@@ -1,2 +1,2 @@
26eb392e2b8bc103f0aba289344134392ebd55e99a0254cce16327cc7ca4cf93 plugin-sdk-api-baseline.json
24f6b50b8c9a2b004491c335eab25786d9024869c710d1784e5748bae4bd0698 plugin-sdk-api-baseline.jsonl
5c810137267a9ddaeab9abc40219e4a02bafec32767533df06bcca7109ee1608 plugin-sdk-api-baseline.json
ec3183fad4412002a07d61359e7f62a7b9ca6b2ddf70ddb1d1afb713cf5d053a plugin-sdk-api-baseline.jsonl

2
docs/plugins/sdk-subpaths.md
View File

@@ -29,6 +29,7 @@ For the plugin authoring guide, see [Plugin SDK overview](/plugins/sdk-overview)
| `plugin-sdk/plugin-test-runtime` | Plugin runtime, registry, provider-registration, setup-wizard, and runtime task-flow fixtures for tests |
| `plugin-sdk/provider-test-contracts` | Provider runtime, auth, discovery, onboard, catalog, web-search/fetch, and wizard contract helpers |
| `plugin-sdk/test-env` | Test environment, fetch/network, live-test, temporary filesystem, and time-control fixtures |
| `plugin-sdk/test-fixtures` | Generic CLI, sandbox, skill, agent-message, system-event, terminal, chunking, auth-token, and typed-case test fixtures |
| `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` |
@@ -271,6 +272,7 @@ For the plugin authoring guide, see [Plugin SDK overview](/plugins/sdk-overview)
| `plugin-sdk/channel-test-helpers` | Channel-oriented test helpers for account startup lifecycle, directory assertions, send-config threading, runtime mocks, status issues, outbound delivery, and hook registration |
| `plugin-sdk/plugin-test-contracts` | Plugin package, registration, public artifact, direct import, runtime API, and import side-effect contract helpers |
| `plugin-sdk/provider-test-contracts` | Provider runtime, auth, discovery, onboard, catalog, wizard, web-search/fetch, and stream contract helpers |
| `plugin-sdk/test-fixtures` | Generic CLI runtime capture, sandbox context, skill writer, agent-message, system-event, terminal-text, chunking, auth-token, and typed-case fixtures |
</Accordion>
<Accordion title="Memory subpaths">

83
docs/plugins/sdk-testing.md
View File

@@ -35,6 +35,8 @@ plugins.
**Environment/network test import:** `openclaw/plugin-sdk/test-env`
**Generic fixture import:** `openclaw/plugin-sdk/test-fixtures`
The testing subpath exports a narrow set of helpers for plugin authors:
```typescript
@@ -50,45 +52,53 @@ import { describePluginRegistrationContract } from "openclaw/plugin-sdk/plugin-t
import { registerSingleProviderPlugin } from "openclaw/plugin-sdk/plugin-test-runtime";
import { describeOpenAIProviderRuntimeContract } from "openclaw/plugin-sdk/provider-test-contracts";
import { withEnv, withFetchPreconnect } from "openclaw/plugin-sdk/test-env";
import { createCliRuntimeCapture, typedCases } from "openclaw/plugin-sdk/test-fixtures";
```
### Available exports
| 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` |
| `createStartAccountContext` | Build channel account lifecycle contexts. Import from `plugin-sdk/channel-test-helpers` |
| `describePluginRegistrationContract` | Install plugin registration contract checks. Import from `plugin-sdk/plugin-test-contracts` |
| `registerSingleProviderPlugin` | Register one provider plugin in loader smoke tests. Import from `plugin-sdk/plugin-test-runtime` |
| `registerProviderPlugin` | Capture all provider kinds from one plugin. Import from `plugin-sdk/plugin-test-runtime` |
| `registerProviderPlugins` | Capture provider registrations across multiple plugins. Import from `plugin-sdk/plugin-test-runtime` |
| `requireRegisteredProvider` | Assert that a provider collection contains an id. Import from `plugin-sdk/plugin-test-runtime` |
| `createRuntimeEnv` | Build a mocked CLI/plugin runtime environment. Import from `plugin-sdk/plugin-test-runtime` |
| `createPluginSetupWizardStatus` | Build setup status helpers for channel plugins. Import from `plugin-sdk/plugin-test-runtime` |
| `describeOpenAIProviderRuntimeContract` | Install provider-family runtime contract checks. Import from `plugin-sdk/provider-test-contracts` |
| `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. Import from `plugin-sdk/test-env` |
| `withFetchPreconnect` | Run fetch tests with preconnect hooks installed. Import from `plugin-sdk/test-env` |
| `withEnv` / `withEnvAsync` | Temporarily patch environment variables. Import from `plugin-sdk/test-env` |
| `createTempHomeEnv` / `withTempDir` | Create isolated filesystem test fixtures. Import from `plugin-sdk/test-env` |
| `createMockServerResponse` | Create a minimal HTTP server response mock. Import from `plugin-sdk/test-env` |
| `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. Import from `plugin-sdk/test-env` |
| `createTestWizardPrompter` | Build a mocked setup wizard prompter |
| `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` |
| `createStartAccountContext` | Build channel account lifecycle contexts. Import from `plugin-sdk/channel-test-helpers` |
| `describePluginRegistrationContract` | Install plugin registration contract checks. Import from `plugin-sdk/plugin-test-contracts` |
| `registerSingleProviderPlugin` | Register one provider plugin in loader smoke tests. Import from `plugin-sdk/plugin-test-runtime` |
| `registerProviderPlugin` | Capture all provider kinds from one plugin. Import from `plugin-sdk/plugin-test-runtime` |
| `registerProviderPlugins` | Capture provider registrations across multiple plugins. Import from `plugin-sdk/plugin-test-runtime` |
| `requireRegisteredProvider` | Assert that a provider collection contains an id. Import from `plugin-sdk/plugin-test-runtime` |
| `createRuntimeEnv` | Build a mocked CLI/plugin runtime environment. Import from `plugin-sdk/plugin-test-runtime` |
| `createPluginSetupWizardStatus` | Build setup status helpers for channel plugins. Import from `plugin-sdk/plugin-test-runtime` |
| `describeOpenAIProviderRuntimeContract` | Install provider-family runtime contract checks. Import from `plugin-sdk/provider-test-contracts` |
| `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. Import from `plugin-sdk/test-env` |
| `withFetchPreconnect` | Run fetch tests with preconnect hooks installed. Import from `plugin-sdk/test-env` |
| `withEnv` / `withEnvAsync` | Temporarily patch environment variables. Import from `plugin-sdk/test-env` |
| `createTempHomeEnv` / `withTempDir` | Create isolated filesystem test fixtures. Import from `plugin-sdk/test-env` |
| `createMockServerResponse` | Create a minimal HTTP server response mock. Import from `plugin-sdk/test-env` |
| `createCliRuntimeCapture` | Capture CLI runtime output in tests. Import from `plugin-sdk/test-fixtures` |
| `createSandboxTestContext` | Build sandbox test contexts. Import from `plugin-sdk/test-fixtures` |
| `writeSkill` | Write skill fixtures. Import from `plugin-sdk/test-fixtures` |
| `makeAgentAssistantMessage` | Build agent transcript message fixtures. Import from `plugin-sdk/test-fixtures` |
| `peekSystemEvents` / `resetSystemEventsForTest` | Inspect and reset system event fixtures. Import from `plugin-sdk/test-fixtures` |
| `sanitizeTerminalText` | Sanitize terminal output for assertions. Import from `plugin-sdk/test-fixtures` |
| `countLines` / `hasBalancedFences` | Assert chunking output shape. Import from `plugin-sdk/test-fixtures` |
| `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. Import from `plugin-sdk/test-env` |
| `createTestWizardPrompter` | Build a mocked setup wizard prompter |
| `createRuntimeTaskFlow` | Create isolated runtime task-flow state |
| `typedCases` | Preserve literal types for table-driven tests. Import from `plugin-sdk/test-fixtures` |
Bundled-plugin contract suites also use SDK testing subpaths for test-only
registry, manifest, public-artifact, and runtime fixture helpers. Core-only
@@ -97,7 +107,8 @@ 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`, `plugin-sdk/channel-test-helpers`,
`plugin-sdk/plugin-test-contracts`, `plugin-sdk/plugin-test-runtime`,
`plugin-sdk/provider-test-contracts`, or `plugin-sdk/test-env` rather than
`plugin-sdk/provider-test-contracts`, `plugin-sdk/test-env`, or
`plugin-sdk/test-fixtures` rather than
importing repo `src/**` files or repo `test/helpers/plugins/*` bridges directly.
### Types

2
extensions/browser/test-support.ts
View File

@@ -3,7 +3,7 @@ export {
expectGeneratedTokenPersistedToGatewayAuth,
type CliMockOutputRuntime,
type CliRuntimeCapture,
} from "openclaw/plugin-sdk/testing";
} from "openclaw/plugin-sdk/test-fixtures";
export {
createTempHomeEnv,
withEnv,

2
extensions/codex/src/app-server/transcript-mirror.test.ts
View File

@@ -10,7 +10,7 @@ import {
castAgentMessage,
makeAgentAssistantMessage,
makeAgentUserMessage,
} from "openclaw/plugin-sdk/testing";
} from "openclaw/plugin-sdk/test-fixtures";
import { afterEach, describe, expect, it } from "vitest";
import { mirrorCodexAppServerTranscript } from "./transcript-mirror.js";

4
extensions/deepinfra/index.test.ts
View File

@@ -1,8 +1,8 @@
import { describe, expect, it } from "vitest";
import {
createCapturedPluginRegistration,
registerSingleProviderPlugin,
} from "openclaw/plugin-sdk/testing";
} from "openclaw/plugin-sdk/plugin-test-runtime";
import { describe, expect, it } from "vitest";
import deepinfraPlugin from "./index.js";
describe("deepinfra augmentModelCatalog", () => {

2
extensions/deepinfra/onboard.test.ts
View File

@@ -6,7 +6,7 @@ import {
type OpenClawConfig,
resolveAgentModelPrimaryValue,
} from "openclaw/plugin-sdk/provider-onboard";
import { captureEnv } from "openclaw/plugin-sdk/testing";
import { captureEnv } from "openclaw/plugin-sdk/test-env";
import { afterEach, describe, expect, it, vi } from "vitest";
import {
applyDeepInfraProviderConfig,

2
extensions/discord/src/chunk.test.ts
View File

@@ -1,4 +1,4 @@
import { countLines, hasBalancedFences } from "openclaw/plugin-sdk/testing";
import { countLines, hasBalancedFences } from "openclaw/plugin-sdk/test-fixtures";
import { describe, expect, it } from "vitest";
import { chunkDiscordText, chunkDiscordTextWithMode } from "./chunk.js";

2
extensions/discord/src/monitor.test.ts
View File

@@ -1,5 +1,5 @@
import { ChannelType, type Guild } from "@buape/carbon";
import { typedCases } from "openclaw/plugin-sdk/testing";
import { typedCases } from "openclaw/plugin-sdk/test-fixtures";
import { beforeEach, describe, expect, it, vi } from "vitest";
import {
allowListMatches,

2
extensions/discord/src/monitor/monitor.agent-components.test.ts
View File

@@ -2,7 +2,7 @@ import type { ButtonInteraction, ComponentData, StringSelectMenuInteraction } fr
import { ChannelType } from "discord-api-types/v10";
import type { DiscordAccountConfig, OpenClawConfig } from "openclaw/plugin-sdk/config-types";
import { buildAgentSessionKey } from "openclaw/plugin-sdk/routing";
import { peekSystemEvents, resetSystemEventsForTest } from "openclaw/plugin-sdk/testing";
import { peekSystemEvents, resetSystemEventsForTest } from "openclaw/plugin-sdk/test-fixtures";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { expectPairingReplyText } from "../../../../test/helpers/pairing-reply.js";
import {

2
extensions/imessage/src/monitor/inbound-processing.test.ts
View File

@@ -1,5 +1,5 @@
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
import { sanitizeTerminalText } from "openclaw/plugin-sdk/testing";
import { sanitizeTerminalText } from "openclaw/plugin-sdk/test-fixtures";
import { describe, expect, it, vi } from "vitest";
import {
describeIMessageEchoDropLog,

2
extensions/memory-core/src/cli.test.ts
View File

@@ -7,7 +7,7 @@ import {
spyRuntimeErrors,
spyRuntimeJson,
spyRuntimeLogs,
} from "openclaw/plugin-sdk/testing";
} from "openclaw/plugin-sdk/test-fixtures";
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
import { readShortTermRecallEntries, recordShortTermRecalls } from "./short-term-promotion.js";

2
extensions/openshell/src/backend.e2e.test.ts
View File

@@ -3,7 +3,7 @@ import fs from "node:fs/promises";
import net from "node:net";
import os from "node:os";
import path from "node:path";
import { createSandboxTestContext } from "openclaw/plugin-sdk/testing";
import { createSandboxTestContext } from "openclaw/plugin-sdk/test-fixtures";
import { describe, expect, it } from "vitest";
import {
createSandboxBrowserConfig,

2
extensions/openshell/src/openshell-core.test.ts
View File

@@ -2,7 +2,7 @@ import nodeFs from "node:fs";
import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { createSandboxTestContext } from "openclaw/plugin-sdk/testing";
import { createSandboxTestContext } from "openclaw/plugin-sdk/test-fixtures";
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
import type { OpenShellSandboxBackend } from "./backend.js";
import {

2
extensions/telegram/src/test-support/write-skill.ts
View File

@@ -1 +1 @@
export { writeSkill } from "openclaw/plugin-sdk/testing";
export { writeSkill } from "openclaw/plugin-sdk/test-fixtures";

4
package.json
View File

@@ -526,6 +526,10 @@
"types": "./dist/plugin-sdk/test-env.d.ts",
"default": "./dist/plugin-sdk/test-env.js"
},
"./plugin-sdk/test-fixtures": {
"types": "./dist/plugin-sdk/test-fixtures.d.ts",
"default": "./dist/plugin-sdk/test-fixtures.js"
},
"./plugin-sdk/testing": {
"types": "./dist/plugin-sdk/testing.d.ts",
"default": "./dist/plugin-sdk/testing.js"

2
scripts/check-no-extension-test-core-imports.ts
View File

@@ -47,6 +47,8 @@ const MOCK_RELATIVE_MODULE_PATTERN =
const RELATIVE_CORE_HINT =
"Use openclaw/plugin-sdk/testing or a focused plugin-sdk test/runtime subpath instead of core internals.";
// Tombstones for retired repo-only plugin helper bridge files. Keep this list so
// deleted bridges fail loudly if they are recreated instead of using SDK subpaths.
const RETIRED_EXTENSION_TEST_HELPER_BRIDGE_FILES = [
"test/helpers/plugins/env.ts",
"test/helpers/plugins/fetch-mock.ts",

3
scripts/lib/plugin-sdk-doc-metadata.ts
View File

@@ -119,6 +119,9 @@ export const pluginSdkDocMetadata = {
"test-env": {
category: "utilities",
},
"test-fixtures": {
category: "utilities",
},
} as const satisfies Record<string, PluginSdkDocMetadata>;
export type PluginSdkDocEntrypoint = keyof typeof pluginSdkDocMetadata;

1
scripts/lib/plugin-sdk-entrypoints.json
View File

@@ -115,6 +115,7 @@
"plugin-test-runtime",
"provider-test-contracts",
"test-env",
"test-fixtures",
"testing",
"temp-path",
"logging-core",

22
src/plugin-sdk/test-fixtures.ts Normal file
View File

@@ -0,0 +1,22 @@
// Focused public test helpers for generic fixtures shared by plugin tests.
export {
createCliRuntimeCapture,
firstWrittenJsonArg,
spyRuntimeErrors,
spyRuntimeJson,
spyRuntimeLogs,
} from "../cli/test-runtime-capture.js";
export type { CliMockOutputRuntime, CliRuntimeCapture } from "../cli/test-runtime-capture.js";
export { createSandboxTestContext } from "../agents/sandbox/test-fixtures.js";
export { writeSkill } from "../agents/skills.e2e-test-helpers.js";
export {
castAgentMessage,
makeAgentAssistantMessage,
makeAgentUserMessage,
} from "../agents/test-helpers/agent-message-fixtures.js";
export { peekSystemEvents, resetSystemEventsForTest } from "../infra/system-events.js";
export { sanitizeTerminalText } from "../terminal/safe-text.js";
export { countLines, hasBalancedFences } from "../test-utils/chunk-test-helpers.js";
export { expectGeneratedTokenPersistedToGatewayAuth } from "../test-utils/auth-token-assertions.js";
export { typedCases } from "../test-utils/typed-cases.js";

8
src/plugins/contracts/plugin-sdk-subpaths.test.ts
View File

@@ -60,6 +60,7 @@ const PUBLIC_SDK_TEST_HELPER_SUBPATHS = [
"plugin-test-runtime",
"provider-test-contracts",
"test-env",
"test-fixtures",
] as const;
const importResolvedPluginSdkSubpath = async (specifier: string) => import(specifier);
@@ -747,6 +748,13 @@ describe("plugin-sdk subpath exports", () => {
"installPinnedHostnameTestHooks",
"isLiveTestEnabled",
]);
expectSourceMentions("test-fixtures", [
"createCliRuntimeCapture",
"createSandboxTestContext",
"makeAgentAssistantMessage",
"peekSystemEvents",
"typedCases",
]);
});
it("keeps public SDK test helper subpaths free of top-level Vitest module mocks", () => {