@kiwa-test/nextjs 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -0,0 +1,479 @@
+declare const REDIRECT_SYMBOL: unique symbol;
+interface RedirectSignal {
+    readonly [REDIRECT_SYMBOL]: true;
+    readonly url: string;
+    readonly type: 'replace' | 'push';
+}
+interface CookieJar {
+    get(name: string): string | undefined;
+    set(name: string, value: string, options?: Record<string, unknown>): void;
+    delete(name: string): void;
+    entries(): Array<[string, string]>;
+}
+interface ServerActionEnv {
+    readonly cookies: CookieJar;
+    readonly headers: Map<string, string>;
+    readonly revalidated: {
+        paths: string[];
+        tags: string[];
+    };
+    readonly redirect: RedirectSignal | null;
+}
+type ServerActionFunction<TResult> = (...args: any[]) => Promise<TResult> | TResult;
+interface ServerActionInvocation<TResult> {
+    /** The `'use server'` async function under test. */
+    readonly action: ServerActionFunction<TResult>;
+    /** Optional FormData first argument (default empty). */
+    readonly formData?: FormData;
+    /** Extra positional args appended after FormData (e.g. previous state for useFormState). */
+    readonly args?: unknown[];
+    /** Initial cookie jar entries (name → value). */
+    readonly cookies?: Record<string, string>;
+    /** Initial request headers (case-insensitive). */
+    readonly headers?: Record<string, string>;
+}
+interface ServerActionResult<TResult> {
+    /** Resolved return value (or `undefined` if the action threw a redirect signal). */
+    readonly result: TResult | undefined;
+    /** Error thrown by the action (excluding redirect signals which are normalized). */
+    readonly error: unknown;
+    /** Side-effects captured during the invocation. */
+    readonly env: ServerActionEnv;
+}
+/**
+ * Invoke a Next.js Server Action in isolation and capture its side-effects.
+ *
+ * The action is called as `await action(formData, ...args)`. The kiwa helper
+ * does NOT monkey-patch global `next/navigation` / `next/headers` / `next/cache`
+ * imports. Instead the action under test should accept its dependencies via
+ * an injectable seam (a parameter or a module-level setter) so tests stay
+ * deterministic. See `examples/nextjs-server-actions-poc/` for the pattern.
+ */
+declare function invokeServerAction<TResult>(opts: ServerActionInvocation<TResult>): Promise<ServerActionResult<TResult>>;
+
+declare const MIDDLEWARE_ACTION_SYMBOL: unique symbol;
+type MiddlewareActionKind = 'next' | 'redirect' | 'rewrite' | 'json' | 'noop';
+interface MiddlewareAction {
+    readonly [MIDDLEWARE_ACTION_SYMBOL]: true;
+    readonly kind: MiddlewareActionKind;
+    readonly url?: string;
+    readonly body?: unknown;
+    readonly status?: number;
+}
+interface MiddlewareRequest {
+    readonly url: string;
+    readonly method: string;
+    readonly headers: ReadonlyMap<string, string>;
+    readonly cookies: ReadonlyMap<string, string>;
+    readonly nextUrl: {
+        readonly pathname: string;
+        readonly search: string;
+        readonly searchParams: URLSearchParams;
+    };
+    readonly geo: {
+        readonly country?: string;
+        readonly region?: string;
+        readonly city?: string;
+    };
+}
+interface MiddlewareEnv {
+    readonly responseHeaders: Map<string, string>;
+    readonly responseCookies: Map<string, string>;
+    readonly action: MiddlewareAction;
+}
+type MiddlewareFunction = (req: MiddlewareRequest, env: {
+    setHeader: (name: string, value: string) => void;
+    setCookie: (name: string, value: string) => void;
+}) => MiddlewareAction | Promise<MiddlewareAction>;
+interface InvokeMiddlewareOptions {
+    readonly middleware: MiddlewareFunction;
+    readonly url: string;
+    readonly method?: string;
+    readonly headers?: Record<string, string>;
+    readonly cookies?: Record<string, string>;
+    readonly geo?: {
+        readonly country?: string;
+        readonly region?: string;
+        readonly city?: string;
+    };
+}
+interface InvokeMiddlewareResult {
+    readonly env: MiddlewareEnv;
+    readonly error: unknown;
+}
+/**
+ * Helpers your `middleware.ts` returns instead of constructing NextResponse
+ * directly. Keep the production code shape close by re-exporting these from
+ * a shared module; the helper expects the returned value to be a
+ * MiddlewareAction shaped object.
+ */
+declare const middlewareActions: {
+    next(): MiddlewareAction;
+    redirect(url: string, status?: number): MiddlewareAction;
+    rewrite(url: string): MiddlewareAction;
+    json(body: unknown, status?: number): MiddlewareAction;
+};
+/**
+ * Invoke a middleware function in isolation and capture its outgoing
+ * response shape + headers + cookies. Mirrors the kiwa style of
+ * invokeServerAction: no globals, no real Next.js runtime.
+ */
+declare function invokeMiddleware(opts: InvokeMiddlewareOptions): Promise<InvokeMiddlewareResult>;
+
+declare const NOT_FOUND_SYMBOL: unique symbol;
+declare const FORBIDDEN_SYMBOL: unique symbol;
+declare const RSC_REDIRECT_SYMBOL: unique symbol;
+interface NotFoundSignal {
+    readonly [NOT_FOUND_SYMBOL]: true;
+}
+interface ForbiddenSignal {
+    readonly [FORBIDDEN_SYMBOL]: true;
+}
+interface RscRedirectSignal {
+    readonly [RSC_REDIRECT_SYMBOL]: true;
+    readonly url: string;
+    readonly type: 'replace' | 'push';
+}
+type RscSignal = NotFoundSignal | ForbiddenSignal | RscRedirectSignal;
+interface RscElement {
+    readonly type: string | symbol | ((props: Record<string, unknown>) => unknown);
+    readonly props: Record<string, unknown>;
+    readonly key: string | null;
+}
+type RscNode = RscElement | string | number | boolean | null | undefined | RscNode[];
+interface RenderServerComponentOptions<TProps> {
+    readonly component: (props: TProps) => Promise<RscNode> | RscNode;
+    readonly props?: TProps;
+}
+interface RenderServerComponentResult {
+    readonly tree: RscNode;
+    readonly signal: RscSignal | null;
+    readonly error: unknown;
+}
+/**
+ * Recursively walk an RSC tree and collect every node that satisfies the
+ * predicate. Children are read from `props.children` and are normalized to a
+ * flat array regardless of how the component spelled them.
+ */
+declare function findAll(tree: RscNode, predicate: (node: RscElement) => boolean): RscElement[];
+/**
+ * Concatenate every string/number leaf of an RSC tree, joined by a single
+ * space. Useful for `expect(textContent(tree)).toContain('hello')` style
+ * assertions where the exact element structure does not matter.
+ */
+declare function textContent(tree: RscNode): string;
+/**
+ * Invoke an async server component in isolation and capture its return tree.
+ * Throws of `notFound() / forbidden() / redirect()` from `next/navigation`
+ * should be replaced with the kiwa signals below (Pattern A from the
+ * server-action seam doc); the helper normalizes them into `result.signal`
+ * instead of leaving them as `result.error`.
+ */
+declare function renderServerComponent<TProps = Record<string, unknown>>(opts: RenderServerComponentOptions<TProps>): Promise<RenderServerComponentResult>;
+
+declare const PARALLEL_INTERCEPTION_SYMBOL: unique symbol;
+interface InterceptionMatch<TSlot extends string> {
+    readonly [PARALLEL_INTERCEPTION_SYMBOL]: true;
+    readonly slot: TSlot;
+    readonly variant: 'intercepted' | 'default';
+    readonly url: string;
+    readonly distance: 'sibling' | 'parent' | 'root';
+}
+type SlotComponent<TProps = Record<string, unknown>, TNode = unknown> = (props: TProps) => Promise<TNode> | TNode;
+type DefaultFallbackComponent<TNode = unknown> = () => Promise<TNode> | TNode;
+interface ParallelLayoutChildren<TSlots extends string, TNode = unknown> {
+    readonly children: TNode;
+    readonly slots: Readonly<Record<TSlots, TNode>>;
+}
+type ParallelLayoutFunction<TSlots extends string, TLayoutProps, TNode = unknown> = (props: TLayoutProps & ParallelLayoutChildren<TSlots, TNode>) => Promise<TNode> | TNode;
+interface SlotInput<TSlots extends string, TNode = unknown> {
+    readonly slot: TSlots;
+    readonly component: SlotComponent<Record<string, unknown>, TNode> | null;
+    readonly props?: Record<string, unknown>;
+    readonly defaultFallback?: DefaultFallbackComponent<TNode>;
+    readonly intercepting?: {
+        readonly variant: 'intercepted' | 'default';
+        readonly url: string;
+        readonly distance?: 'sibling' | 'parent' | 'root';
+    };
+}
+interface InvokeParallelRoutesOptions<TSlots extends string, TLayoutProps, TNode = unknown> {
+    readonly layout: ParallelLayoutFunction<TSlots, TLayoutProps, TNode>;
+    readonly children: SlotComponent<Record<string, unknown>, TNode>;
+    readonly childrenProps?: Record<string, unknown>;
+    readonly slots: ReadonlyArray<SlotInput<TSlots, TNode>>;
+    readonly layoutProps?: TLayoutProps;
+}
+interface SlotRenderResult<TSlots extends string, TNode = unknown> {
+    readonly slot: TSlots;
+    readonly tree: TNode | null;
+    readonly usedDefault: boolean;
+    readonly interception: InterceptionMatch<TSlots> | null;
+    readonly error: unknown;
+}
+interface InvokeParallelRoutesResult<TSlots extends string, TNode = unknown> {
+    readonly tree: TNode | null;
+    readonly slotResults: ReadonlyArray<SlotRenderResult<TSlots, TNode>>;
+    readonly childrenError: unknown;
+    readonly layoutError: unknown;
+}
+/**
+ * Invoke an App Router parallel-routes layout in isolation. All slot
+ * components are rendered in parallel (Promise.all) so a slow slot cannot
+ * block fast siblings; per-slot errors are captured into `slotResults`
+ * without aborting the layout render.
+ */
+declare function invokeParallelRoutes<TSlots extends string, TLayoutProps = Record<string, unknown>, TNode = unknown>(opts: InvokeParallelRoutesOptions<TSlots, TLayoutProps, TNode>): Promise<InvokeParallelRoutesResult<TSlots, TNode>>;
+
+declare const RSC_ERROR_BOUNDARY_SYMBOL: unique symbol;
+interface RscErrorBoundarySignal {
+    readonly [RSC_ERROR_BOUNDARY_SYMBOL]: true;
+    readonly error: unknown;
+}
+/**
+ * An async source the helper consumes chunk-by-chunk. Each yielded value is
+ * one streaming frame; the helper appends it to `env.chunks` in arrival order
+ * and uses the last chunk as `env.resolved` once the source completes.
+ *
+ * Use a plain async generator for most cases:
+ *
+ *   async function* source() {
+ *     yield <Spinner />;            // initial chunk
+ *     yield <Skeleton rows={3} />;  // partial data
+ *     yield <Items list={data} />;  // final resolved chunk
+ *   }
+ */
+type RscStreamSource = AsyncIterable<RscNode>;
+interface SetupNextRscEnvOptions {
+    /**
+     * The async server component under test. If `dataSource` is omitted, the
+     * helper awaits this function once and treats its return value as the only
+     * (resolved) chunk — equivalent to a synchronous resolution.
+     *
+     * The component may throw to trigger the error boundary path. See
+     * `injectError` for the test-side variant.
+     */
+    readonly component?: (props: Record<string, unknown>) => Promise<RscNode> | RscNode;
+    /**
+     * Optional props forwarded to `component`. Defaults to `{}`.
+     */
+    readonly props?: Record<string, unknown>;
+    /**
+     * Explicit streaming source. When provided, the helper iterates this and
+     * ignores `component`. Useful when the production code already produces a
+     * stream and the test wants to feed a deterministic sequence.
+     */
+    readonly dataSource?: RscStreamSource;
+    /**
+     * Markup shown while the (first) chunk is pending. Captured as
+     * `env.fallback` so tests can assert that `<Suspense fallback={...}>`
+     * surfaces the right loading state before the data arrives.
+     */
+    readonly suspenseFallback?: RscNode;
+    /**
+     * Hard timeout (ms) for the whole stream. If the source has not completed
+     * by this deadline, the helper resolves with `env.timedOut = true` and the
+     * chunks collected so far. Default 5000ms.
+     */
+    readonly streamingTimeout?: number;
+    /**
+     * Test-side error injection. When set, the helper short-circuits before
+     * iterating the source and routes the error into `env.errorBoundary` —
+     * the same shape a production `error.tsx` boundary would see.
+     */
+    readonly injectError?: unknown;
+}
+interface SetupNextRscEnvResult {
+    /**
+     * Streaming chunks in arrival order. For a Suspense boundary, the first
+     * chunk is typically the fallback markup and the last chunk is the
+     * resolved subtree.
+     */
+    readonly chunks: RscNode[];
+    /**
+     * The fallback markup captured before the source produced its first
+     * non-fallback chunk. `null` when the test did not pass `suspenseFallback`
+     * or when the source resolved synchronously without an explicit fallback.
+     */
+    readonly fallback: RscNode | null;
+    /**
+     * The last chunk yielded by the source — the markup a real Next.js page
+     * would settle on after streaming finishes. `null` when the source threw
+     * or timed out before producing any chunk.
+     */
+    readonly resolved: RscNode | null;
+    /**
+     * Set when the component or source threw, or when `injectError` was
+     * provided. Mirrors the value a production `error.tsx` boundary receives.
+     * `null` for happy-path streams.
+     */
+    readonly errorBoundary: RscErrorBoundarySignal | null;
+    /**
+     * `true` when `streamingTimeout` elapsed before the source completed.
+     * `chunks` still contains any chunks that arrived before the deadline.
+     */
+    readonly timedOut: boolean;
+}
+/**
+ * Drive an async RSC stream through a single Suspense boundary and capture
+ * every chunk + the fallback + the resolved subtree + any error-boundary
+ * trigger. The helper is deterministic — chunks arrive in the order the
+ * source yields them, and the timeout is wall-clock-bounded so tests cannot
+ * hang on a stuck stream.
+ *
+ * Typical usage:
+ *
+ *   const env = await setupNextRscEnv({
+ *     dataSource: streamItems(),
+ *     suspenseFallback: <Skeleton />,
+ *     streamingTimeout: 1000,
+ *   });
+ *   expect(env.fallback).toEqual(<Skeleton />);
+ *   expect(env.chunks).toHaveLength(3);
+ *   expect(env.resolved).toEqual(<ItemList items={items} />);
+ *   expect(env.errorBoundary).toBeNull();
+ *   expect(env.timedOut).toBe(false);
+ */
+declare function setupNextRscEnv(opts?: SetupNextRscEnvOptions): Promise<SetupNextRscEnvResult>;
+
+/**
+ * Advanced Next.js semantics — target-neutral axis SSOT.
+ *
+ * The helpers model App Router, Pages Router, and Edge Runtime behavior as
+ * pure state machines. Tests can assert the neutral event while still seeing
+ * a target-specific dialect through providerEventName.
+ */
+type NextTarget = 'app-router' | 'pages-router' | 'edge-runtime';
+type NextAxis = 'server-action-advanced' | 'partial-prerendering' | 'interception-routes' | 'parallel-routes-advanced';
+type NeutralEventName = 'action.form_submitted' | 'action.revalidate_path' | 'action.revalidate_tag' | 'action.redirected' | 'ppr.static_shell_rendered' | 'ppr.dynamic_hole_opened' | 'ppr.streaming_boundary_flushed' | 'ppr.completed' | 'intercept.current_segment' | 'intercept.parent_segment' | 'intercept.root_catchall' | 'intercept.modal_opened' | 'parallel.default_rendered' | 'parallel.loading_rendered' | 'parallel.error_boundary_captured' | 'parallel.slot_navigated';
+interface AxisStep<TState extends string> {
+    neutralEvent: NeutralEventName;
+    providerEvent: string;
+    state: TState;
+    amountCents: number;
+    metadata: Record<string, string | number | boolean>;
+}
+declare function providerEventName(target: NextTarget, neutral: NeutralEventName): string;
+
+type ServerActionAdvancedState = 'idle' | 'submitted' | 'path-revalidated' | 'tag-revalidated' | 'redirected';
+interface ServerActionAdvancedSession {
+    target: NextTarget;
+    actionId: string;
+    state: ServerActionAdvancedState;
+    form: Record<string, string>;
+    revalidatedPaths: string[];
+    revalidatedTags: string[];
+    redirectUrl: string | null;
+    history: AxisStep<ServerActionAdvancedState>[];
+}
+declare function startServerActionAdvanced(input: {
+    target: NextTarget;
+    actionId: string;
+}): ServerActionAdvancedSession;
+declare function submitFormAction(session: ServerActionAdvancedSession, form: Record<string, string>): AxisStep<ServerActionAdvancedState>;
+declare function revalidateActionPath(session: ServerActionAdvancedSession, path: string): AxisStep<ServerActionAdvancedState>;
+declare function revalidateActionTag(session: ServerActionAdvancedSession, tag: string): AxisStep<ServerActionAdvancedState>;
+declare function redirectAction(session: ServerActionAdvancedSession, url: string): AxisStep<ServerActionAdvancedState>;
+
+type PartialPrerenderingState = 'idle' | 'static-shell' | 'dynamic-hole' | 'streaming' | 'completed';
+interface PartialPrerenderingSession {
+    target: NextTarget;
+    routeId: string;
+    state: PartialPrerenderingState;
+    shellHtml: string | null;
+    dynamicHoles: Map<string, string>;
+    streamedBoundaries: string[];
+    history: AxisStep<PartialPrerenderingState>[];
+}
+declare function startPartialPrerendering(input: {
+    target: NextTarget;
+    routeId: string;
+}): PartialPrerenderingSession;
+declare function renderStaticShell(session: PartialPrerenderingSession, html: string): AxisStep<PartialPrerenderingState>;
+declare function openDynamicHole(session: PartialPrerenderingSession, input: {
+    holeId: string;
+    fallback: string;
+}): AxisStep<PartialPrerenderingState>;
+declare function flushStreamingBoundary(session: PartialPrerenderingSession, input: {
+    holeId: string;
+    html: string;
+}): AxisStep<PartialPrerenderingState>;
+declare function completePartialPrerendering(session: PartialPrerenderingSession): AxisStep<PartialPrerenderingState>;
+
+type InterceptionRoutesState = 'idle' | 'current' | 'parent' | 'root' | 'modal-open';
+type InterceptionMatcher = '(.)' | '(..)' | '(...)';
+interface InterceptionRoutesSession {
+    target: NextTarget;
+    routeId: string;
+    state: InterceptionRoutesState;
+    matches: Array<{
+        matcher: InterceptionMatcher;
+        from: string;
+        to: string;
+    }>;
+    modalRoute: string | null;
+    history: AxisStep<InterceptionRoutesState>[];
+}
+declare function startInterceptionRoutes(input: {
+    target: NextTarget;
+    routeId: string;
+}): InterceptionRoutesSession;
+declare function interceptCurrentSegment(session: InterceptionRoutesSession, from: string, to: string): AxisStep<InterceptionRoutesState>;
+declare function interceptParentSegment(session: InterceptionRoutesSession, from: string, to: string): AxisStep<InterceptionRoutesState>;
+declare function interceptRootCatchall(session: InterceptionRoutesSession, from: string, to: string): AxisStep<InterceptionRoutesState>;
+declare function openInterceptedModal(session: InterceptionRoutesSession, modalRoute: string): AxisStep<InterceptionRoutesState>;
+
+type ParallelRoutesAdvancedState = 'idle' | 'default-rendered' | 'loading-rendered' | 'error-captured' | 'slot-navigated';
+interface ParallelRoutesAdvancedSession {
+    target: NextTarget;
+    layoutId: string;
+    state: ParallelRoutesAdvancedState;
+    slots: Map<string, string>;
+    loadingSlots: Set<string>;
+    errors: Array<{
+        slot: string;
+        message: string;
+    }>;
+    history: AxisStep<ParallelRoutesAdvancedState>[];
+}
+declare function startParallelRoutesAdvanced(input: {
+    target: NextTarget;
+    layoutId: string;
+}): ParallelRoutesAdvancedSession;
+declare function renderDefaultSlot(session: ParallelRoutesAdvancedSession, slot: string, html: string): AxisStep<ParallelRoutesAdvancedState>;
+declare function renderLoadingState(session: ParallelRoutesAdvancedSession, slot: string): AxisStep<ParallelRoutesAdvancedState>;
+declare function captureParallelError(session: ParallelRoutesAdvancedSession, input: {
+    slot: string;
+    error: Error | string;
+}): AxisStep<ParallelRoutesAdvancedState>;
+declare function navigateSlot(session: ParallelRoutesAdvancedSession, input: {
+    slot: string;
+    from: string;
+    to: string;
+}): AxisStep<ParallelRoutesAdvancedState>;
+
+interface FidelityRow {
+    provider: NextTarget;
+    axis: NextAxis;
+    neutralEvents: NeutralEventName[];
+    providerEvents: string[];
+}
+interface FidelityCoverage {
+    providers: NextTarget[];
+    axes: NextAxis[];
+    rows: FidelityRow[];
+}
+declare const NEXT_AXIS_TO_EVENTS: Record<NextAxis, NeutralEventName[]>;
+declare function collectFidelityCoverage(providers?: NextTarget[]): FidelityCoverage;
+
+type KiwaTestMode = 'mock' | 'real';
+interface ResolvedMode {
+    mode: KiwaTestMode;
+    provider: NextTarget;
+    reason: 'default-mock' | 'kiwa-mode-real' | 'missing-key' | 'invalid-mode';
+}
+declare function resolveMode(provider: NextTarget, env?: Record<string, string | undefined>): ResolvedMode;
+declare function resolveAllModes(env?: Record<string, string | undefined>): ResolvedMode[];
+declare function assertMode(provider: NextTarget, expected: KiwaTestMode, env?: Record<string, string | undefined>): void;
+
+export { type AxisStep, type CookieJar, type DefaultFallbackComponent, FORBIDDEN_SYMBOL, type FidelityCoverage, type FidelityRow, type ForbiddenSignal, type InterceptionMatch, type InterceptionMatcher, type InterceptionRoutesSession, type InterceptionRoutesState, type InvokeMiddlewareOptions, type InvokeMiddlewareResult, type InvokeParallelRoutesOptions, type InvokeParallelRoutesResult, type KiwaTestMode, MIDDLEWARE_ACTION_SYMBOL, type MiddlewareAction, type MiddlewareActionKind, type MiddlewareEnv, type MiddlewareFunction, type MiddlewareRequest, NEXT_AXIS_TO_EVENTS, NOT_FOUND_SYMBOL, type NeutralEventName, type NextAxis, type NextTarget, type NotFoundSignal, PARALLEL_INTERCEPTION_SYMBOL, type ParallelLayoutChildren, type ParallelLayoutFunction, type ParallelRoutesAdvancedSession, type ParallelRoutesAdvancedState, type PartialPrerenderingSession, type PartialPrerenderingState, REDIRECT_SYMBOL, RSC_ERROR_BOUNDARY_SYMBOL, RSC_REDIRECT_SYMBOL, type RedirectSignal, type RenderServerComponentOptions, type RenderServerComponentResult, type ResolvedMode, type RscElement, type RscErrorBoundarySignal, type RscNode, type RscRedirectSignal, type RscSignal, type RscStreamSource, type ServerActionAdvancedSession, type ServerActionAdvancedState, type ServerActionEnv, type ServerActionFunction, type ServerActionInvocation, type ServerActionResult, type SetupNextRscEnvOptions, type SetupNextRscEnvResult, type SlotComponent, type SlotInput, type SlotRenderResult, assertMode, captureParallelError, collectFidelityCoverage, completePartialPrerendering, findAll, flushStreamingBoundary, interceptCurrentSegment, interceptParentSegment, interceptRootCatchall, invokeMiddleware, invokeParallelRoutes, invokeServerAction, middlewareActions, navigateSlot, openDynamicHole, openInterceptedModal, providerEventName, redirectAction, renderDefaultSlot, renderLoadingState, renderServerComponent, renderStaticShell, resolveAllModes, resolveMode, revalidateActionPath, revalidateActionTag, setupNextRscEnv, startInterceptionRoutes, startParallelRoutesAdvanced, startPartialPrerendering, startServerActionAdvanced, submitFormAction, textContent };