stem_adapter_tests 0.1.1

Shared contract test suites for Stem broker and result backend adapters.

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

Flag	Default	Affects	Behavior when enabled
verifyPriorityOrdering	true	Broker priority test group	Verifies higher-priority messages are delivered first.
verifyBroadcastFanout	false	Broadcast fan-out test group	Verifies broadcast delivery reaches all subscribers and replay semantics remain correct.

ResultBackendContractCapabilities

Flag	Default	Affects	Behavior when enabled
verifyTaskStatusExpiry	true	Task status expiry tests	Verifies status TTL expiration behavior.
verifyGroupExpiry	true	Group expiry tests	Verifies group TTL expiration and post-expiry behavior.
verifyChordClaiming	true	Chord claiming tests	Verifies single-claimant callback dispatch semantics.
verifyWorkerHeartbeats	true	Heartbeat CRUD tests	Verifies heartbeat set/get/list/update behavior.
verifyHeartbeatExpiry	true	Heartbeat expiry tests	Verifies heartbeat TTL expiration behavior independently from heartbeat CRUD checks.

QueueEventsContractCapabilities

Flag	Default	Affects	Behavior when enabled
verifyFanout	true	Multi-listener fan-out tests	Verifies custom queue events reach all active listeners on the same queue scope.

WorkflowStoreContractCapabilities

Flag	Default	Affects	Behavior when enabled
verifyVersionedCheckpoints	true	Checkpoint versioning tests	Verifies versioned checkpoint persistence and retrieval.
verifyRunLeases	true	Run lease tests	Verifies claim/renew/release lease semantics.
verifyWatcherRegistry	true	Watcher tests	Verifies watcher registration, listing, and resolution behavior.
verifyRunsWaitingOn	true	Waiting-topic lookup tests	Verifies lookups for runs waiting on external topics.
verifyFilteredRunListing	true	Filtered run listing tests	Verifies filtered listing and pagination semantics.

LockStoreContractCapabilities

Flag	Default	Affects	Behavior when enabled
verifyOwnerLookup	true	ownerOf tests	Verifies lock owner lookup behavior.
verifyRenewSemantics	true	Renew and expiry tests	Verifies renewal/TTL semantics for active locks.

RevokeStoreContractCapabilities

Flag	Default	Affects	Behavior when enabled
verifyPruneExpired	true	Revoke expiry pruning tests	Verifies pruneExpired removes only expired revocations in the target namespace.

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.