Skip to content
Source
Sign inSign up
TanStack/router
Open History to see the last commit

playwright-plugin.md

188 lines5.4 KB

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
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 }
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,
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,
113```
114​
115Avoid:
116​
117```ts
118webServer: {
119 command: `MODE=spa pnpm build && PORT=${PORT} pnpm start`,
120 wait: appServerReady,
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
179 "nx": {
180 "metadata": {
181 "playwrightShards": 6
182 }
183 }
185```
186​
187This generates legacy shard targets under `test:e2e--shard-...` plus a parent
188`test:e2e` target.