docs(vitest-integrations): debugging guide

Author: edmundhung

src/content/docs/workers/testing/vitest-integration/debugging.mdx

@@ -0,0 +1,80 @@
+---
+title: Debugging
+pcx_content_type: concept
+sidebar:
+  order: 8
+head: []
+description: Debug your Workers tests with Vitest.
+---
+
+Starting with `@cloudflare/vitest-pool-workers` v0.7.5, you can now debug your Workers tests with Vitest.
+
+## Open inspector with Vitest
+
+To start debugging, run Vitest with the following command and attach a debugger to port `9229`:
+
+```sh
+vitest --inspect --no-file-parallelism
+```
+
+## Customizing the inspector port
+
+By default, the inspector will be opened on port `9229`. If you need to use a different port (e.g. `3456`), you can run the following command:
+
+```sh
+vitest --inspect=3456 --no-file-parallelism
+```
+
+or define it in your Vitest configuration file:
+
+```ts
+import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";
+
+export default defineWorkersConfig({
+  test: {
+    inspector: {
+        port: 3456,
+    },
+    poolOptions: {
+      workers: {
+        // ...
+      },
+    },
+  },
+});
+```
+
+## Setup VS Code to use breakpoints
+
+To setup VS Code for breakpoint debugging in your Worker tests, you can create a `.vscode/launch.json` file that contains the following configuration:
+
+```json
+{
+    "configurations": [
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "Open inspector with Vitest",
+            "program": "${workspaceRoot}/node_modules/vitest/vitest.mjs",
+            "console": "integratedTerminal",
+            "args": ["--inspect=9229", "--no-file-parallelism"]
+        },
+        {
+            "name": "Attach to Workers Runtime",
+            "type": "node",
+            "request": "attach",
+            "port": 9229,
+            "cwd": "/"
+        }
+    ],
+    "compounds": [
+        {
+            "name": "Debug Workers tests",
+            "configurations": ["Open inspector with Vitest", "Attach to Workers Runtime"],
+            "stopAll": true
+        }
+    ]
+}
+```
+
+You will find the **Debug Workers tests** option at the top of the **Run & Debug** panel. This will open inspector with Vitest and attach a debugger to the Workers runtime. You can then add breakpoints to your test files and start debugging.