> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Contract tests

## Contract tests (plugin and channel shape)

Contract tests verify that every registered plugin and channel conforms to
its interface contract. They iterate over all discovered plugins and run a
suite of shape and behavior assertions. The default `pnpm test` unit lane
intentionally skips these shared seam and smoke files; run the contract
commands explicitly when you touch shared channel or provider surfaces.

### Commands

* All contracts: `pnpm test:contracts`
* Channel contracts only: `pnpm test:contracts:channels`
* Provider contracts only: `pnpm test:contracts:plugins`

### Channel contracts

Located in `src/channels/plugins/contracts/*.contract.test.ts`. Current
top-level categories:

* **channel-catalog** - bundled/registry channel catalog entry metadata
* **plugin** (registry-backed, sharded) - basic plugin registration shape
* **surfaces-only** (registry-backed, sharded) - per-surface shape checks for `actions`, `setup`, `status`, `outbound`, `messaging`, `threading`, `directory`, and `gateway`
* **session-binding** (registry-backed) - session binding behavior
* **outbound-payload** - message payload structure and normalization
* **group-policy** (fallback) - default group policy enforcement per channel
* **threading** (registry-backed, sharded) - thread id handling
* **directory** (registry-backed, sharded) - directory/roster API
* **registry** and **plugins-core.\*** - channel plugin registry, loader, and config-write authorization internals

Inbound dispatch-capture and outbound-payload harness helpers used by these
suites are exposed internally through `src/plugin-sdk/channel-contract-testing.ts`
(npm-excluded, not a public SDK subpath); there is no standalone
`inbound.contract.test.ts` file in this directory.

### Provider contracts

Located in `src/plugins/contracts/*.contract.test.ts`. Current categories
include:

* **shape** - plugin manifest, API, and runtime export shape
* **plugin-registration** (+ parallel) - manifest registration cases
* **package-manifest** - package manifest requirements
* **loader** - plugin loader setup/teardown behavior
* **registry** - plugin contract registry contents and lookup
* **providers** - shared provider behavior across bundled providers, plus web-search providers
* **auth-choice** - auth choice metadata and setup behavior
* **provider-catalog-deprecation** - deprecated provider catalog metadata
* **wizard.choice-resolution**, **wizard.model-picker**, **wizard.setup-options** - provider setup wizard contracts
* **embedding-provider**, **memory-embedding-provider**, **web-fetch-provider**, **tts** - capability-specific provider contracts
* **session-actions**, **session-attachments**, **session-entry-projection** - plugin-owned session state contracts
* **scheduled-turns** - plugin scheduled turn metadata and timestamp bounds
* **host-hooks**, **run-context-lifecycle**, **runtime-import-side-effects**, **runtime-seams** - plugin host/runtime lifecycle and import-boundary contracts
* **extension-runtime-dependencies** - runtime dependency placement for extensions

### When to run

* After changing plugin-sdk exports or subpaths
* After adding or modifying a channel or provider plugin
* After refactoring plugin registration or discovery

Contract tests run in CI and do not require real API keys.