You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit f6902af
Browse filesBrowse the repository at this point in the historyBrowse files
fix(vitest): run app tests without starting the Worker
`vp test` stopped with a startup error before running any test in Void
apps on the default Cloudflare target, including a fresh
`npm create void` app:
ReferenceError: module is not defined
With `nodejs_compat`, which Void turns on for auth, PostgreSQL, MySQL,
Sandbox, and TanStack Start, React Router and vinext apps:
Error: AssertionError: depsOptimizer is required in dev mode
Vitest loads `vite.config.ts` and starts a Vite server of its own, so
the Cloudflare Vite plugin that `voidPlugin()` includes started the
Worker there too. Vitest turns off dependency prebundling in nearly
every environment, the Worker's included, and the Cloudflare plugin
relies on it: a CommonJS dependency such as React reached workerd
unconverted, and the plugin's own nodejs_compat polyfill import
asserted on the missing optimizer. Users could not remove the plugin,
and `test.deps.optimizer` does not bring discovery back.
## Fix
`isVitestServer()` recognizes the server that Vitest creates by the
plugins Vitest adds to it (`vitest`, `vitest:*`), in any `--mode`. A
server that a test starts through Vite's API, and `vp dev --mode test`,
are not Vitest's and keep everything.
In Vitest's server:
- The plugins of Void's Cloudflare wrapper, the Cloudflare Vite plugin
included, do not apply, in Void apps and in framework apps. Void's
other plugins still resolve `void/*`, `@schema` and the generated
modules, so tests can import route handlers and page loaders.
- `migrationPlugin` does not apply, so a test run no longer migrates
the local D1 database or the PostgreSQL or MySQL database in `.env`.
- The AI project setup prints its hint instead of prompting.
Tests run in Node.js, so a call that reaches a binding still throws
`env: Cloudflare env is unavailable`; `vi.mock()` can replace the
binding module.
## Tests
- Unit: the detection, the Cloudflare wrapper and the migration plugin
with and without Vitest's plugins (modes `test` and `staging`), and
the AI setup prompt.
- Integration: `vp test` in isolated copies of the React Pages
playground (as is, with `nodejs_compat` and with `--mode staging`)
and the TanStack Start playground.
- Packed consumer: Vite+ fixtures run `vp test` with a mocked binding.
## Docs
Add a Testing guide: `vp test` needs no configuration, tests run in
Node.js without bindings, and test files stay out of the convention
directories. Link it from the email testing sections and the Void
skill, and note the Vitest server in the package AGENTS.md.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The harness matches handlers in the same order as deployed email routes.
141
+
The harness matches handlers in the same order as deployed email routes.[Testing](../testing.md) explains how to run tests and how to test code that uses other bindings.
The harness intercepts every `sendEmail` call until `dispose()` is called. `clear()` empties the captured list without releasing the sink.
257
+
The harness intercepts every `sendEmail` call until `dispose()` is called. `clear()` empties the captured list without releasing the sink.[Testing](../testing.md) explains how to run tests and how to test code that uses other bindings.
258
258
259
259
To handle incoming messages, see [Receiving Email](./receiving.md).
Test your app with [Vitest](https://vitest.dev/). With Vite+, the default toolchain, run it with `vp test`:
8
+
9
+
```sh
10
+
vp test
11
+
```
12
+
13
+
Import test APIs from `vite-plus/test`. With the Vite toolchain, add `vitest` to your dev dependencies, run `vitest`, and import from `vitest` instead.
14
+
15
+
Vitest reads your `vite.config.ts`, so `void/*` imports, `@schema`, and the other modules Void provides resolve in tests as they do in your app. Tests need no separate configuration.
16
+
17
+
Keep test files out of the [convention directories](../reference/structure.md) such as `routes/` and `pages/`. Void reads the files there as part of your app, so a test file in `routes/` becomes a route. Put tests in `tests/`, or next to the code they test in `src/`.
18
+
19
+
## Bindings {#bindings}
20
+
21
+
Tests run in Node.js, not in the Workers runtime. Void doesn't start your Worker for a test run, so D1, KV, R2, and other bindings are unavailable, and it doesn't apply migrations to your local database. You can import modules that use bindings, but a call that reaches one throws `env: Cloudflare env is unavailable`.
22
+
23
+
To test code that uses a binding, replace its module with [`vi.mock()`](https://vitest.dev/api/vi#vi-mock):
`void/email/testing` captures sent and received email in tests. See [Testing](./email/sending.md#testing) in Sending Email and [Testing inbound handlers](./email/receiving.md#testing-inbound-handlers) in Receiving Email.
Copy file name to clipboardExpand all lines: packages/void/AGENTS.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -222,6 +222,7 @@ production functions and real generated entries rather than copied code.
222
222
223
223
-**Workers types 5 still declares the Buffer constructor as `any`.** In the mixed Node/Workers type environment, this also affects `node:buffer`'s exported value. CLI code and tests that need Buffer constructor inference or narrowing use `cli/node-buffer.ts`, which retains Node's `BufferConstructor` signatures. Keep `workers-node-globals.typecheck.ts` covering constructor checks and Node Buffer instance methods.
224
224
-**Cloudflare browser login needs all terminal streams.**`cf auth login` prints its device confirmation code to stderr, so the auth and deploy runners inherit stdin, stdout, and stderr only for login; credential reads stay captured. Keep the asynchronous platform runner cancellable.
225
+
-**Vitest runs an app's tests in a Vite server of its own.** That server loads the app's Vite config, so serve plugins run there too, but Vitest turns off dependency prebundling, which the Cloudflare plugin needs to start the Worker (`module is not defined`, or `depsOptimizer is required in dev mode` with `nodejs_compat`). `isVitestServer()` in `plugin-dev-config.ts` recognizes the server by Vitest's plugin names, in any `--mode`. `cloudflare()` and `migrationPlugin` do not apply there, and the AI setup prints its hint instead of prompting. A server that a test starts through Vite's API keeps them all. Gate new dev-server work that changes a database or asks questions the same way; code generation still runs. `test/integration/vitest-app.test.ts` runs the tests of a Void app and a framework app; check Vitest's plugin names again when updating it.
225
226
-**Cloudflare compatibility flags must be merged as a set.** The Cloudflare plugin concatenates callback arrays with the resolved generated config. `mergeBindings` must emit the union once and clear the in-memory fallback, preserving all distinct flags without rewriting authored config. Existing Worker handoff copies production flags into the generated Cloudflare config, so concatenation otherwise causes upload error `10021` (`Compatibility flag specified multiple times`). Keep real-build coverage for `cloudflare` and `worker` overlap.
226
227
-**`__VOID_ISR_DEPLOYMENT_ID` must be a compile-time literal.**`router/compile.ts` stringifies `crypto.randomUUID()` once at build time (`export const __VOID_ISR_DEPLOYMENT_ID = "..."`, exactly like `__VOID_BUILD_KEY`) so every isolate of a deployment shares one id. A bare runtime `crypto.randomUUID()` per-isolate in the emitted source would mint a fresh id per isolate, so the edge-cache key (`handleIsr`'s `deploymentId` option) and the KV key (`env.__VOID_ISR_DEPLOYMENT_ID`, also used by the `revalidate()` purge path) would disagree — breaking cache reads and on-demand purge.
227
228
-**Self-host ISR requires a user-declared `ISR_CACHE` KV.** There is no `id: 'local'` injection for it: a placeholder id is fine for miniflare-backed dev but breaks a real `wrangler deploy`, which rejects an unknown namespace id. The user creates the namespace and binds it as `ISR_CACHE`; `readIsrCache`/`writeIsrCache` fail open to a live render when it is absent.
0 commit comments