docs: add ctx.exports documentation for vitest-pool-workers (#27037)

petebacondarwin · devin-ai-integration[bot] · web-flow · commit dfd033fc4a89 · 2025-12-19T13:52:07.000Z
* docs: add ctx.exports documentation for vitest-pool-workers

- Add link to context-exports fixture on recipes page
- Add known issue about missing ctx.exports properties and additionalExports workaround

Co-Authored-By: pbacondarwin@cloudflare.com &lt;pete@bacondarwin.com&gt;

* docs: add example of problematic code scenario for ctx.exports

Address reviewer feedback by adding a brief example showing a wildcard
re-export from a virtual module that cannot be automatically inferred.

Co-Authored-By: pbacondarwin@cloudflare.com &lt;pete@bacondarwin.com&gt;

---------

Co-authored-by: Devin AI &lt;158243242+devin-ai-integration[bot]@users.noreply.github.com&gt;
diff --git a/src/content/docs/workers/testing/vitest-integration/known-issues.mdx b/src/content/docs/workers/testing/vitest-integration/known-issues.mdx
@@ -69,6 +69,40 @@ test('check if file exists', async () => {
 });
 ```
 
+### Missing properties on `ctx.exports`
+
+The `ctx.exports` property provides access to the exports of the main (`SELF`) Worker. The Workers Vitest integration attempts to automatically infer these exports by statically analyzing the Worker source code using esbuild. However, complex build setups, such as those using virtual modules or wildcard re-exports that esbuild cannot follow, may result in missing properties on the `ctx.exports` object.
+
+For example, consider a Worker that re-exports an entrypoint from a virtual module using a wildcard export:
+
+```ts
+// index.ts
+export * from "@virtual-module";
+```
+
+In this case, any exports from `@virtual-module` (such as `MyEntrypoint`) cannot be automatically inferred and will be missing from `ctx.exports`.
+
+To work around this, add the `additionalExports` option to your Vitest configuration:
+
+```ts
+import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";
+
+export default defineWorkersConfig({
+	test: {
+		poolOptions: {
+			workers: {
+				wrangler: { configPath: "./wrangler.toml" },
+				additionalExports: {
+					MyEntrypoint: "WorkerEntrypoint",
+				},
+			},
+		},
+	},
+});
+```
+
+The `additionalExports` option is a map where keys are the export names and values are the type of export (`"WorkerEntrypoint"`, `"DurableObject"`, or `"WorkflowEntrypoint"`).
+
 ### Module resolution
 
 If you encounter module resolution issues such as: `Error: Cannot use require() to import an ES Module` or `Error: No such module`, you can bundle these dependencies using the [deps.optimizer](https://vitest.dev/config/#deps-optimizer) option:
diff --git a/src/content/docs/workers/testing/vitest-integration/recipes.mdx b/src/content/docs/workers/testing/vitest-integration/recipes.mdx
@@ -24,6 +24,7 @@ Recipes are examples that help demonstrate how to write unit tests and integrati
 - [Tests using multiple auxiliary Workers and request mocks](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples/multiple-workers)
 - [Tests importing WebAssembly modules](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples/web-assembly)
 - [Tests using JSRPC with entrypoints and Durable Objects](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples/rpc)
+- [Tests using `ctx.exports` to access Worker exports](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples/context-exports)
 - [Integration test with static assets and Puppeteer](https://github.com/GregBrimble/puppeteer-vitest-workers-assets)
 - [Resolving modules with Vite Dependency Pre-Bundling](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples/module-resolution)
 - [Mocking Workers AI and Vectorize bindings in unit tests](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples/ai-vectorize)
