Skip to Content
Reference@streamsy/core

Testing

Reference for the @streamsy/core/testing entry point. It has the storage contract tests, fault injection, and a protocol Layer for tests.

import {
  StorageContract,
  StreamsTest,
  expectFailureTag,
  faultyStorage,
  layerTest,
  type StorageContractOptions,
} from "@streamsy/core/testing";
import type { ChangeSnapshot, Storage, StorageCapabilities, StreamId } from "@streamsy/core";
import type { Protocol, StreamsReader, StreamsWriter } from "@streamsy/core/protocol";
import type { Context, Effect, Layer } from "effect";

The exports of @streamsy/core/testing test storage adapters and protocol code. StorageContract and expectFailureTag call Vitest, so import this entry point only in test files that Vitest runs. Application tests provide MemoryStorage.layer(group) instead. See Testing.

Storage contract

StorageContract

declare const StorageContract: {
  run(options: StorageContractOptions): void;
  assertModes(configurations: ReadonlyArray<StorageCapabilities>): void;
};

StorageContract holds the contract tests that every storage adapter must pass. See Contract tests.

run registers a Vitest describe block named options.name, with one test for each rule of the contract.

  • Each test builds a new options.layer, with a TestClock.
  • Each test first checks that capabilities of the store equals options.expected.
  • run skips each test of a capability that options.expected rules out, for example the fork tests when fork is none.
  • The tests of CommitBoundary, the owner records, the commit hooks, and the projection marks run only when options.ownerRecords is true. They check that the records, the marks, and the stream writes commit and roll back together, that owner record keys of any length stay distinct, and that a commit hook sees the ids of each write before the commit.

assertModes registers one test. It checks that configurations holds both values of each capability that the shipped stores have: chain and copy, store and stream, push and poll, and indexed and lazy. Call it with the expected capabilities of each run of a configurable store, to check that the runs cover both modes.

StorageContractOptions

interface StorageContractOptions {
  readonly name: string;
  readonly layer: Layer.Layer<Storage>;
  readonly expected: StorageCapabilities;
  readonly ownerRecords?: boolean;
}

StorageContractOptions holds the options of StorageContract.run.

OptionMeaning
nameThe name of the describe block
layerThe Layer of the adapter under test
expectedThe StorageCapabilities that the adapter must report
ownerRecordstrue when layer also provides CommitBoundary, and the owner records, commit hooks, and projection marks that projections need

faultyStorage

declare function faultyStorage(
  source: Layer.Layer<Storage>,
  options: {
    readonly failOn: number;
    readonly when: "before" | "after";
  },
): Layer.Layer<Storage>;

faultyStorage wraps the store of source so that one mutate call fails with a retryable StorageFault. The call that fails is the failOnth call, counted from 1, after each build of the Layer.

  • With when: "before", the call fails and the store does not apply the mutation.
  • With when: "after", the store applies the mutation, and then the call fails. Use after to test a write whose reply is lost.

Every other call passes to the store unchanged. Building the Layer dies with a RangeError when failOn is not a positive integer.

Protocol tests

layerTest

declare const layerTest: (
  options?: MemoryOptions & Protocol.ProtocolOptions,
) => Layer.Layer<StreamsReader | StreamsTest | StreamsWriter>;

// MemoryOptions has no exported name. It holds the memory options of MemoryStorage.Options.
type MemoryOptions = {
  readonly constrained?: boolean;
  readonly pollIntervalMs?: number;
};

layerTest returns a Layer with the real protocol reader and writer over a new memory store, and a StreamsTest service that watches the store. The options mean the same as in MemoryStorage.Options. To test stream classes, bind them to it:

import { Protocol } from "@streamsy/core/protocol";
import { layerTest } from "@streamsy/core/testing";
import { shop } from "./streams.ts";

const streams = Protocol.bind(layerTest(), shop);

StreamsTest

class StreamsTest extends Context.Service<
  StreamsTest,
  {
    readonly storage: typeof Storage.Service;
    readonly subscribers: Effect.Effect<number>;
    readonly snapshot: Effect.Effect<{
      readonly id: StreamId;
      readonly value: ChangeSnapshot;
    }>;
  }
>()("@streamsy/core/StreamsTest") {}

StreamsTest is the service that layerTest provides. It lets a test see the changes subscriptions of the store, so the test can wait for a live read without a sleep.

MemberDoes
storageThe store under the protocol Layer
subscribersSucceeds with the number of changes subscriptions that are open now
snapshotWaits for the next ChangeSnapshot that any subscription emits, and succeeds with it and its stream id

expectFailureTag

declare const expectFailureTag: <A, E extends { readonly _tag: string }, R>(
  effect: Effect.Effect<A, E, R>,
  tag: E["_tag"],
) => Effect.Effect<E, A, R>;

expectFailureTag swaps the success and the failure of effect, and checks with the Vitest expect that the error has the _tag tag. It succeeds with the error. When effect succeeds, the result fails with the success value, so the test cannot pass.

On this page