stem_adapter_tests #

Shared contract suites for adapter packages. Use this package to prove your broker, result backend, workflow store, and lock store semantics match Stem's runtime expectations.

Install #

dart pub add --dev stem_adapter_tests

Quick Start #

import 'package:stem_adapter_tests/stem_adapter_tests.dart';

void main() {
  runBrokerContractTests(
    adapterName: 'my-adapter',
    factory: BrokerContractFactory(create: createBroker),
  );

  runResultBackendContractTests(
    adapterName: 'my-adapter',
    factory: ResultBackendContractFactory(create: createBackend),
  );

  runQueueEventsContractTests(
    adapterName: 'my-adapter',
    factory: QueueEventsContractFactory(create: createBroker),
  );

  final workflowFactory = WorkflowStoreContractFactory(
    create: createWorkflowStore,
  );

  runWorkflowStoreContractTests(
    adapterName: 'my-adapter',
    factory: workflowFactory,
  );

  runWorkflowScriptFacadeTests(
    adapterName: 'my-adapter',
    factory: workflowFactory,
  );
}

Capability Flags #

Capability flags let adapters opt out of specific behavior checks while keeping all other contract assertions active.

BrokerContractCapabilities #

ResultBackendContractCapabilities #

QueueEventsContractCapabilities #

WorkflowStoreContractCapabilities #

LockStoreContractCapabilities #

RevokeStoreContractCapabilities #

Skip Behavior #

Each flagged test uses explicit skip values (instead of implicit omission) so it is always clear which capability disabled a test and why.

Adapter Recipes #

Full-feature adapter #

runResultBackendContractTests(
  adapterName: 'full-adapter',
  factory: ResultBackendContractFactory(create: createBackend),
  settings: const ResultBackendContractSettings(
    capabilities: ResultBackendContractCapabilities(),
  ),
);

Adapter without broadcast fan-out #

runBrokerContractTests(
  adapterName: 'queue-only-adapter',
  factory: BrokerContractFactory(create: createBroker),
  settings: const BrokerContractSettings(
    capabilities: BrokerContractCapabilities(
      verifyBroadcastFanout: false,
    ),
  ),
);

Adapter with heartbeat CRUD but no heartbeat expiry #

runResultBackendContractTests(
  adapterName: 'no-heartbeat-expiry-adapter',
  factory: ResultBackendContractFactory(create: createBackend),
  settings: const ResultBackendContractSettings(
    capabilities: ResultBackendContractCapabilities(
      verifyWorkerHeartbeats: true,
      verifyHeartbeatExpiry: false,
    ),
  ),
);

Adapter without queue-event fan-out #

runQueueEventsContractTests(
  adapterName: 'single-listener-adapter',
  factory: QueueEventsContractFactory(create: createBroker),
  settings: const QueueEventsContractSettings(
    capabilities: QueueEventsContractCapabilities(
      verifyFanout: false,
    ),
  ),
);

Workflow Clock Requirement #

Workflow store factories receive a shared FakeWorkflowClock. Inject that same clock into your runtime/store under test so workflow facade and store assertions observe the same deterministic timeline.

Versioning #

This package tracks the same release cadence as stem.