address comments

penalosa · penalosa · commit bf3abd8d9a20 · 2025-01-31T17:36:38.000Z
diff --git a/src/content/docs/workers/testing/index.mdx b/src/content/docs/workers/testing/index.mdx
@@ -9,26 +9,24 @@ import { Render, LinkButton } from "~/components";
 
 The Workers platform has a variety of ways to test your applications, depending on your requirements. We recommend using the [Vitest integration](/workers/testing/vitest-integration), which allows for unit testing individual functions within your Worker. However, if you don't use Vitest, both [Miniflare's API](/workers/testing/miniflare/writing-tests) and the [`unstable_startWorker()`](/workers/wrangler/api/#unstable_startworker) API provide options for testing your Worker in any testing framework.
 
-
 <LinkButton href="/workers/testing/vitest-integration/get-started/write-your-first-test/">
 	Write your first test
 </LinkButton>
 
-
 ## Testing comparison matrix
 
-| Feature                                   | [Vitest integration](/workers/testing/vitest-integration) | [`unstable_startWorker()`](/workers/wrangler/api/#unstable_startworker) | [Miniflare's API](/workers/testing/miniflare) |
-| ----------------------------------------- | ----------- | ---------------- | --------------- |
-| Unit testing                              | ✅          | ❌               | ❌              |
-| Integration testing                       | ✅          | ✅               | ✅              |
-| Loading Wrangler configuration files      | ✅          | ✅               | ❌              |
-| Bindings directly in tests                | ✅          | ❌               | ✅              |
-| Isolated per-test storage                 | ✅          | ❌               | ❌              |
-| Outbound request mocking                  | ✅          | ❌               | ✅              |
-| Multiple Worker support                   | ✅          | ✅               | ✅              |
-| Direct access to Durable Objects          | ✅          | ❌               | ❌              |
-| Run Durable Object alarms immediately     | ✅          | ❌               | ❌              |
-| List Durable Objects                      | ✅          | ❌               | ❌              |
-| Testing service Workers                   | ❌          | ✅               | ✅              |
+| Feature                               | [Vitest integration](/workers/testing/vitest-integration) | [`unstable_startWorker()`](/workers/wrangler/api/#unstable_startworker) | [Miniflare's API](/workers/testing/miniflare) |
+| ------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------- |
+| Unit testing                          | ✅                                                        | ❌                                                                      | ❌                                            |
+| Integration testing                   | ✅                                                        | ✅                                                                      | ✅                                            |
+| Loading Wrangler configuration files  | ✅                                                        | ✅                                                                      | ❌                                            |
+| Use bindings directly in tests        | ✅                                                        | ❌                                                                      | ✅                                            |
+| Isolated per-test storage             | ✅                                                        | ❌                                                                      | ❌                                            |
+| Outbound request mocking              | ✅                                                        | ❌                                                                      | ✅                                            |
+| Multiple Worker support               | ✅                                                        | ✅                                                                      | ✅                                            |
+| Direct access to Durable Objects      | ✅                                                        | ❌                                                                      | ❌                                            |
+| Run Durable Object alarms immediately | ✅                                                        | ❌                                                                      | ❌                                            |
+| List Durable Objects                  | ✅                                                        | ❌                                                                      | ❌                                            |
+| Testing service Workers               | ❌                                                        | ✅                                                                      | ✅                                            |
 
 <Render file="testing-pages-functions" product="workers" />
diff --git a/src/content/docs/workers/testing/integration-testing.mdx b/src/content/docs/workers/testing/integration-testing.mdx
@@ -8,6 +8,7 @@ description: Test multiple units of your Worker working together.
 ---
 
 import { Render } from "~/components";
+import { LinkButton } from "@astrojs/starlight/components";
 
 Integration tests test multiple units of your Worker together by sending HTTP requests to your Worker and asserting on the HTTP responses. As an example, consider the following Worker:
 
@@ -84,32 +85,30 @@ This method is less recommended than `SELF` for integration tests because of its
 
 :::
 
-## Wrangler's `unstable_dev()` API
+## [Wrangler's `unstable_startWorker()` API](/workers/wrangler/api/#unstable_startworker)
 
-If you do not want to use Vitest and would like to write integration tests for a single Worker, consider using [Wrangler's `unstable_dev()` API](/workers/wrangler/api/#unstable_dev). `unstable_dev()` allows you to start an HTTP server similar to [`wrangler dev`](/workers/wrangler/commands/#dev) that you can send HTTP requests to. `unstable_dev()` will automatically load options from your Wrangler configuration file. Note that `unstable_dev()` is an experimental API subject to breaking changes.
+:::caution
+`unstable_startWorker()` is an experimental API subject to breaking changes.
+:::
+
+If you do not want to use Vitest and would like to write integration tests for a single Worker, consider using [Wrangler's `unstable_startWorker()` API](/workers/wrangler/api/#unstable_startworker). This API exposes the internals of Wrangler's dev server, and allows you to customise how it runs.
 
 ```js
 import assert from "node:assert";
-import { unstable_dev } from "wrangler";
+import { unstable_startWorker } from "wrangler";
 
-const worker = await unstable_dev("./index.mjs");
+const worker = await unstable_startWorker({ config: "wrangler.json" });
 try {
 	const response = await worker.fetch("/?a=1&b=2");
 	assert.strictEqual(await response.text(), "3");
 } finally {
-	await worker.stop();
+	await worker.dispose();
 }
 ```
 
-:::note
-
-If you have been using `unstable_dev()` for integration testing and want to migrate to Cloudflare's Vitest integration, refer to the [Migrate from `unstable_dev` migration guide](/workers/testing/vitest-integration/get-started/migrate-from-unstable-dev/) for more information.
-
-:::
-
-## Miniflare's API
+## [Miniflare's API](/workers/testing/miniflare/writing-tests/)
 
-If you would like to write integration tests for multiple Workers, need direct access to [bindings](/workers/runtime-apis/bindings/) outside your Worker in tests, or have another advanced use case, consider using [Miniflare's API](/workers/testing/miniflare) directly. Miniflare is the foundation for the other testing tools on this page, exposing a JavaScript API for the [`workerd` runtime](https://github.com/cloudflare/workerd) and local simulators for the other Developer Platform products. Unlike `unstable_dev()`, Miniflare does not automatically load options from your Wrangler configuration file.
+If you would like to write integration tests for multiple Workers, need direct access to [bindings](/workers/runtime-apis/bindings/) outside your Worker in tests, or have another advanced use case, consider using [Miniflare's API](/workers/testing/miniflare) directly. Miniflare is the foundation for the other testing tools on this page, exposing a JavaScript API for the [`workerd` runtime](https://github.com/cloudflare/workerd) and local simulators for the other Developer Platform products. Unlike `unstable_startWorker()`, Miniflare does not automatically load options from your Wrangler configuration file. Refer to the [Writing Tests](/workers/testing/miniflare/writing-tests/) page for an example of how to use Miniflare together with `node:test`.
 
 ```js
 import assert from "node:assert";
diff --git a/src/content/docs/workers/testing/miniflare/writing-tests.mdx b/src/content/docs/workers/testing/miniflare/writing-tests.mdx
@@ -13,7 +13,7 @@ For most users, Cloudflare recommends using the Workers Vitest integration for t
 
 import { TabItem, Tabs, Details } from "~/components";
 
-import { FileTree } from '@astrojs/starlight/components';
+import { FileTree } from "@astrojs/starlight/components";
 
 This guide will instruct you through setting up [Miniflare](/workers/testing/miniflare) for testing your Workers. Miniflare is a low-level API that allows you to fully control how your Workers are run and tested.
 
@@ -81,7 +81,7 @@ describe("worker", () => {
 	test("hello world", async () => {
 		assert.strictEqual(
 			await (await worker.dispatchFetch("http://example.com")).text(),
-			"Hello World"
+			"Hello World",
 		);
 	});
 
@@ -96,11 +96,25 @@ You should be able to run the above test via `node --test`
 The highlighted lines of the test file above demonstrate how to set up Miniflare to run a JavaScript Worker. Once Miniflare has been set up, your individual tests can send requests to the running Worker and assert against the responses. This is the main limitation of using Miniflare for testing your Worker as compared to the [Vitest integration](/workers/testing/vitest-integration/)—all access to your Worker must be through the `dispatchFetch()` Miniflare API, and you cannot unit test individual functions from your Worker.
 
 <Details header="What runtime are tests running in?">
-When using the [Vitest integration](/workers/testing/vitest-integration/), your entire test suite runs in [`workerd`](https://github.com/cloudflare/workerd), which is why it's possible to unit test individual functions. By contrast, when using a different testing framework to run tests via Miniflare, only your Worker itself is running in [`workerd`](https://github.com/cloudflare/workerd)—your test files run in Node.js. This means that importing functions from your Worker into your test files might exhibit different behaviour than you'd see at runtime if the functions rely on `workerd`-specific behaviour.
+	When using the [Vitest integration](/workers/testing/vitest-integration/),
+	your entire test suite runs in
+	[`workerd`](https://github.com/cloudflare/workerd), which is why it's possible
+	to unit test individual functions. By contrast, when using a different testing
+	framework to run tests via Miniflare, only your Worker itself is running in
+	[`workerd`](https://github.com/cloudflare/workerd)—your test files run in
+	Node.js. This means that importing functions from your Worker into your test
+	files might exhibit different behaviour than you'd see at runtime if the
+	functions rely on `workerd`-specific behaviour.
 </Details>
 
 ## Interacting with Bindings
 
+:::caution
+
+Miniflare does not read [Wrangler's config file](/workers/wrangler/configuration), and so all bindings that your Worker uses need to be specified in the Miniflare API options.
+
+:::
+
 The `dispatchFetch()` API from Miniflare allows you to send requests to your Worker and assert that the correct response is returned, but sometimes you need to interact directly with bindings in tests. For use cases like that, Miniflare provides the [`getBindings()`](/workers/testing/miniflare/get-started/#reference) API. For instance, to access an environment variable in your tests, adapt the test file `src/index.test.js` as follows:
 
 ```diff lang="js" title="src/index.test.js"
@@ -127,7 +141,6 @@ describe("worker", () => {
 
 You can also interact with local resources such as KV and R2, using the same API as you would from a Worker. For example, here's how you would interact with a KV namespace:
 
-
 ```diff lang="js" title="src/index.test.js"
 ...
 describe("worker", () => {
@@ -168,7 +181,7 @@ new Miniflare({
 });
 ```
 
-This can be a bit cumbersome as your Worker grows. To help with thi, Miniflare can also crawl your module graph to automatically figure out which modules to include:
+This can be a bit cumbersome as your Worker grows. To help with this, Miniflare can also crawl your module graph to automatically figure out which modules to include:
 
 ```js
 new Miniflare({
@@ -190,7 +203,3 @@ before(() => {
 	});
 });
 ```
-
-
-
-
diff --git a/src/content/docs/workers/wrangler/api.mdx b/src/content/docs/workers/wrangler/api.mdx
@@ -35,7 +35,7 @@ describe("worker", () => {
 	test("hello world", async () => {
 		assert.strictEqual(
 			await (await worker.fetch("http://example.com")).text(),
-			"Hello world"
+			"Hello world",
 		);
 	});
 
@@ -45,8 +45,6 @@ describe("worker", () => {
 });
 ```
 
-
-
 ## `unstable_dev`
 
 Start an HTTP server for testing your Worker.
@@ -61,6 +59,8 @@ The `unstable_dev()` function has an `unstable_` prefix because the API is exper
 
 `unstable_dev()` has no known bugs and is safe to use. If you discover any bugs, open a [GitHub issue](https://github.com/cloudflare/workers-sdk/issues/new/choose).
 
+If you have been using `unstable_dev()` for integration testing and want to migrate to Cloudflare's Vitest integration, refer to the [Migrate from `unstable_dev` migration guide](/workers/testing/vitest-integration/get-started/migrate-from-unstable-dev/) for more information.
+
 :::
 
 ### Constructor
@@ -374,8 +374,6 @@ The bindings supported by `getPlatformProxy` are:
 
     For example, you might have the following file read by `getPlatformProxy`.
 
-
-
     <WranglerConfig>
 
     ```toml
