Document that Node.js-dependent test libraries (jest-image-snapshot, etc.) are not compatible with vitest-pool-workers

[penalosa]

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

• 🐛 BUG: jest-image-snapshot is not work with the new vitest integration workers-sdk#5605
• [vitest-pool-workers] Bump RTTI compat date workers-sdk#13091

[github-actions]

Hey there, we've marked this issue as stale because there's no recent activity on it. This label helps us identify long-standing issues in our repo (and not used to auto-close issues).