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 aTestClock. - Each test first checks that
capabilitiesof the store equalsoptions.expected. runskips each test of a capability thatoptions.expectedrules out, for example the fork tests whenforkisnone.- The tests of
CommitBoundary, the owner records, the commit hooks, and the projection marks run only whenoptions.ownerRecordsistrue. 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.
| Option | Meaning |
|---|---|
name | The name of the describe block |
layer | The Layer of the adapter under test |
expected | The StorageCapabilities that the adapter must report |
ownerRecords | true 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. Useafterto 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.
| Member | Does |
|---|---|
storage | The store under the protocol Layer |
subscribers | Succeeds with the number of changes subscriptions that are open now |
snapshot | Waits 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.
StreamRoute
Reference for the StreamRoute namespace in @streamsy/core/protocol. A route owns the id grammar of a stream class and builds the address of each id.
Projection constructors
Reference for the constructors of the Projection namespace in @streamsy/projection. A constructor declares a projection over input streams, and its at method binds the params.