@kasperpeulen/vitest-plugin-nextjs 0.0.0-stage → 0.1.0-alpha.1

package/README.md

@@ -1,3 +1,250 @@
-# Temporary Holding Version
+# Storybook for Pages
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> End-to-end stories and tests of the pages of a framework app, with as little mocking as possible. Next.js first.
+
+[![CI](https://github.com/storybookjs/storybook-for-pages/actions/workflows/ci.yml/badge.svg)](https://github.com/storybookjs/storybook-for-pages/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/storybookjs/storybook-for-pages/blob/main/LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D24-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![pnpm](https://img.shields.io/badge/pnpm-11-F69220?logo=pnpm&logoColor=white)](https://pnpm.io/)
+
+A page of your app runs with the framework's own runtime: in a Vitest test, in `vite dev` and in a Storybook story. Next.js comes first. React Router, TanStack Start, SvelteKit and Nuxt come later, each as a Vite plugin with a Storybook framework on top.
+
+| Package                                                                         | What it is                                                                                               |
+| ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| [`@kasperpeulen/vitest-plugin-nextjs`](https://github.com/storybookjs/storybook-for-pages/blob/main/packages/vitest-plugin-nextjs)           | The Next.js plugin for Vite: a page of a Next.js app in Vitest Browser Mode, `vite dev` and Storybook.   |
+| [`@kasperpeulen/storybook-nextjs-vite-rsc`](https://github.com/storybookjs/storybook-for-pages/blob/main/packages/storybook-nextjs-vite-rsc) | The Storybook framework on top of it: stories of whole pages and of Server Components.                   |
+| [`@kasperpeulen/vitest-plugin-rsc`](https://github.com/storybookjs/storybook-for-pages/blob/main/packages/vitest-plugin-rsc)                 | The core, without a framework: React Server Components in one browser tab, server, Flight and hydration. |
+| [`@kasperpeulen/dom-locators`](https://github.com/storybookjs/storybook-for-pages/blob/main/packages/dom-locators)                           | Vitest Browser Mode's page locators answered in the document, also in a DOM of Node.js.                  |
+
+All of them are alphas: `npm install` without a tag gets the last one.
+
+Write a test, render a page of your Next.js app, click around, check the database. No dev server, no deployment, no mocks of Next.js.
+
+```tsx
+test("archive a note", async () => {
+  await signedInAs(testUser);
+  await db.insert(notes).values({ ownerId: testUser.id, title: "Inbox triage" });
+
+  await renderServer({ url: "/notes" });
+  await expect.element(page.getByText("Inbox triage")).toBeVisible();
+
+  await page.getByRole("button", { name: "Archive Inbox triage" }).click();
+  await expect.element(page.getByText("Inbox triage")).not.toBeInTheDocument();
+});
+```
+
+That test seeds a database, renders the `/notes` route on the server, hydrates it in a real browser, runs a Server Action and checks the result. All in one browser tab.
+
+The trick: the plugin runs your server code _in the test's browser tab_. Next's own request handler renders the route, Next's own client hydrates it, and the `db` your test seeds is the very same module your Server Components read. In the notes demo, that database is Postgres compiled to WebAssembly.
+
+## Why
+
+Server Components have been hard to test. Rendering one in a unit test has been [an open problem since 2023](https://github.com/testing-library/react-testing-library/issues/1209), so they've mostly been left to E2E tests. And E2E tests are slow, share a server and a database, and get flaky. That's why validation errors, roles, empty states, feature flags and time-dependent code usually go untested.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/storybookjs/storybook-for-pages/main/docs/assets/test-pyramid.svg" alt="Test pyramid: a small Playwright E2E layer above a wider Vitest unit, component, and integration layer" width="760" />
+</p>
+
+This plugin moves that coverage down to the fast part of the pyramid:
+
+- **Everything lives in the tab.** The file system is in memory, the database is a [real engine in WebAssembly](https://github.com/storybookjs/storybook-for-pages/blob/main/docs/databases.md), and outgoing requests go to [MSW](https://mswjs.io/docs/recipes/vitest-browser-mode).
+- **Test files run in parallel.** Every Vitest worker gets its own tab, with its own server, database, disk, cookies and storage.
+- **Every test starts clean.** Cookies, storage, the disk and Next's cache are reset before each test.
+
+That also makes it a nice loop for coding agents: edit, run, fix, repeat.
+
+### Is it really Next.js?
+
+Yes. The plugin doesn't reimplement Next. It swaps the bundler for Vite and runs Next's runtime unchanged. To keep that honest, the repo runs Next's own e2e tests against the plugin: **967 of the 1,139 that apply pass (85%)** on `next@16.4.0`. Every failure is listed with a reason in the [conformance report](https://github.com/storybookjs/storybook-for-pages/blob/main/docs/internals/next-conformance.md). CI also tests against `next@latest` and `next@canary`.
+
+## Quick start
+
+You need:
+
+- Vite 8+ and Vitest 5.0.4+ in [Browser Mode](https://vitest.dev/guide/browser/) (the examples use Playwright).
+- A Next.js App Router app on `next@16.4` or later.
+
+### 1. Install
+
+```bash
+npm install -D @kasperpeulen/vitest-plugin-rsc @kasperpeulen/vitest-plugin-nextjs vitest @vitest/browser-playwright playwright @types/node@24
+# Next's route resolution, pinned to your `next` version
+npm install -D -E @next/routing@$(node -p "require('next/package.json').version")
+npx playwright install chromium
+```
+
+A few notes:
+
+- The plugins are in **alpha**. The API can still change from one release to the next.
+- `@kasperpeulen/vitest-plugin-nextjs` is built on `@kasperpeulen/vitest-plugin-rsc`, which it has as a peer dependency: install both, at the same release.
+- `@next/routing` must match your `next` version exactly. Upgrade them together.
+- Vitest 5 needs `@types/node` 22+, and create-next-app installs 20, hence the bump.
+
+### 2. Configure Vitest
+
+```ts
+// vitest.config.mts
+import { playwright } from "@vitest/browser-playwright";
+import { defineConfig } from "vitest/config";
+import { vitestPluginRSC } from "@kasperpeulen/vitest-plugin-rsc";
+import { vitestPluginNext } from "@kasperpeulen/vitest-plugin-nextjs";
+
+export default defineConfig({
+  plugins: [vitestPluginRSC(), vitestPluginNext()],
+  test: {
+    browser: {
+      enabled: true,
+      headless: true,
+      provider: playwright(),
+      instances: [{ browser: "chromium" }],
+    },
+    include: ["**/*.test.{ts,tsx}"],
+    isolate: false,
+  },
+});
+```
+
+- No setup file needed: the plugin cleans up around every test.
+- `isolate: false` loads your app's server once per worker instead of once per file. It does mean the test files in a worker share modules, so put mocks in a [setup file](https://github.com/storybookjs/storybook-for-pages/blob/main/docs/nextjs-guide.md#mocks).
+- `.mts` makes the config load as ESM, which matters if your `package.json` has no `"type": "module"`.
+- `include` keeps Playwright's `*.spec.ts` files out.
+- Add `.vitest/` to `.gitignore`. That's where screenshots of failed tests go.
+
+### 3. Write a test
+
+A Server Component that reads a cookie and bumps it from a Server Action:
+
+```tsx
+// app/likes.tsx
+import { cookies } from "next/headers";
+
+export async function Likes() {
+  const likes = Number((await cookies()).get("likes")?.value ?? 0);
+
+  return (
+    <form
+      action={async () => {
+        "use server";
+        (await cookies()).set("likes", String(likes + 1));
+      }}
+    >
+      <button>Likes: {likes}</button>
+    </form>
+  );
+}
+```
+
+And its test:
+
+```tsx
+// app/likes.test.tsx
+import { expect, test } from "vitest";
+import { page } from "vitest/browser";
+import { renderServer } from "@kasperpeulen/vitest-plugin-nextjs/testing-library";
+import { Likes } from "./likes";
+
+test("likes from a Server Action", async () => {
+  await renderServer(<Likes />, { headers: { cookie: "likes=41" } });
+
+  await page.getByRole("button", { name: "Likes: 41" }).click();
+  await expect.element(page.getByRole("button", { name: "Likes: 42" })).toBeVisible();
+});
+
+test("opens the home page", async () => {
+  const { response } = await renderServer({ url: "/" });
+
+  expect(response.status).toBe(200);
+});
+```
+
+The first test renders a single component, Testing Library style, but on Next's server. The click runs the Server Action, and Next renders again with the new cookie. The second test opens your home page like a browser would.
+
+### 4. Run it
+
+```bash
+npx vitest
+```
+
+Vitest starts Chromium and watches your files. Use `npx vitest run` in CI. The first test in each worker is a bit slower, because it loads Next's runtime.
+
+## What you can test
+
+Pretty much everything Next does. Your files go through Next's own compiler, so `next/font`, `next/image`, `next/dynamic` and styled-jsx just work, and a mistake that would break `next build` breaks your test too. Routes, layouts, `loading.tsx`, error boundaries, redirects, cookies, Server Actions, route handlers, caching and `proxy.ts` all behave as they do in Next.
+
+Head to the **[Next.js guide](https://github.com/storybookjs/storybook-for-pages/blob/main/docs/nextjs-guide.md)** for an example of each.
+
+For a quicker feedback loop, `VITEST_PLUGIN_RSC_MODE=fast npx vitest` runs in [fast mode](https://github.com/storybookjs/storybook-for-pages/blob/main/docs/nextjs-guide.md#fast-mode): the pages of a test file render in one app, without HTML from the server, prefetching or page loads. Keep CI in fidelity mode, the default. [Fast testing patterns](https://github.com/storybookjs/storybook-for-pages/blob/main/docs/fast-testing-patterns.md) has what each test costs, and what else makes it cheaper.
+
+### Databases
+
+Browsers have no TCP sockets, so the database runs in the tab: a real engine in WebAssembly. Your app keeps its ORM, queries and migrations. Tests mock just one module, `db.ts`.
+
+|                                  | Drizzle | Prisma | Kysely | SQL |
+| -------------------------------- | ------- | ------ | ------ | --- |
+| Postgres, on PGlite              | ✅      | ✅     | ✅     | ✅  |
+| SQLite, on `@libsql/client-wasm` | ✅      | ✅     | ✅     | ✅  |
+| MySQL, on MariaDB in WebAssembly | ✅      | ✅     | ✅     | ✅  |
+
+There's a Redis recipe for `ioredis` too. See [Databases](https://github.com/storybookjs/storybook-for-pages/blob/main/docs/databases.md).
+
+### Storybook
+
+[`@kasperpeulen/storybook-nextjs-vite-rsc`](https://github.com/storybookjs/storybook-for-pages/blob/main/packages/storybook-nextjs-vite-rsc) brings the same thing to Storybook. A story can render a whole page of your app, with the same mocks as your tests. Even a static, deployed Storybook carries its database along, so forms really submit.
+
+### Without Next.js
+
+`vitestPluginRSC()` on its own renders Server Components for any React app. See [RSC without Next.js](https://github.com/storybookjs/storybook-for-pages/blob/main/docs/rsc-without-nextjs.md).
+
+## Good to know
+
+It's Next's real runtime, but in a browser tab. A few things follow from that:
+
+- **No `test.concurrent`.** Tests in one file run one after another. Files still run in parallel.
+- **No native addons or TCP sockets.** Use a [database recipe](https://github.com/storybookjs/storybook-for-pages/blob/main/docs/databases.md), a WebAssembly alternative, or MSW.
+- **Development React by default.** A Server Component's error message reaches the client, where a deployment would send a digest. Use [`build: "production"`](https://github.com/storybookjs/storybook-for-pages/blob/main/docs/nextjs-guide.md#development-or-production) to match a deployment.
+- **Some Next features aren't supported yet**, like `opengraph-image` image rendering, the React Compiler and most custom `webpack` config.
+
+The full list is in [Limitations](https://github.com/storybookjs/storybook-for-pages/blob/main/docs/limitations.md).
+
+## Documentation
+
+**Guides**
+
+- [Testing a Next.js app](https://github.com/storybookjs/storybook-for-pages/blob/main/docs/nextjs-guide.md): the main guide.
+- [Testing Client Components](https://github.com/storybookjs/storybook-for-pages/blob/main/docs/use-client-test-files.md) in a `"use client"` test file.
+- [Databases](https://github.com/storybookjs/storybook-for-pages/blob/main/docs/databases.md): Postgres, SQLite, MySQL and Redis in the tab.
+- [Fast testing patterns](https://github.com/storybookjs/storybook-for-pages/blob/main/docs/fast-testing-patterns.md): how to make a suite fast, and what each pattern costs and gives up.
+- [Fast tests](https://github.com/storybookjs/storybook-for-pages/blob/main/docs/fast-tests.md): the measurements behind them, and the quickest feedback loop.
+- [Node.js in the browser](https://github.com/storybookjs/storybook-for-pages/blob/main/docs/nodejs-in-the-browser.md): which Node APIs work, and the in-memory disk.
+- [Static builds](https://github.com/storybookjs/storybook-for-pages/blob/main/docs/static-build.md): `vite build`, and how to serve the result.
+- [RSC without Next.js](https://github.com/storybookjs/storybook-for-pages/blob/main/docs/rsc-without-nextjs.md).
+
+**Reference**
+
+- [API reference](https://github.com/storybookjs/storybook-for-pages/blob/main/docs/api.md)
+- [Limitations](https://github.com/storybookjs/storybook-for-pages/blob/main/docs/limitations.md)
+
+**Under the hood**
+
+- [Internals](https://github.com/storybookjs/storybook-for-pages/blob/main/docs/internals/README.md): how it all works, the Next.js conformance suite, benchmarks and releasing. Detailed, and mostly for contributors.
+
+## Publishing
+
+Release Please and `.github/workflows/release.yml` release the four packages, each with a version of its own: see [Releasing](https://github.com/storybookjs/storybook-for-pages/blob/main/docs/internals/releasing.md). A release goes to npm with npm's trusted publishing, an OIDC token of the workflow, without an npm token.
+
+That is set up for all four packages:
+
+- Each package exists on npm, from a first publish by hand.
+- Each has a trusted publisher on npmjs.com: GitHub Actions, organization `storybookjs`, repository `storybook-for-pages`, workflow `release.yml`.
+
+To check it for a package:
+
+```sh
+npm trust list @kasperpeulen/vitest-plugin-nextjs
+```
+
+npm makes no provenance for a package of a private repository, so the workflow publishes without `--provenance`.
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/storybookjs/storybook-for-pages/blob/main/CONTRIBUTING.md).

package/dist/_virtual/_rolldown/runtime.js

@@ -0,0 +1,14 @@
+import "node:module";
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll };

package/dist/action-ids.d.ts

@@ -0,0 +1,18 @@
+import { ServerRequest } from "./registry.js";
+
+//#region src/action-ids.d.ts
+/**
+ * The ids of the Server Actions that `request` names. Next's router names the
+ * one it calls in the `next-action` header. A form that the browser posts
+ * itself, as React renders one for a Server Action, to work before the app
+ * has hydrated or without JavaScript, names them in its fields, which Next's
+ * `decodeAction()` and `areAllActionIdsValid()` read: a field
+ * `$ACTION_ID_<id>`, or `$ACTION_REF_<n>` with the id in the field
+ * `$ACTION_<n>:0`, for an action with bound arguments.
+ *
+ * Next reads the whole body of such a request first, and so does this: from
+ * a copy, which leaves `request` a body of its own.
+ */
+declare function actionIdsOf(request: ServerRequest): Promise<string[]>;
+//#endregion
+export { actionIdsOf };

package/dist/action-ids.js

@@ -0,0 +1,44 @@
+import { registry } from "./registry.js";
+//#region src/action-ids.ts
+const actionIdField = "$ACTION_ID_";
+const actionReferenceField = "$ACTION_REF_";
+/**
+* The ids of the Server Actions that `request` names. Next's router names the
+* one it calls in the `next-action` header. A form that the browser posts
+* itself, as React renders one for a Server Action, to work before the app
+* has hydrated or without JavaScript, names them in its fields, which Next's
+* `decodeAction()` and `areAllActionIdsValid()` read: a field
+* `$ACTION_ID_<id>`, or `$ACTION_REF_<n>` with the id in the field
+* `$ACTION_<n>:0`, for an action with bound arguments.
+*
+* Next reads the whole body of such a request first, and so does this: from
+* a copy, which leaves `request` a body of its own.
+*/
+async function actionIdsOf(request) {
+	if (request.method !== "POST") return [];
+	const header = request.headers.get("next-action");
+	if (header !== null) return [header];
+	const contentType = request.headers.get("content-type") ?? "";
+	if (!/^multipart\/form-data\b/i.test(contentType)) return [];
+	let { body } = request;
+	if (body instanceof ReadableStream) [body, request.body] = body.tee();
+	let form;
+	try {
+		form = await new registry.Response(body, { headers: { "content-type": contentType } }).formData();
+	} catch {
+		return [];
+	}
+	const ids = [];
+	for (const name of form.keys()) {
+		if (name.startsWith(actionIdField)) ids.push(name.slice(11));
+		if (!name.startsWith(actionReferenceField)) continue;
+		const reference = form.get(`$ACTION_${name.slice(12)}:0`);
+		try {
+			const { id } = JSON.parse(typeof reference === "string" ? reference : "");
+			if (typeof id === "string") ids.push(id);
+		} catch {}
+	}
+	return ids;
+}
+//#endregion
+export { actionIdsOf };

package/dist/adapter.d.ts

@@ -0,0 +1,8 @@
+import { NextAdapter } from "next";
+
+//#region src/adapter.d.ts
+/** Who waits for the outcome of a build, by the build directory it made up for it. */
+declare const receivers: Map<any, any>;
+declare const adapter: NextAdapter;
+//#endregion
+export { adapter as default, receivers };

package/dist/adapter.js

@@ -0,0 +1,12 @@
+//#region src/adapter.ts
+const scope = globalThis;
+/** Who waits for the outcome of a build, by the build directory it made up for it. */
+const receivers = scope.__vitest_plugin_rsc_next_adapter__ ??= /* @__PURE__ */ new Map();
+const adapter = {
+	name: "vitest-plugin-rsc",
+	onBuildComplete(context) {
+		receivers.get(context.distDir)?.(context);
+	}
+};
+//#endregion
+export { adapter as default, receivers };

package/dist/app-requests.d.ts

@@ -0,0 +1,63 @@
+import { Opened } from "./registry.js";
+import { PageStore } from "./page-store.js";
+
+//#region src/app-requests.d.ts
+/** Says which page of the app is open, by its signal, which aborts as it is left. */
+declare function setOpenPage(signal: AbortSignal | undefined): void;
+/** Says whether the router of the pages outlives them, from now on. */
+declare function setRouterOutlivesPage(outlives: boolean): void;
+declare function leftTheApp(url: URL): Error;
+declare function unlessAborted<T>(answer: Promise<T>, signal: AbortSignal, abandon: (answer: Promise<T>) => void): Promise<T>;
+type Sending<Passed = never> = {
+  /**
+   * The store of the page, as it was when the request started: what it sends
+   * besides its own headers, and where the cookies of its responses go. None
+   * for a request the server makes to itself while it handles another. That
+   * one carries the headers it was given, cookies included, and does not wait
+   * for the request it is part of.
+   */
+  from: PageStore | undefined;
+  /**
+   * Whether it sends the cookies of the store and keeps the ones it gets: not
+   * with `credentials: "omit"`. A `cookie` header of its own it sends either way.
+   */
+  credentials?: boolean;
+  /**
+   * A page load, which leaves the app when it is redirected to another
+   * origin: one that the test opens, or one of the app's own, sent while the
+   * page before it is still open (see `navigate()` in page.ts). That one
+   * opens nothing of what the test opened, also after a redirect, and
+   * starts no files of its route, which leaving that page would take back.
+   * What it opens is its `opened`, after a redirect too: from a page of fast
+   * mode's kept app, a page without HTML.
+   */
+  navigation?: "test" | "app"; /** Who answers a request that the server has nothing for: see `HandleOptions.unrouted`. */
+  network?: () => Promise<Response | NoInfer<Passed>>; /** What the request opens, not after a redirect: see `HandleOptions.opened`. */
+  opened?: Opened;
+};
+declare function sendRequest<Passed extends undefined = never>(request: Request, {
+  from,
+  credentials,
+  navigation,
+  network,
+  opened
+}: Sending<Passed>): Promise<Response | NoInfer<Passed>>;
+type Network<Passed> = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response | Passed>;
+/**
+ * The browser's `fetch` while a browser context of the app is open: what
+ * Next's client router and Client Components call. `store()` is the store of
+ * the context, and `network()` the `fetch` the document had before it, which
+ * gets every request that is not the app's, or, where the DOM hands over the
+ * page's requests, one that answers none, for the DOM to send. Without a
+ * context, `network()` gets every request: code that took this `fetch` in a
+ * context has the document's own after it.
+ *
+ * Next marks the requests it sends for a page, with an `rsc` or a
+ * `next-action` header. They belong to the page that is open as they are
+ * sent. Its router is there only once its page is, so without a page that
+ * page was left, and it sends nothing more. A test asks with
+ * `handleRequest()`.
+ */
+declare function pageFetch<Passed extends undefined = never>(store: () => PageStore | undefined, network: () => Network<NoInfer<Passed>>): Network<Passed>;
+//#endregion
+export { Sending, leftTheApp, pageFetch, sendRequest, setOpenPage, setRouterOutlivesPage, unlessAborted };