@kiwa-test/nextjs 1.0.5 → 1.2.0

package/dist/index.d.ts

@@ -225,4 +225,255 @@ interface InvokeParallelRoutesResult<TSlots extends string, TNode = unknown> {
  */
 declare function invokeParallelRoutes<TSlots extends string, TLayoutProps = Record<string, unknown>, TNode = unknown>(opts: InvokeParallelRoutesOptions<TSlots, TLayoutProps, TNode>): Promise<InvokeParallelRoutesResult<TSlots, TNode>>;
 
-export { type CookieJar, type DefaultFallbackComponent, FORBIDDEN_SYMBOL, type ForbiddenSignal, type InterceptionMatch, type InvokeMiddlewareOptions, type InvokeMiddlewareResult, type InvokeParallelRoutesOptions, type InvokeParallelRoutesResult, MIDDLEWARE_ACTION_SYMBOL, type MiddlewareAction, type MiddlewareActionKind, type MiddlewareEnv, type MiddlewareFunction, type MiddlewareRequest, NOT_FOUND_SYMBOL, type NotFoundSignal, PARALLEL_INTERCEPTION_SYMBOL, type ParallelLayoutChildren, type ParallelLayoutFunction, REDIRECT_SYMBOL, RSC_REDIRECT_SYMBOL, type RedirectSignal, type RenderServerComponentOptions, type RenderServerComponentResult, type RscElement, type RscNode, type RscRedirectSignal, type RscSignal, type ServerActionEnv, type ServerActionFunction, type ServerActionInvocation, type ServerActionResult, type SlotComponent, type SlotInput, type SlotRenderResult, findAll, invokeMiddleware, invokeParallelRoutes, invokeServerAction, middlewareActions, renderServerComponent, textContent };
+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 };