cloudflare / cloudflare/cloudflare-docs
Document that Node.js-dependent test libraries (jest-image-snapshot, etc.) are not compatible with vitest-pool-workers
- Dominant language
- MDX
- Stars
- 5.2k
- Forks
- 16.7k
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 337
Description
## Context
We regularly get reports from users trying to use Node.js-native testing libraries like `jest-image-snapshot` with `@cloudflare/vitest-pool-workers` (e.g. cloudflare/workers-sdk#5605). These libraries fail because they depend on Node.js APIs (`fs`, `child_process`, etc.) that are either unavailable or stub-only in the Workers runtime.
The error users hit is typically `No such module "node:child_process"` at import time, which is confusing — it doesn't explain *why* the library can't work.
## Suggested change
Add a known issue entry to https://developers.cloudflare.com/workers/testing/vitest-integration/known-issues/ explaining that:
- Tests in `vitest-pool-workers` run inside the workerd runtime, not Node.js
- Libraries that depend on Node.js-only APIs (filesystem, process spawning, native addons, etc.) are not compatible
- Common examples: `jest-image-snapshot` (needs `fs` + `child_process`), image processing libraries that shell out, etc.
- The error message may be `No such module "node:..."` — this means the library requires a Node.js API that Workers doesn't implement
## Related
- cloudflare/workers-sdk#5605
- cloudflare/workers-sdk#13091
Contributor guide
Assessment
This issue has not been assessed yet.