@systemfsoftware/xstate-test 0.0.0-stage → 2.0.0-beta.2

package/dist/propertyTest-BHnBV8ax.d.ts

@@ -0,0 +1,147 @@
+import { n as FastCheckGeneratorKind, t as FastCheckAdapterOptions } from "./adapter-Dd4Go0U3.js";
+import { G as TestEventGenerators, J as TestFailureStore, R as PropertyTestOptions, V as TestAdapter, _t as TestCoverage, a as GenerateTestSuiteOptions, gt as SnapshotFromSource, ht as InputFromSource, mt as EventFromSource, n as TestPathsOptions, r as TestPathsResult, s as TestSuite } from "./index-CSbyUxJr.js";
+import { ActorLogic, EventObject, Snapshot } from "@systemfsoftware/xstate";
+/**
+ * Options for the file-system failure database. See `failures`.
+ *
+ * @experimental
+ */
+interface FailureDatabaseOptions {
+  /** The directory failures are saved in. Defaults to `'.xstate-test'`. */
+  readonly dir?: string;
+  /**
+   * `'first'` (the default) replays saved failures before the campaign and
+   * fails on the first one that still reproduces. `'only'` replays them and
+   * skips the campaign. `false` saves failures without replaying them.
+   */
+  readonly replay?: 'first' | 'only' | false;
+  /**
+   * The subdirectory of `dir` the failures of this test are saved in.
+   * Defaults to the machine id plus a hash of the configured event cases and
+   * oracles. Set it when two tests run the same machine with different
+   * oracles, so each replays only its own failures.
+   */
+  readonly key?: string;
+}
+/**
+ * The accepted values of the `failures` option.
+ *
+ * @experimental
+ */
+type FailuresOption = boolean | FailureDatabaseOptions | TestFailureStore;
+/**
+ * A {@link TestFailureStore} that saves each failing fixture as
+ * `<dir>/<key>/<hash>.json`. Node's `fs` is loaded only when a campaign reads
+ * or writes a failure, so importing `@xstate/test` stays free of Node APIs.
+ *
+ * @experimental
+ */
+declare function createFailureDatabase(options?: FailureDatabaseOptions): TestFailureStore;
+/** The options the wrappers add to, or reshape from, `xstate/graph`. */
+interface DeriveEventsOptions {
+  /**
+   * Saves the fixture of a failing campaign to disk, and replays saved
+   * fixtures before the next campaign. `true` uses the defaults: the
+   * `.xstate-test` directory and `replay: 'first'`. A `TestFailureStore`
+   * object is used as-is.
+   */
+  readonly failures?: FailuresOption;
+  /**
+   * Derives a generator, via `eventsFromSchemas()`, for every event type the
+   * machine declares in `schemas.events` and that `events` does not already
+   * configure. Defaults to `true`; machines that declare no `schemas.events`
+   * are unaffected either way.
+   *
+   * Only declared runtime schemas are derived from. An event type the machine
+   * handles but declares no schema for is left out rather than generated as
+   * `{}`, and a type-only `types<...>()` declaration is skipped because it
+   * carries no runtime structure. A runtime schema the converters do not
+   * recognize throws, unless `events` already covers that event type.
+   */
+  readonly deriveEvents?: boolean;
+}
+/**
+ * `PropertyTestOptions` with the generator kind fixed to fast-check:
+ * `events`, `commands` and `outcomes` take `fc.Arbitrary` values, and every
+ * fast-check option is accepted at the top level.
+ *
+ * @experimental
+ */
+type FastCheckPropertyTestOptions<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject, TInput> = Omit<PropertyTestOptions<TSnapshot, TEvent, TInput, FastCheckGeneratorKind>, 'adapter' | 'events' | 'failures'> & FastCheckAdapterOptions & DeriveEventsOptions & {
+  /**
+   * Overrides the implicit fast-check adapter. Any generator kind is
+   * accepted here, so a non-fast-check adapter can be dropped in; `events`
+   * and `commands` are still typed against fast-check, so such an adapter
+   * usually wants `propertyTest()` from `xstate/graph` instead.
+   */
+  readonly adapter?: TestAdapter<any>;
+  /**
+   * Optional when the machine declares `schemas.events`; the generators are
+   * derived from those schemas, and entries here override the derived ones.
+   */
+  readonly events?: TestEventGenerators<TSnapshot, TEvent, FastCheckGeneratorKind>;
+};
+/** @experimental */
+type FastCheckGenerateTestSuiteOptions<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject, TInput> = FastCheckPropertyTestOptions<TSnapshot, TEvent, TInput> & Omit<GenerateTestSuiteOptions<TSnapshot, TEvent, TInput, FastCheckGeneratorKind>, keyof PropertyTestOptions<TSnapshot, TEvent, TInput, FastCheckGeneratorKind>>;
+/**
+ * Runs a property-testing campaign with fast-check as the generator.
+ *
+ * Identical to `propertyTest()` from `xstate/graph`, except that fast-check
+ * options (`seed`, `numRuns`, `maxCommands`, `scheduler`, …) are top-level
+ * options rather than `fastCheckAdapter()` arguments, and `events` is derived
+ * from the machine's `schemas.events` when it declares them.
+ *
+ * @experimental
+ */
+declare const propertyTest: {
+  <TSource extends ActorLogic<any, any, any>>(options: FastCheckPropertyTestOptions<SnapshotFromSource<TSource>, EventFromSource<TSource>, InputFromSource<TSource>>): (source: TSource) => Promise<{
+    coverage: TestCoverage;
+  }>;
+  <TSource extends ActorLogic<any, any, any>>(source: TSource, options: FastCheckPropertyTestOptions<SnapshotFromSource<TSource>, EventFromSource<TSource>, InputFromSource<TSource>>): Promise<{
+    coverage: TestCoverage;
+  }>;
+};
+/**
+ * Records an offline property suite from a passing campaign, with fast-check
+ * as the generator. See `generateTestSuite()` in `xstate/graph`.
+ *
+ * @experimental
+ */
+declare const generateTestSuite: {
+  <TSource extends ActorLogic<any, any, any>>(options: FastCheckGenerateTestSuiteOptions<SnapshotFromSource<TSource>, EventFromSource<TSource>, InputFromSource<TSource>>): (source: TSource) => Promise<TestSuite>;
+  <TSource extends ActorLogic<any, any, any>>(source: TSource, options: FastCheckGenerateTestSuiteOptions<SnapshotFromSource<TSource>, EventFromSource<TSource>, InputFromSource<TSource>>): Promise<TestSuite>;
+};
+/**
+ * `TestPathsOptions` with the generator kind fixed to fast-check:
+ * `events` takes `fc.Arbitrary` values, which are sampled into concrete
+ * payloads before traversal.
+ *
+ * @experimental
+ */
+type FastCheckTestPathsOptions<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject, TInput> = Omit<TestPathsOptions<TSnapshot, TEvent, TInput>, 'events' | 'outcomes' | 'failures'> & DeriveEventsOptions & {
+  readonly events?: TestEventGenerators<TSnapshot, TEvent, FastCheckGeneratorKind>;
+  /**
+   * Invoke sources whose outcomes are sampled from fast-check arbitraries
+   * and routed through the `xstate.done.actor` / `xstate.error.actor` steps
+   * traversal took. In pure mode the sampled `output` or `error` is the
+   * payload of that step's event; in executed mode the source is stubbed
+   * and the stub resolves with it.
+   */
+  readonly outcomes?: TestPathsOptions<TSnapshot, TEvent, TInput, FastCheckGeneratorKind>['outcomes'];
+};
+/**
+ * Executes model paths against a system under test.
+ *
+ * The same options as `propertyTest()`, minus the generation controls
+ * (`numRuns`, `maxCommands`, `swarm`, `frontiers`, …) and plus the traversal
+ * controls (`pathGenerator`, `limit`, `toState`, `samples`, `seed`). fast-check
+ * arbitraries are accepted in `events` and sampled into `samples` concrete
+ * payloads before traversal.
+ *
+ * @experimental
+ */
+declare const testPaths: {
+  <TSource extends ActorLogic<any, any, any>>(options?: FastCheckTestPathsOptions<SnapshotFromSource<TSource>, EventFromSource<TSource>, InputFromSource<TSource>>): (source: TSource) => Promise<TestPathsResult<SnapshotFromSource<TSource>, EventFromSource<TSource>>>;
+  <TSource extends ActorLogic<any, any, any>>(source: TSource, options?: FastCheckTestPathsOptions<SnapshotFromSource<TSource>, EventFromSource<TSource>, InputFromSource<TSource>>): Promise<TestPathsResult<SnapshotFromSource<TSource>, EventFromSource<TSource>>>;
+};
+export { propertyTest as a, FailuresOption as c, generateTestSuite as i, createFailureDatabase as l, FastCheckPropertyTestOptions as n, testPaths as o, FastCheckTestPathsOptions as r, FailureDatabaseOptions as s, FastCheckGenerateTestSuiteOptions as t };

package/dist/schema.d.ts

@@ -0,0 +1,59 @@
+import { n as FastCheckGeneratorKind } from "./adapter-Dd4Go0U3.js";
+import { G as TestEventGenerators } from "./index-CSbyUxJr.js";
+import { AnyStateMachine, EventFrom, SnapshotFrom } from "@systemfsoftware/xstate";
+import * as fc from "fast-check";
+/**
+ * Converts a single payload schema into a FastCheck arbitrary. Returns
+ * `undefined` when the converter does not recognize the schema.
+ *
+ * @experimental
+ */
+export type SchemaConverter = (schema: unknown, path: string) => fc.Arbitrary<unknown> | undefined;
+/** @experimental */
+export interface EventsFromSchemasOptions {
+  /**
+   * What to do with event types that the machine handles but that have no
+   * declared schema, under either their own key or a matching wildcard key
+   * (`'user.*'`).
+   *
+   * - `'empty'` (default) generates `{}` for them.
+   * - `'skip'` leaves them out of the returned map.
+   */
+  readonly eventsWithoutSchema?: 'empty' | 'skip';
+  /**
+   * Converts schemas that are not recognized by the built-in converters.
+   * Return `undefined` to fall through to the built-in error.
+   */
+  readonly fallback?: SchemaConverter;
+}
+/**
+ * Converts a declared payload schema into a FastCheck arbitrary. Only schema
+ * libraries whose structure can be inspected are supported; a Standard Schema
+ * alone only validates, so nothing can be generated from it.
+ *
+ * @experimental
+ */
+export declare function arbitraryFromSchema(schema: unknown, options?: EventsFromSchemasOptions, path?: string): fc.Arbitrary<unknown>;
+/**
+ * Derives event generators from the event schemas declared on a machine
+ * (`setup({ schemas: { events } })` or `createMachine({ schemas: { events } })`).
+ *
+ * Type-only event declarations (`types.events`) are erased at runtime and
+ * cannot be used here.
+ *
+ * @experimental
+ */
+export declare const eventsFromSchemas: {
+  <TMachine extends AnyStateMachine>(options?: EventsFromSchemasOptions): (machine: TMachine) => TestEventGenerators<SnapshotFrom<TMachine>, EventFrom<TMachine>, FastCheckGeneratorKind>;
+  <TMachine extends AnyStateMachine>(machine: TMachine, options?: EventsFromSchemasOptions): TestEventGenerators<SnapshotFrom<TMachine>, EventFrom<TMachine>, FastCheckGeneratorKind>;
+};
+/**
+ * Merges derived generators with explicit ones. Explicit entries win for event
+ * types declared in both.
+ *
+ * @experimental
+ */
+export declare const mergeEventGenerators: {
+  <TDerived, TExplicit>(explicit: TExplicit): (derived: TDerived) => TDerived & TExplicit;
+  <TDerived, TExplicit>(derived: TDerived, explicit: TExplicit): TDerived & TExplicit;
+};