@gyral/testing

npm install @gyral/testing

function callsIn(commands: ReadonlyArray<Command<unknown>>): readonly CallInput[];

expect(callsIn(next.commands)).toEqual([{ selector: 'video', method: 'play', args: [] }]);

function collectErrors(): CollectedErrors;

function commandsFor<I, M>(commands: ReadonlyArray<Command<M>>, driver: Driver<I, unknown> | Named): ReadonlyArray<Command<M> & {
    readonly input: I;
}>;

function fakeDriver<I = unknown, O = unknown, E = unknown>(of: string | Driver<I, O, E>, optionsOrRun?: FakeOptions<I, O, E> | FakeRun<I, O>): FakeDriver<I, O, E>;

el.drivers = { 'url-sync': fakeDriver<string | null, void>('url-sync', (q) => void urls.push(q)) };

function focusTargetsIn(commands: ReadonlyArray<Command<unknown>>): readonly FocusTarget[];

expect(focusTargetsIn(next.commands)).toEqual([{ selector: '#results' }]);

function hydrated(page: MountedSsr | ParentNode, options?: HydratedOptions): Promise<void>;

function initial<S, M extends Tagged, P>(spec: ComponentSpec<S, M, P>, props?: P): Stepped<S, M>;

function inputsFor<S, SM extends Tagged>(commands: ReadonlyArray<Command<unknown>>, store: Store<S, SM>): readonly SM[];
function inputsFor<I, M>(commands: ReadonlyArray<Command<M>>, driver: Driver<I, unknown> | Named): readonly I[];

function mount<K extends keyof HTMLElementTagNameMap>(tag: K, options?: MountOptions<HTMLElementTagNameMap[K]>): Promise<Mounted<HTMLElementTagNameMap[K]>>;
function mount<E extends HTMLElement>(component: Constructor<E> | string, options?: MountOptions<E>): Promise<Mounted<E>>;

function mountSsr(html: string, options?: MountSsrOptions): MountedSsr;

function outputsIn<C extends WithOutputs>(commands: ReadonlyArray<Command<unknown>>, component: C): ReadonlyArray<OutputsOf<C>>;
function outputsIn<O extends Tagged = Tagged>(commands: ReadonlyArray<Command<unknown>>): readonly O[];

expect(outputsIn(next.commands, Item)).toEqual([{ _tag: 'Picked', id: 1 }]);

function parse<S, M extends Tagged, P, N extends string, K extends N>(component: SpecOf<S, M, P, N>, name: K, input?: Partial<IntentInput>, options?: ParseOptions<NoInfer<S>, NoInfer<P>>): Parsed<M, K> | IntentRejected | undefined | Promise<Parsed<M, K> | IntentRejected | undefined>;

function reject<M>(command: Command<M>, error: unknown): M | undefined;

function resetDocumentStores(): void;

function resolve<M>(command: Command<M>, output: unknown): M | undefined;

function run<S, M extends Tagged, P>(spec: ComponentSpec<S, M, P>, messages: ReadonlyArray<NoInfer<StepMessage<M, P>>>, options?: NoInfer<RunOptions<S, P>>): Ran<S, M>;

function step<S, M extends Tagged, P>(spec: ComponentSpec<S, M, P>, state: NoInfer<S>, msg: NoInfer<StepMessage<M, P>>, props?: NoInfer<P>, stores?: readonly AnyStoreInstance[]): Stepped<S, M>;

function stepStore<S, M extends Tagged>(store: Store<S, M>, state: NoInfer<S>, msg: NoInfer<M>): Stepped<S, M>;

function subscriptionsFor<S, M extends Tagged, P>(spec: ComponentSpec<S, M, P>, state: NoInfer<S>, props?: NoInfer<P>): ReadonlyArray<Command<M>>;

function viewOf<S, M extends Tagged, P, N extends string>(component: ComponentSpec<S, M, P, N> | GyralElementClass<S, M, P, Tagged, N>, state: NoInfer<S>, options?: ViewOptions<NoInfer<P>>): ChildValue;

function virtualTime(): VirtualTime;

interface CollectedErrors {
    readonly errors: readonly GyralError[];
    /** Stops collecting; later failures are reported as usual. */
    stop(): void;
}

interface FakeCall<I, O> {
    readonly input: I;
    readonly signal: AbortSignal;
    /** Settles this call (only for fakes without `impl`). */
    readonly resolve: (output: O) => void;
    readonly reject: (error: unknown) => void;
    /** Streams a value into this call (DriverContext.emit); ignored once settled or aborted. */
    readonly emit: (output: O) => void;
    readonly settled: boolean;
}

interface FakeDriver<I, O, E> extends Driver<I, O, E> {
    readonly calls: ReadonlyArray<FakeCall<I, O>>;
    /** Inputs of every call so far. */
    readonly inputs: readonly I[];
    /** Settles the oldest unsettled, non-aborted call. Throws if there is none. */
    resolveNext(output: O): void;
    rejectNext(error: unknown): void;
    /** Streams a value into the newest call that is still running. Throws if there is none. */
    emitNext(output: O): void;
}

interface FakeOptions<I, O, E> {
    /** Answer calls immediately. Without it, calls wait for `resolveNext`/`rejectNext`. */
    readonly impl?: FakeRun<I, O>;
    readonly concurrency?: Concurrency;
    readonly toError?: (cause: unknown) => E;
}

type FakeRun<I, O> = (input: I, ctx: DriverContext<O>) => O | Promise<O>;

interface FocusTarget extends FocusOptions {
    readonly selector: string;
}

interface HydratedOptions {
    /**
     * Custom element tags allowed to stay undefined (never upgraded). `gyral-stores` is always
     * allowed: in the browser it is a plain scoping element.
     */
    readonly allowUndefined?: readonly string[];
    /**
     * Release every lazy island first (`defer-hydration` + `data-gyral-hydrate`), as if each
     * one's trigger had fired. Default `false`: islands keep waiting.
     */
    readonly releaseIslands?: boolean;
}

interface Mounted<E extends HTMLElement> {
    readonly el: E;
    /** The first match in the element's shadow root (or light DOM), or null. */
    $(selector: string): HTMLElement | null;
    /** Every match in the element's shadow root (or light DOM). */
    $$(selector: string): HTMLElement[];
    /** Sets a control's value as typing would, fires `input` and `change`, then waits. */
    type(selector: string, text: string): Promise<void>;
    /** Clicks the first match, then waits. */
    click(selector: string): Promise<void>;
    /** Waits until rendering, commands and messages have settled (`settled()`). */
    settled(): Promise<void>;
    /** Removes the element (and its overrides with it). */
    dispose(): void;
}

interface MountedSsr {
    /** The element holding the server body (Declarative Shadow DOM already parsed). */
    readonly root: HTMLElement;
    /** Console errors/warnings and uncaught errors seen since mounting (see `hydrated`). */
    readonly problems: readonly string[];
    readonly unmount: () => void;
}

interface MountOptions<E extends HTMLElement> {
    /** Props, set as properties before the element connects. */
    readonly props?: PropsOf<E> & Readonly<Record<string, unknown>>;
    /** Attributes, set before the element connects. */
    readonly attrs?: Readonly<Record<string, string>>;
    /** Driver substitutions by name (`el.drivers`), set before the element connects. */
    readonly drivers?: DriverOverrides;
    /** Store instances by name (`el.stores`), set before the element connects. */
    readonly stores?: StoreOverrides;
    /** Query the element's light DOM instead of its shadow root (for `shadow: false`). */
    readonly light?: boolean;
    /** Where to append the element. Default `document.body`. */
    readonly parent?: ParentNode;
}

interface MountSsrOptions {
    /** Restore the page-level store seed (`data-gyral-stores`). Default `true`. */
    readonly stores?: boolean;
    /** Copy `<meta name=…>` elements from the head (e.g. a CSRF token). Default `true`. */
    readonly metas?: boolean;
    /**
     * Copy the managed head (ADR 0019: elements marked `data-gyral-head`) right after the
     * document's `<title>`, as the server wrote it, so a test can check that the client's first
     * `setHead()` adopts it without writing. Default `true`.
     */
    readonly head?: boolean;
}

interface ParseOptions<S, P> {
    /** Props as the component sees them. Default `{}`. */
    readonly props?: P;
    /** The state when the event fires. Default: the component's initial state for `props`. */
    readonly state?: S;
    /** Store instances `ctx.read` resolves (ADR 0013). */
    readonly stores?: readonly AnyStoreInstance[];
}

interface Ran<S, M> extends Stepped<S, M> {
    /** State after each message, in order. */
    readonly states: readonly S[];
}

interface RunOptions<S, P> {
    readonly props?: P;
    /** Store instances `ctx.read()` sees. */
    readonly stores?: readonly AnyStoreInstance[];
    /** Start from this state instead of `init(props)` (whose commands are then skipped). */
    readonly state?: S;
}

type StepMessage<M, P> = M | PropsChanged<P> | IntentRejected | StoreChanged | Hydrated | Errored;

interface Stepped<S, M> {
    readonly state: S;
    readonly commands: ReadonlyArray<Command<M>>;
}

interface ViewOptions<P> {
    readonly props?: P;
    readonly stores?: readonly AnyStoreInstance[];
}

interface VirtualTime {
    /** Advances the clock, running due timers and the promise work between them. */
    advance(ms: number): Promise<void>;
    /** Runs every pending timer (and timers they schedule) until none remain. */
    runAll(): Promise<void>;
    /** Current virtual time in ms (`Date.now()` while installed). */
    now(): number;
    restore(): void;
}

interface WithOutputs {
    /** Type-only, as on `GyralElementClass`. */
    readonly outputs?: Tagged;
}

const renderOnServer: BrowserCommand<[ServerRenderRequest], string>

import { commands } from 'vitest/browser';
const page = mountSsr(await commands.renderOnServer({ module: '../src/counter.ts',
  export: 'Counter', props: { start: 3 } }));
await import('../src/counter.ts'); // hydrates in place
await hydrated(page);

interface ServerRenderRequest {
    /**
     * The module to load on the server: relative to the test file (`'../src/counter.ts'`), an
     * absolute path, a path from the project root (`'/src/app.ts'`) or a package specifier.
     */
    readonly module: string;
    /**
     * The export to render (default `'default'`):
     * - a `define()` class: renders its element, with `props` set as properties;
     * - a function: called with `props`; it may return (or resolve to) a template result, an
     *   HTML string or a `Response` (a full page from `@gyral/ssr`'s `renderPage`, an app's
     *   `fetch` handler…);
     * - a template result: rendered as is.
     */
    readonly export?: string;
    /** Props for a component class, or the argument of a function export. */
    readonly props?: Readonly<Record<string, unknown>>;
    /**
     * Development markers and checks (`render`'s `dev` option). Default: the build of core the
     * server loads (development in Vitest).
     */
    readonly dev?: boolean;
}