@tinvar/react 0.0.0-stage → 0.4.0

package/src/testing.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The JavaScript half of the testing layer: what codegen's mocks of
+ * `@queries/*` and `@actions/*` are built on, and the harness server
+ * components render in. Loads only in a Vitest worker; see ADR 0061.
+ */
+
+import type { ReactNode } from 'react';
+import type { ActionReference, ActionResponse } from './action';
+import type { SharedDataMap } from './server';
+
+/** The marker a Vite build refuses any module of. */
+export declare const TESTING_RUNTIME: 'tinvar:testing-runtime';
+
+/** Throws unless the environment given is a Vitest worker's, and not production. */
+export declare function refuseOutsideTests(env: Record<string, string | undefined> | undefined): void;
+
+/** A stand-in for one `@queries/*` function. */
+export interface MockedQuery<Args extends object, Result> {
+  (args: Args): Promise<Result>;
+  /** The query's wire name. */
+  readonly query: string;
+}
+
+/** A stand-in for one `@actions/*` reference: a reference, recording its calls. */
+export type MockedAction<Args extends object, Result> = ActionReference<Args, Result>;
+
+export declare function mockQuery<Args extends object, Result>(
+  name: string,
+  fallback: () => Result,
+): MockedQuery<Args, Result>;
+
+export declare function mockAction<Args extends object, Result = ActionResponse>(
+  name: string,
+  fallback: () => Result,
+): MockedAction<Args, Result>;
+
+type ArgsOf<M> = M extends (args: infer A, ...rest: never[]) => unknown ? A : never;
+type ResultOf<M> = M extends (...args: never[]) => Promise<infer R> ? R : never;
+
+/** The arguments each call to a mock was made with, oldest first. */
+export declare function calls<M extends (...args: never[]) => Promise<unknown>>(mock: M): ArgsOf<M>[];
+
+/** What a mock answers from now on: a value, or a function of the call's arguments. */
+export declare function answer<M extends (...args: never[]) => Promise<unknown>>(
+  mock: M,
+  value: ResultOf<M> | Promise<ResultOf<M>> | ((args: ArgsOf<M>) => ResultOf<M> | Promise<ResultOf<M>>),
+): void;
+
+/** Has a mock refuse from now on: an action with an ActionError (422 with field errors by default). */
+export declare function refuse(
+  mock: (...args: never[]) => Promise<unknown>,
+  refusal?: { status?: number; errors?: Record<string, string[]> },
+): void;
+
+/**
+ * What a fake takes: any field, at any depth. A plain object is laid over
+ * the field's defaults; a list, null or anything else replaces it.
+ */
+export type Overrides<T> = T extends readonly unknown[]
+  ? T
+  : T extends (...args: never[]) => unknown
+    ? T
+    : T extends object
+      ? { [K in keyof T]?: Overrides<T[K]> }
+      : T;
+
+/** A fake's defaults under a test's overrides, at any depth; what codegen's fakes return. */
+export declare function withOverrides<T>(base: T, overrides: Overrides<T>): T;
+
+/** Forgets every call and answer. */
+export declare function resetMocks(): void;
+
+/** A fetch that answers posts to `/_action/{name}` and `/_query/{name}` from the mocks, and nothing else. */
+export declare function actionFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+
+/** Marks a 'use client' module's exports; `tinvarTesting()` adds the call. */
+export declare function markClient(...exports: unknown[]): void;
+
+export declare function isClientComponent(type: unknown): boolean;
+
+/**
+ * Renders a tree's server components against the mocks, and hands back what
+ * is left -- host elements and client components -- for React Testing
+ * Library's render().
+ */
+export declare function renderServer(
+  node: ReactNode,
+  options?: { shared?: { [K in keyof SharedDataMap]?: SharedDataMap[K] } },
+): Promise<ReactNode>;