Open History to see the last commit
1# Playwright E2E Inference (Modes + Shards)
2β
3Use `scripts/nx/playwright-plugin.ts` to infer Playwright e2e targets from
4`package.json` metadata.
5β
6The plugin supports two metadata styles:
7β
8- `nx.metadata.playwrightModes` (recommended)
9- `nx.metadata.playwrightShards` (legacy, still supported)
10β
11When `playwrightModes` is present, it takes precedence.
12β
13## 1. Configure `playwrightModes` in `package.json`
14β
15```json
16{
17 "name": "tanstack-react-start-e2e-basic",
18 "nx": {
19 "metadata": {
20 "playwrightModes": [
21 { "toolchain": "vite", "mode": "ssr" },
22 { "toolchain": "vite", "mode": "spa", "shards": 4 },
23 { "toolchain": "vite", "mode": "prerender", "shards": 4 },
24 { "toolchain": "vite", "mode": "preview" }
25 ]
26 }
27 }
28}
29```
30β
31Supported modes:
32β
33- `ssr`
34- `spa`
35- `prerender`
36- `preview`
37β
38`shards` is optional and defaults to `1`.
39β
40Supported toolchains:
41β
42- `vite`
43β
44## 2. What targets are generated
45β
46For each `{ toolchain, mode }` entry, the plugin generates:
47β
48- `build:<toolchain>:<mode>`
49- `test:e2e--<toolchain>-<mode>`
50β
51If `shards > 1`, it also generates:
52β
53- `test:e2e--<toolchain>-<mode>--shard-1-of-N` ... `--shard-N-of-N`
54- `test:e2e--<toolchain>-<mode>` as a parent noop target depending on all shards
55β
56Finally, it generates:
57β
58- `test:e2e` as a parent noop target depending on every mode target
59β
60## 3. Environment variables injected by inferred targets
61β
62Each inferred `build:<toolchain>:<mode>` and `test:e2e--<toolchain>-<mode>` target sets:
63β
64- `MODE=<mode>`
65- `TOOLCHAIN=<toolchain>`
66- `E2E_TOOLCHAIN=<toolchain>`
67- `E2E_DIST=dist-<toolchain>-<mode>`
68- `E2E_DIST_DIR=dist-<toolchain>-<mode>`
69β
70## 4. Build behavior and webServer command
71β
72Each inferred e2e target depends on the inferred `build:<toolchain>:<mode>`
73target. It runs `vite build && tsc --noEmit` or
74`rsbuild build && tsc --noEmit`, selecting the toolchain explicitly. Ordinary
75package build scripts do not need to know about E2E mocking.
76β
77The React, Solid, and Vue basic examples preload the same MSW handlers in
78Nx prerender builds (through mode metadata) and Playwright application servers
79with Node's native option:
80`NODE_OPTIONS='--import=@tanstack/router-e2e-utils/mock-api'`.
81The handlers return canned posts and users at `https://jsonplaceholder.typicode.com` inside
82each Node process, including prerendering. No API listener or fixture port is
83needed. Playwright starts only the application server. A cached build uses the
84same URL when started by a fresh process with the preload enabled. Ordinary
85`pnpm dev`, builds, and standalone servers use the public API without MSW.
86Application code uses the public URL in both cases; test setup enables mocking.
87β
88The inferred build target uses standard production inputs and explicit mode-
89specific outputs (`dist-<toolchain>-<mode>`). Mode env values are passed through
90the target command env, so they do not need to be duplicated as target input
91env hashes.
92β
93Because of this, Playwright `webServer.command` should only start the app.
94β
95Good:
96β
97```ts
98webServer: {
99 command: `PORT=${PORT} pnpm start`,
100 wait: appServerReady,
101}
102```
103β
104For preview mode, pass the inferred dist folder:
105β
106```ts
107const distDir = process.env.E2E_DIST_DIR ?? 'dist'
108β
109webServer: {
110 command: `pnpm preview --outDir ${distDir} --port ${PORT}`,
111 wait: appServerReady,
112}
113```
114β
115Avoid:
116β
117```ts
118webServer: {
119 command: `MODE=spa pnpm build && PORT=${PORT} pnpm start`,
120 wait: appServerReady,
121}
122```
123β
124## 5. Let each server bind its own port
125β
126Use port `0` in server commands. The OS chooses a free port while binding the
127listening socket. Do not reserve ports, write port files, or restore ports from
128Nx outputs.
129β
130Playwright's `webServer.wait` captures the address printed after listening.
131It exports named capture groups to subsequent servers and test workers. The
132shared `appServerReady` pattern captures `E2E_APP_PORT`; configs read that value
133when reloaded in workers to configure `use.baseURL`.
134β
135```ts
136import { appServerReady } from '@tanstack/router-e2e-utils'
137β
138const baseURL = `http://localhost:${process.env.E2E_APP_PORT ?? 0}`
139β
140// Inside defineConfig:
141use: { baseURL },
142webServer: {
143 command: 'pnpm preview --port 0',
144 wait: appServerReady,
145 reuseExistingServer: false,
146},
147```
148β
149Canned posts/users requests use `https://jsonplaceholder.typicode.com`. Node builds and
150servers preload `@tanstack/router-e2e-utils/mock-api` through `NODE_OPTIONS`.
151Browser API suites import `apiTest as test` from the E2E utilities. That fixture
152uses the official MSW Playwright adapter with the same handlers. Opt in only
153where the API is needed: Playwright routing disables the browser HTTP cache.
154β
155External-navigation tests use another hostname on the existing app listener,
156with a static HTML asset when the test needs a distinct destination document.
157No API server, fixture-port environment variable, or build launcher is needed.
158β
159Custom servers must print their actual `server.address().port`, not the
160requested port. SPA servers bind their backend first and use its actual port
161for proxying. Playwright owns server shutdown.
162β
163## 6. Run inferred targets
164β
165Examples:
166β
167```sh
168pnpm nx run tanstack-react-start-e2e-basic:test:e2e--vite-ssr
169pnpm nx run tanstack-react-start-e2e-basic:test:e2e--vite-spa--shard-1-of-4
170pnpm nx run tanstack-react-start-e2e-basic:test:e2e
171```
172β
173## Legacy fallback: `playwrightShards`
174β
175If `playwrightModes` is not configured, the plugin still supports:
176β
177```json
178{
179 "nx": {
180 "metadata": {
181 "playwrightShards": 6
182 }
183 }
184}
185```
186β
187This generates legacy shard targets under `test:e2e--shard-...` plus a parent
188`test:e2e` target.