@tanstack-router-testing/react-start-testing 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present eve0415
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# tanstack-router-testing
+
+Unit testing utilities for [TanStack Router](https://tanstack.com/router) and [TanStack Start](https://tanstack.com/start).
+
+## Quick start
+
+```bash
+pnpm add -D @tanstack-router-testing/react-router-testing @tanstack-router-testing/react-start-testing
+```
+
+Configure Vitest with the Start shim:
+
+```ts
+// vitest.config.ts
+import { tanstackStartTesting } from '@tanstack-router-testing/react-start-testing/vite';
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  plugins: [tanstackStartTesting()],
+  test: { environment: 'jsdom' },
+});
+```
+
+Write your first test — import a single route file, pass it to the harness, and assert:
+
+```tsx
+// posts.$postId.test.tsx
+import { render } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { createRouterHarness } from '@tanstack-router-testing/react-router-testing';
+import { Route } from './routes/posts.$postId';
+
+describe('post route', () => {
+  it('loads and renders a post', async () => {
+    const harness = createRouterHarness({
+      route: Route,
+      params: { postId: '42' }, // fully typed from route path
+      loaderData: { id: '42', title: 'Hello' }, // skip the real loader
+    });
+    await harness.load();
+    const { findByText } = render(<harness.TestRouterProvider />);
+    await expect(findByText('Hello')).resolves.toBeTruthy();
+    harness.cleanup();
+  });
+});
+```
+
+Or use a full route tree for integration-level tests:
+
+```tsx
+import { createRouterHarness } from '@tanstack-router-testing/react-router-testing';
+import { routeTree } from './routeTree.gen';
+
+const harness = createRouterHarness({ routeTree, initialEntries: ['/posts/7'] });
+await harness.load();
+expect(harness.getLoaderData('/posts/$postId')).toBeDefined();
+harness.cleanup();
+```
+
+## Packages
+
+| Package                                                                     | Purpose                                                                              |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| [`react-router-testing`](./packages/react-router-testing)                   | `createRouterHarness` (file route or full tree), `createTestRouter`, SSR harness     |
+| [`react-start-testing`](./packages/react-start-testing)                     | `mockServerFn`, `mockMiddleware`, `createStartTestRuntime`, RSC runtime, Vite plugin |
+| [`router-testing-core`](./packages/router-testing-core)                     | Internal registry/env runtime (transitive dependency)                                |
+| [`react-start-testing-storybook`](./packages/react-start-testing-storybook) | Storybook decorator for Start stories                                                |
+
+All packages are scoped under `@tanstack-router-testing/`.
+
+## Design principles
+
+1. **Real router, not route stubs.** Tests exercise `createRouter`, route trees, memory history, loaders, guards, params, search, and redirects through the router itself.
+2. **Production-shaped Start calls.** Server functions are called as `await fn({ data })` — the harness supplies mocks and leaves the call shape alone.
+3. **Upstream-mergeable shape.** Public exports are shaped for future first-party subpaths (`@tanstack/react-router/testing`).
+
+## Documentation
+
+- [Getting Started](./docs/getting-started.md)
+- [API Reference](./docs/api-reference.md)
+- **Guides:** [Loaders](./docs/guides/testing-loaders.md) | [Guards & Redirects](./docs/guides/testing-guards.md) | [Server Functions](./docs/guides/testing-server-functions.md) | [Middleware](./docs/guides/testing-middleware.md) | [SSR](./docs/guides/testing-ssr.md) | [RSC](./docs/guides/testing-rsc.md) | [Query Integration](./docs/guides/testing-with-query.md)
+- [Example Tests](./docs/examples/)
+
+## Running tests
+
+```bash
+pnpm run build              # build all packages
+pnpm test:unit:core         # fast core + integration tests
+pnpm test:types             # type-level assertions
+pnpm test:unit:vendored     # 110 vendored TanStack app smoke tests
+pnpm run lint:check         # oxlint + oxfmt
+```
+
+## Contributing
+
+This project aims to become an upstream contribution to `tanstack/router`. Feedback, issues, and PRs welcome.
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,399 @@
+import { AnyFn, CallMiddlewareOptions, CallMiddlewareResult, TestEnv, callMiddleware } from "@tanstack-router-testing/router-testing-core";
+import { ComponentType } from "react";
+import { StartHandlerType } from "@tanstack/start-storage-context";
+import { AnyRouter } from "@tanstack/react-router";
+import { AnyStartInstanceOptions } from "@tanstack/start-client-core";
+
+//#region src/clearStartMocks.d.ts
+/**
+ * Clear every server-function and middleware mock installed by
+ * {@link mockServerFn} or {@link mockMiddleware}.
+ *
+ * @returns `void`.
+ *
+ * @example
+ * ```ts
+ * import { afterEach } from 'vitest';
+ * import { clearStartMocks } from '@tanstack-router-testing/react-start-testing';
+ *
+ * afterEach(() => {
+ *   clearStartMocks();
+ * });
+ * ```
+ *
+ * @remarks
+ * This is the same function wired to {@link StartTestRuntime.cleanup}, so you
+ * only need to call it explicitly when installing mocks outside of a runtime
+ * (i.e. via {@link mockServerFn} / {@link mockMiddleware} directly).
+ */
+declare const clearStartMocks: () => void;
+//#endregion
+//#region src/mockServerFn.d.ts
+/**
+ * Catch-all type representing any TanStack Start server function.
+ *
+ * @remarks
+ * Used as a generic constraint in {@link mockServerFn} and {@link ServerFnMock}
+ * to accept any function created by `createServerFn().handler(...)`.
+ */
+type AnyServerFn = (...args: never[]) => unknown;
+/**
+ * The mock implementation signature for a server function of type `TFn`.
+ *
+ * @typeParam TFn - The server function type being mocked.
+ *
+ * @remarks
+ * The mock receives the same callable-shape arguments as the real server
+ * function (e.g. `{ data }`) and must return a compatible result. Full generic
+ * inference is preserved so autocomplete works identically to the real call.
+ *
+ * @see {@link mockServerFn}
+ */
+type ServerFnMock<TFn extends AnyServerFn> = (...args: Parameters<TFn>) => ReturnType<TFn>;
+/**
+ * Install a mock implementation for a TanStack Start server function.
+ *
+ * @param fn - The server function created by `createServerFn().handler(...)`.
+ * @param impl - A {@link ServerFnMock} that replaces the real handler for the
+ *   duration of the test. It receives the same callable-shape arguments (e.g.
+ *   `{ data }`) as the original function.
+ * @returns A disposer function that restores the original implementation when
+ *   called. Alternatively, call {@link clearStartMocks} to remove all mocks at
+ *   once.
+ *
+ * @example
+ * ```ts
+ * import { createServerFn } from '@tanstack/react-start';
+ * import { mockServerFn } from '@tanstack-router-testing/react-start-testing';
+ *
+ * const listOrders = createServerFn()
+ *   .validator((input: { userId: string }) => input)
+ *   .handler(async ({ data }) => db.orders.findMany(data.userId));
+ *
+ * const dispose = mockServerFn(listOrders, async ({ data }) => [
+ *   { id: '1', userId: data.userId, total: 42 },
+ * ]);
+ *
+ * // ... run your test ...
+ * dispose();
+ * ```
+ *
+ * @remarks
+ * The mock is authored against the public callable shape, so a server function
+ * normally called as `listOrders({ data })` is mocked with that same signature.
+ * Internal context fields are normalised automatically before reaching the mock.
+ */
+declare const mockServerFn: <TFn extends AnyServerFn>(fn: TFn, impl: ServerFnMock<TFn>) => (() => void);
+//#endregion
+//#region src/mockMiddleware.d.ts
+/**
+ * Phase override options for {@link mockMiddleware}.
+ *
+ * @remarks
+ * Provide `client`, `server`, or both. Omitted keys leave the corresponding
+ * phase untouched, so you can mock only the server side without affecting the
+ * client phase and vice-versa.
+ */
+interface MockMiddlewareOptions {
+  /** Override for the `.client()` phase. When omitted the real client handler runs. */
+  readonly client?: AnyFn;
+  /** Override for the `.server()` phase. When omitted the real server handler runs. */
+  readonly server?: AnyFn;
+}
+/**
+ * Override one or both phases of a registered middleware.
+ *
+ * @param mw - The middleware object returned by
+ *   `createMiddleware().server(...).client(...)`.
+ * @param options - A {@link MockMiddlewareOptions} object specifying which
+ *   phases to replace.
+ * @returns A disposer function that restores the original middleware handlers.
+ *   Alternatively, call {@link clearStartMocks} to remove all mocks at once.
+ *
+ * @example
+ * ```ts
+ * import { createMiddleware } from '@tanstack/react-start';
+ * import { mockMiddleware } from '@tanstack-router-testing/react-start-testing';
+ *
+ * const authMiddleware = createMiddleware()
+ *   .server(async ({ next }) => next({ context: { user: await getUser() } }))
+ *   .client(async ({ next }) => next());
+ *
+ * const dispose = mockMiddleware(authMiddleware, {
+ *   server: async ({ next }) => next({ context: { user: { id: 'test-user' } } }),
+ * });
+ *
+ * // ... run your test ...
+ * dispose();
+ * ```
+ *
+ * @throws If `mw` is not registered. Registration is the shim's
+ *   responsibility (see ADR 0001).
+ *
+ * @remarks
+ * Server functions are invoked directly and mocked middleware participates in
+ * that normal call path. Only the phases you specify in `options` are replaced;
+ * the rest continue to run their real implementations.
+ */
+declare const mockMiddleware: (mw: object, options: MockMiddlewareOptions) => (() => void);
+//#endregion
+//#region src/isomorphic.d.ts
+/**
+ * Execute `fn` with the simulated TanStack Start environment forced to `env`,
+ * then restore the prior value.
+ *
+ * @typeParam T - The return type of `fn`.
+ * @param env - The environment to simulate: `'server'` or `'client'`.
+ * @param fn - A synchronous or asynchronous function to run inside the
+ *   simulated environment.
+ * @returns A `Promise` resolving to the return value of `fn`.
+ *
+ * @example
+ * ```ts
+ * import { runInStartEnv } from '@tanstack-router-testing/react-start-testing';
+ *
+ * const result = await runInStartEnv('server', () => {
+ *   // Code here sees `import.meta.env.SSR === true`
+ *   return fetchDataOnServer();
+ * });
+ * ```
+ *
+ * @remarks
+ * The environment is scoped to the execution of `fn` and is restored
+ * automatically even if `fn` throws. Used internally by
+ * {@link createStartTestRuntime} to set the environment for each
+ * {@link StartTestRuntime.run | run} invocation.
+ */
+declare const runInStartEnv: <T>(env: TestEnv, fn: () => T | Promise<T>) => Promise<T>;
+//#endregion
+//#region src/runtime.d.ts
+/**
+ * Configuration for {@link createStartTestRuntime}.
+ *
+ * @remarks
+ * At most one of `startInstance` and `startOptions` should be provided. If both
+ * are given, `startOptions` takes precedence. When neither is supplied the
+ * runtime creates an empty options object.
+ */
+interface StartTestRuntimeOptions {
+  /**
+   * A Start instance whose `getOptions()` method is called once during
+   * runtime creation. Ignored when {@link startOptions} is also provided.
+   */
+  readonly startInstance?: {
+    readonly getOptions: () => AnyStartInstanceOptions | Promise<AnyStartInstanceOptions>;
+  };
+  /** Explicit Start options to use instead of resolving from a `startInstance`. */
+  readonly startOptions?: AnyStartInstanceOptions;
+  /**
+   * The incoming request available to server functions via `getRequest()`.
+   * Accepts a full `Request`, a URL string, or a `URL` object.
+   * Defaults to `http://tanstack-router-testing.test/`.
+   */
+  readonly request?: Request | string | URL;
+  /** The TanStack Router instance made available via `getRouter()` inside server functions. */
+  readonly router?: AnyRouter;
+  /** Initial middleware context. Merged into each call's context before global request middlewares run. */
+  readonly context?: unknown;
+  /** Default simulated environment. Defaults to `'server'`. */
+  readonly env?: TestEnv;
+  /** Default handler type passed to the storage context. Defaults to `'serverFn'`. */
+  readonly handlerType?: StartHandlerType;
+}
+/**
+ * Per-invocation overrides passed to {@link StartTestRuntime.run} and
+ * {@link StartTestRuntime.call}.
+ *
+ * @remarks
+ * Every property mirrors a field from {@link StartTestRuntimeOptions}. When
+ * provided here it takes precedence over the runtime-level default for that
+ * single invocation only.
+ */
+interface StartTestRunOptions {
+  /** Override the request for this invocation. */
+  readonly request?: Request | string | URL;
+  /** Override the middleware context for this invocation. */
+  readonly context?: unknown;
+  /** Override the simulated environment (`'server'` or `'client'`) for this invocation. */
+  readonly env?: TestEnv;
+  /** Override the handler type for this invocation. */
+  readonly handlerType?: StartHandlerType;
+}
+/**
+ * A test runtime that simulates the TanStack Start server environment.
+ *
+ * @remarks
+ * Created by {@link createStartTestRuntime}. Provides the storage context,
+ * request, and environment that server functions expect at runtime. Call
+ * {@link cleanup} (or {@link clearStartMocks}) in `afterEach` to restore all
+ * mocks.
+ */
+interface StartTestRuntime {
+  /** The `Request` object available to server functions via `getRequest()`. */
+  readonly request: Request;
+  /** The resolved Start options used by the runtime. */
+  readonly startOptions: AnyStartInstanceOptions;
+  /**
+   * Run an arbitrary function inside the Start storage context.
+   *
+   * @typeParam T - The return type of `fn`.
+   * @param fn - The function to execute.
+   * @param options - Optional per-invocation overrides. See {@link StartTestRunOptions}.
+   * @returns A `Promise` resolving to the return value of `fn`.
+   */
+  readonly run: <T>(fn: () => T | Promise<T>, options?: StartTestRunOptions) => Promise<T>;
+  /**
+   * Invoke a server function (or any callable) with explicit arguments inside
+   * the Start storage context.
+   *
+   * @typeParam TArgs - Tuple of argument types.
+   * @typeParam TReturn - The return type of `fn`.
+   * @param fn - The function to call.
+   * @param args - Arguments forwarded to `fn`.
+   * @param options - Optional per-invocation overrides. See {@link StartTestRunOptions}.
+   * @returns A `Promise` resolving to the awaited return value of `fn`.
+   */
+  readonly call: <TArgs extends readonly unknown[], TReturn>(fn: (...args: TArgs) => TReturn | Promise<TReturn>, args: TArgs, options?: StartTestRunOptions) => Promise<Awaited<TReturn>>;
+  /**
+   * Remove all server-function and middleware mocks. Equivalent to calling
+   * {@link clearStartMocks}.
+   */
+  readonly cleanup: () => void;
+}
+/**
+ * Create a {@link StartTestRuntime} for executing server functions in a
+ * simulated TanStack Start environment.
+ *
+ * @param options - Runtime configuration. See {@link StartTestRuntimeOptions}.
+ * @returns A `Promise` resolving to a {@link StartTestRuntime} instance.
+ *
+ * @example
+ * ```ts
+ * import { createServerFn } from '@tanstack/react-start';
+ * import {
+ *   createStartTestRuntime,
+ *   mockServerFn,
+ * } from '@tanstack-router-testing/react-start-testing';
+ *
+ * const runtime = await createStartTestRuntime({
+ *   request: 'http://localhost:3000/api/orders',
+ *   env: 'server',
+ * });
+ *
+ * const listOrders = createServerFn()
+ *   .validator((input: { userId: string }) => input)
+ *   .handler(async ({ data }) => [{ id: '1', userId: data.userId }]);
+ *
+ * mockServerFn(listOrders, async ({ data }) => [
+ *   { id: 'mock-1', userId: data.userId },
+ * ]);
+ *
+ * const orders = await runtime.call(listOrders, [{ data: { userId: 'u1' } }]);
+ * // orders === [{ id: 'mock-1', userId: 'u1' }]
+ *
+ * runtime.cleanup();
+ * ```
+ *
+ * @remarks
+ * The runtime resolves Start options from either `startOptions` or
+ * `startInstance.getOptions()`, sets up the Start storage context, and
+ * executes global request middlewares before each invocation.
+ */
+declare const createStartTestRuntime: (options?: StartTestRuntimeOptions) => Promise<StartTestRuntime>;
+//#endregion
+//#region src/rsc.d.ts
+/**
+ * Configuration for {@link createRscTestRuntime}.
+ *
+ * @remarks
+ * Extends {@link StartTestRuntimeOptions} with an additional `streaming` flag
+ * that controls the server rendering mode.
+ */
+interface RscTestRuntimeOptions extends StartTestRuntimeOptions {
+  /**
+   * When `true`, renders via `renderToReadableStream` and collects individual
+   * chunks. When `false` (default), uses `renderToString` for a single
+   * synchronous HTML output.
+   */
+  readonly streaming?: boolean;
+}
+/**
+ * The result of rendering a React Server Component via
+ * {@link RscTestRuntime.renderServerComponent}.
+ */
+interface RscRenderResult {
+  /** The complete HTML string produced by the render. */
+  readonly html: string;
+  /**
+   * A cloned `ReadableStream` of the raw bytes. Only present when the runtime
+   * was created with `streaming: true`; otherwise `null`.
+   */
+  readonly stream: ReadableStream<Uint8Array> | null;
+  /**
+   * Decoded text chunks collected from the stream. Empty when `streaming` is
+   * `false`.
+   */
+  readonly chunks: readonly string[];
+}
+/**
+ * Extended test runtime that adds React Server Component rendering on top of
+ * the base {@link StartTestRuntime}.
+ *
+ * @remarks
+ * Created by {@link createRscTestRuntime}. Inherits all members from
+ * {@link StartTestRuntime} and adds {@link renderServerComponent}.
+ */
+interface RscTestRuntime extends StartTestRuntime {
+  /**
+   * Render a React Server Component to HTML.
+   *
+   * @typeParam TProps - The component's props type.
+   * @param component - The React component to render.
+   * @param props - Props forwarded to `createElement(component, props)`.
+   * @returns A `Promise` resolving to an {@link RscRenderResult} containing the
+   *   rendered HTML and, when streaming is enabled, the raw stream and decoded
+   *   chunks.
+   */
+  readonly renderServerComponent: <TProps extends Record<string, unknown>>(component: ComponentType<TProps>, props: TProps) => Promise<RscRenderResult>;
+}
+/**
+ * Create an {@link RscTestRuntime} for rendering React Server Components in a
+ * simulated TanStack Start environment.
+ *
+ * @param options - Runtime configuration. See {@link RscTestRuntimeOptions}.
+ * @returns A `Promise` resolving to an {@link RscTestRuntime} instance.
+ *
+ * @example
+ * ```ts
+ * import { createRscTestRuntime } from '@tanstack-router-testing/react-start-testing';
+ *
+ * const runtime = await createRscTestRuntime({ streaming: true });
+ *
+ * function Greeting({ name }: { name: string }) {
+ *   return <h1>Hello, {name}!</h1>;
+ * }
+ *
+ * const { html, chunks } = await runtime.renderServerComponent(Greeting, {
+ *   name: 'TanStack',
+ * });
+ * // html === '<h1>Hello, TanStack!</h1>'
+ *
+ * runtime.cleanup();
+ * ```
+ *
+ * @remarks
+ * Delegates to {@link createStartTestRuntime} for the base runtime, then layers
+ * on `renderServerComponent` which uses `react-dom/server` under the hood. Set
+ * `streaming: true` in options to render via `renderToReadableStream` instead of
+ * the default `renderToString`.
+ */
+declare const createRscTestRuntime: (options?: RscTestRuntimeOptions) => Promise<RscTestRuntime>;
+//#endregion
+//#region src/index.d.ts
+/**
+ * Current package version. Bumped at release time.
+ */
+declare const VERSION = "0.0.0";
+//#endregion
+export { type AnyServerFn, type CallMiddlewareOptions, type CallMiddlewareResult, type MockMiddlewareOptions, type RscRenderResult, type RscTestRuntime, type RscTestRuntimeOptions, type ServerFnMock, type StartTestRunOptions, type StartTestRuntime, type StartTestRuntimeOptions, VERSION, callMiddleware, clearStartMocks, createRscTestRuntime, createStartTestRuntime, mockMiddleware, mockServerFn, runInStartEnv };
+//# sourceMappingURL=index.d.mts.map