[Workers] Add docs for Vitest testing (#13092)

* workers: initial testing docs commit. add files for structure per ToC. * add page write your first test * add config and setup sections to first test doc. * add sample tests to first test guide. add first sentence to unstable dev guide. * update docs to reference vitest 1.3.0. add section for configuring via wrangler config. * Reorder table-of-contents * Add migration from Miniflare 2's testing environments page * Add testing options page * Add configuration page * Add test APIs page * Add internal details page * add migration docs for unstable_dev * remove testing section from local dev guide * add callouts for additional config info docs * add recipes for fetch events and scheduled events. * add advanced config and integration test examples. * Minor fixups to `migrate-from-miniflare-2.md` and `configuration.md` * Update content/workers/testing/vitest/get-started/migrate-from-unstable-dev.md Co-authored-by: MrBBot <[email protected]> * Update content/workers/testing/vitest/get-started/migrate-from-unstable-dev.md Co-authored-by: MrBBot <[email protected]> * Update content/workers/testing/vitest/get-started/write-your-first-test.md Co-authored-by: MrBBot <[email protected]> * Update content/workers/testing/vitest/get-started/write-your-first-test.md Co-authored-by: MrBBot <[email protected]> * update unstable_dev migration guide per comments. update first test examples. * add npm command to install vitest 1.3.0 * move vitest into section about installing packages. add note about only 1.3.0 being supported. * Update content/workers/testing/vitest/get-started/write-your-first-test.md Co-authored-by: MrBBot <[email protected]> * Update content/workers/testing/vitest/get-started/write-your-first-test.md Co-authored-by: MrBBot <[email protected]> * Add isolation model diagrams to internal details page * More minor fixups to `configuration.md` * remove recipe examples. add links to fixtures folder. * add compat date and flag to prereqs * Replace `Vitest pool` with `Vitest integration` * Update `configuration.md` in response to review * Update `migrate-from-miniflare-2.md` in response to review * Update `internal-details.md` in response to review * Update `test-apis.md` in response to review * fixup! Update `configuration.md` in response to review * update testing section structure. add pages for unit and integration testing. add section for local binding support. * update testing section description * add description for vitest integration * add vitest integration description * update docs to reflect api changes for defineWorkersConfig * add more info about SELF and auxiliary Workers * Apply suggestions from code review Style guide fixes * PCX review test * Apply suggestions from code review Minor style guide edits * Apply suggestions from code review minor style guide fixes * PCX review for write your first test and isolation * Apply suggestions from code review Co-authored-by: Kate Tungusova <[email protected]> * update api code blocks. add recipe links. * add partial to reference pages functions. add partial to relevant pages. * add auxiliary worker glossary term. update integration testing page. * Apply more suggestions from code review * Minor fixups * Add known issues * edit first test examples to match c3 * Fix broken links * Replace `we` with `Cloudflare` per style guide --------- Co-authored-by: bcoll <[email protected]> Co-authored-by: MrBBot <[email protected]> Co-authored-by: Kate Tungusova <[email protected]> Co-authored-by: Kate Tungusova <[email protected]>
cloudflare · Mar 14, 2024 · 652c33a · 652c33a
1 parent 45fe633
commit 652c33a
Show file tree

Hide file tree

Showing 31 changed files with 1,865 additions and 153 deletions.
diff --git a/...rkers/testing/vitest/isolation-model-1-no-isolated-storage-no-single-worker.svg b/...rkers/testing/vitest/isolation-model-1-no-isolated-storage-no-single-worker.svg
diff --git a/.../workers/testing/vitest/isolation-model-2-no-isolated-storage-single-worker.svg b/.../workers/testing/vitest/isolation-model-2-no-isolated-storage-single-worker.svg
diff --git a/.../workers/testing/vitest/isolation-model-3-isolated-storage-no-single-worker.svg b/.../workers/testing/vitest/isolation-model-3-isolated-storage-no-single-worker.svg
diff --git a/...ges/workers/testing/vitest/isolation-model-4-isolated-storage-single-worker.svg b/...ges/workers/testing/vitest/isolation-model-4-isolated-storage-single-worker.svg
diff --git a/components/CodeCopy.vue b/components/CodeCopy.vue
@@ -88,6 +88,7 @@ function copyCode(e: MouseEvent) {
   width: 2rem;
   font-size: 0.9rem;
   padding: 0.5rem;
+  box-sizing: border-box;
   background: #d9d9d9;
   color: #1e1e1e;
   border: none;

diff --git a/content/_redirects b/content/_redirects
@@ -1274,6 +1274,7 @@
 /workers/runtime-apis/mtls/ /workers/runtime-apis/bindings/mtls/ 301
 /workers/runtime-apis/queues/ /workers/runtime-apis/bindings/bindings/queues/ 301
 /workers/runtime-apis/service-bindings/ /workers/runtime-apis/bindings/service-bindings/ 301
+/workers/observability/local-development-and-testing/ /workers/testing/local-development/ 301
 
 # workers ai
 /workers-ai/models/llm/ /workers-ai/models/#text-generation 301

diff --git a/content/d1/observability/debug-d1.md b/content/d1/observability/debug-d1.md
@@ -10,7 +10,7 @@ D1 allows you to capture exceptions and log errors returned when querying a data
 
 ## Handle errors
 
-The D1 [client API](/d1/build-databases/query-databases/) returns detailed [error messages](/d1/build-databases/query-databases/#errors) within an `Error` object. 
+The D1 [client API](/d1/build-databases/query-databases/) returns detailed [error messages](/d1/build-databases/query-databases/#errors) within an `Error` object.
 
 To ensure you are capturing the full error message, log or return `e.message` as follows:
 
@@ -56,4 +56,4 @@ You should include as much of the following in any bug report:
 
 * Learn [how to debug Workers](/workers/observability/).
 * Understand how to [access logs](/workers/observability/logging/) generated from your Worker and D1.
-* Use [`wrangler dev`](/workers/wrangler/commands/#dev) to run your Worker and D1 locally and [debug issues before deploying](/workers/observability/local-development-and-testing/).
+* Use [`wrangler dev`](/workers/wrangler/commands/#dev) to run your Worker and D1 locally and [debug issues before deploying](/workers/testing/local-development/).
diff --git a/content/learning-paths/workers/test/intro-to-observability.md b/content/learning-paths/workers/test/intro-to-observability.md
@@ -13,7 +13,7 @@ To explore observability, debugging and testing options for Workers, refer to [O
 
 ### Local development
 
-Refer to [Local development and testing](/workers/observability/local-development-and-testing/) to learn how to test your Worker locally with `wrangler dev`.
+Refer to [Local development and testing](/workers/testing/local-development/) to learn how to test your Worker locally with `wrangler dev`.
 
 ### Logs
 

diff --git a/content/workers/_partials/_testing-pages-functions.md b/content/workers/_partials/_testing-pages-functions.md
@@ -0,0 +1,12 @@
+---
+_build:
+  publishResources: false
+  render: never
+  list: never
+---
+
+{{<Aside type="note" header="Pages Functions">}}
+
+The content described on this page is also applicable to [Pages Functions](/pages/functions/). Pages Functions are Cloudflare Workers and can be thought of synonymously with Workers in this context.
+
+{{</Aside>}}
diff --git a/content/workers/observability/_index.md b/content/workers/observability/_index.md
@@ -1,11 +1,11 @@
 ---
 pcx_content_type: navigation
 title: Observability
-weight: 9
+weight: 10
 ---
 
 # Observability
 
-Test and debug your Worker projects.
+Understand how your Worker projects are performing via logs, traces, and other data sources.
 
 {{<directory-listing showDescriptions="true">}}
diff --git a/content/workers/observability/local-development-and-testing.md b/content/workers/observability/local-development-and-testing.md
diff --git a/content/workers/observability/logging/real-time-logs.md b/content/workers/observability/logging/real-time-logs.md
@@ -74,7 +74,7 @@ To view real-time logs associated with any deployed Worker using the Cloudflare
 
 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
 2. In Account Home, go to **Workers & Pages**.
-3. In **Overview**, select your **Worker** > and select **Logs**. 
+3. In **Overview**, select your **Worker** > and select **Logs**.
 
 
 ## View logs using `wrangler tail`
@@ -151,6 +151,6 @@ Refer to the [Tail Workers documentation](/workers/observability/logging/tail-wo
 ## Related resources
 
 * [Errors and exceptions](/workers/observability/errors/) - Review common Workers errors.
-* [Local development and testing](/workers/observability/local-development-and-testing/) - Develop and test you Workers locally.
+* [Local development and testing](/workers/testing/local-development/) - Develop and test you Workers locally.
 * [Logpush](/workers/observability/logging/logpush/) - Learn how to push Workers Trace Event Logs to supported destinations.
 * [Tail Workers](/workers/observability/logging/logpush/) - Learn how to attach Tail Workers to transform your logs and send them to HTTP endpoints.
diff --git a/content/workers/testing/_index.md b/content/workers/testing/_index.md
@@ -0,0 +1,31 @@
+---
+pcx_content_type: navigation
+title: Testing
+weight: 9
+---
+
+# Testing
+
+Review the tools available for testing and debugging Workers.
+
+{{<directory-listing showDescriptions="true">}}
+
+## Testing comparison matrix
+
+| Feature                                   | Vitest&nbsp;Pool | `unstable_dev()` | Miniflare's&nbsp;API |
+| ----------------------------------------- | ---------------- | ---------------- | -------------------- |
+| Unit testing                              | ✅               | ❌               | ❌                   |
+| Integration testing                       | ✅               | ✅               | ✅                   |
+| Loading Wrangler configuration files      | ✅               | ✅               | ❌                   |
+| Bindings directly in tests                | ✅               | ❌               | ✅                   |
+| Isolated per-test storage                 | ✅               | ❌               | ❌                   |
+| Outbound request mocking                  | ✅               | ❌               | ✅                   |
+| Multiple Worker support                   | ✅               | 🚧[^1]           | ✅                   |
+| Direct access to Durable Object instances | ✅               | ❌               | ❌                   |
+| Run Durable Object alarms immediately     | ✅               | ❌               | ❌                   |
+| List Durable Objects                      | ✅               | ❌               | ❌                   |
+| Testing service Workers                   | ❌               | ✅               | ✅                   |
+
+[^1]: Support for multiple Workers in [`unstable_dev()`](/workers/wrangler/api/#unstable_dev) relies on `wrangler dev`'s service registry which can be unreliable when running multiple tests in parallel.
+
+{{<render file="_testing-pages-functions.md" productFolder="workers">}}
diff --git a/content/workers/testing/debugging-tools.md b/content/workers/testing/debugging-tools.md
@@ -0,0 +1,72 @@
+---
+title: Debugging tools
+weight: 4
+pcx_content_type: concept
+meta:
+  description: Debug your local and deployed Workers using a variety of tools.
+---
+
+# Debugging tools
+
+Being able to assess how your Workers are functioning at various points in the development cycle is vital to identifying the root causes of bugs or issues.
+
+Cloudflare provides a variety of tools to help you debug your Workers.
+
+## Chrome DevTools
+
+Wrangler supports using [Chrome DevTools](https://developer.chrome.com/docs/devtools/) to view logs/sources, set breakpoints, and profile CPU/memory usage. To open a DevTools session connected to your Worker from any Chromium-based browser, run [`wrangler dev`](/workers/wrangler/commands/#dev) and press the <kbd>d</kbd> key in your terminal.
+
+## Debug via breakpoints
+
+As of Wrangler 3.9.0, you can debug via breakpoints in your Worker. Breakpoints provide the ability to review what is happening at a given point in the execution of your Worker. Breakpoint functionality exists in both DevTools and VS Code.
+
+For more information on breakpoint debugging via Chrome's DevTools, refer to [Chrome's article on breakpoints](https://developer.chrome.com/docs/devtools/javascript/breakpoints/).
+
+### Setup VS Code to use breakpoints
+
+To setup VS Code for breakpoint debugging in your Worker project:
+
+1. Create a `.vscode` folder in your project's root folder if one does not exist.
+2. Within that folder, create a `launch.json` file with the following content:
+
+```json
+{
+  "configurations": [
+      {
+          "name": "Wrangler",
+          "type": "node",
+          "request": "attach",
+          "port": 9229,
+          "cwd": "/",
+          "resolveSourceMapLocations": null,
+          "attachExistingChildren": false,
+          "autoAttachChildProcesses": false,
+          "sourceMaps": true // works with or without this line
+      }
+  ]
+}
+```
+
+3. Open your project in VS Code, open a new terminal window from VS Code, and run `npx wrangler dev` to start the local dev server.
+
+4. At the top of the **Run & Debug** panel, you should see an option to select a configuration. Choose **Wrangler**, and select the play icon. **Wrangler: Remote Process [0]** should show up in the Call Stack panel on the left.
+
+5. Go back to a `.js` or `.ts` file in your project and add at least one breakpoint.
+
+5. Open your browser and go to the Worker's local URL (default `http://127.0.0.1:8787`). The breakpoint should be hit, and you should be able to review details about your code at the specified line.
+
+{{<Aside type="warning">}}
+
+Breakpoint debugging in `wrangler dev` using `--remote` could extend Worker CPU time and incur additional costs since you are testing against actual resources that count against usage limits. It is recommended to use `wrangler dev` without the `--remote` option. This ensures you are developing locally.
+
+{{</Aside>}}
+
+{{<Aside type="note">}}
+
+The `.vscode/launch.json` file only applies to a single workspace. If you prefer, you can add the above launch configuration to your User Settings (per the [official VS Code documentation](https://code.visualstudio.com/docs/editor/debugging#_global-launch-configuration)) to have it available for all your workspaces.
+
+{{</Aside>}}
+
+## Related resources
+
+* [Local Development](/workers/testing/local-development/) - Develop your Workers and connected resources locally via Wrangler and [`workerd`](https://github.com/cloudflare/workerd), for a fast, accurate feedback loop.