Skip to main content

​
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.