cloudflare / cloudflare/cloudflare-docs

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

Open
#29,395 1 comment 0 reactions 6 assignees Claimed by @WalshyDev View on GitHub
product:workers stale
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.