Skip to content

[workers] restructure testing docs #21560

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Apr 10, 2025
Merged

[workers] restructure testing docs #21560

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
b6393fd
flatten
emily-shen Apr 9, 2025
ccba31a
change integration-testing.mdx to unstable startworker
emily-shen Apr 9, 2025
fff4cae
redirects
emily-shen Apr 9, 2025
cd99a41
fixup
emily-shen Apr 9, 2025
a88ab00
remove duplicated redirect
emily-shen Apr 10, 2025
06c6f67
pr feedback
emily-shen Apr 10, 2025
0fcddf5
fix links
emily-shen Apr 10, 2025
7561d3d
capitalisation
emily-shen Apr 10, 2025
dadd35a
more invalid links
emily-shen Apr 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions public/__redirects
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1529,6 +1529,13 @@
/workers/tutorials/generate-dynamic-og-images-using-workers/ /workers/tutorials/ 302
/workers/static-assets/compatibility-matrix/ /workers/static-assets/migrate-from-pages/ 301
/workers/frameworks/framework-guides/remix/ /workers/frameworks/framework-guides/react-router/ 301
/workers/testing/unit-testing/ /workers/testing/vitest-integration/write-your-first-test/ 301
/workers/testing/integration-testing/ /workers/testing/ 301
/workers/testing/integration-testing/ /workers/testing/ 301
/workers/testing/vitest-integration/get-started/ /workers/testing/vitest-integration/write-your-first-test/ 301
/workers/testing/vitest-integration/get-started/migrate-from-miniflare-2/ /workers/testing/vitest-integration/migration-guides/migrate-from-miniflare-2/ 301
/workers/testing/vitest-integration/get-started/migrate-from-unstable-dev/ /workers/testing/vitest-integration/migration-guides/migrate-from-unstable-dev/ 301
/workers/testing/vitest-integration/get-started/write-your-first-test/ /workers/testing/vitest-integration/write-your-first-test/ 301

# workers ai
/workers-ai/models/llm/ /workers-ai/models/#text-generation 301
Expand Down
26 changes: 13 additions & 13 deletions src/content/docs/workers/testing/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,18 +17,18 @@ The Workers platform has a variety of ways to test your applications, depending

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.

| 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](/workers/wrangler/configuration/) | ✅ | ✅ | ❌ |
| 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 | ❌ | ✅ | ✅ |
| Feature | [Vitest integration](/workers/testing/vitest-integration) | [`unstable_startWorker()`](/workers/testing/unstable_startworker/) | [Miniflare's API](/workers/testing/miniflare/writing-tests/) |
| ------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------ |
| 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" />
139 changes: 0 additions & 139 deletions src/content/docs/workers/testing/integration-testing.mdx
View file
Open in desktop

This file was deleted.

2 changes: 1 addition & 1 deletion src/content/docs/workers/testing/miniflare/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Miniflare
pcx_content_type: navigation
sidebar:
order: 15
order: 16
head:
- tag: title
content: miniflare
Expand Down
8 changes: 4 additions & 4 deletions src/content/docs/workers/testing/miniflare/writing-tests.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,14 @@ head: []
description: Write integration tests against Workers using Miniflare.
---

:::note
For most users, Cloudflare recommends using the Workers Vitest integration for testing Workers and [Pages Functions](/pages/functions/) projects. [Vitest](https://vitest.dev/) is a popular JavaScript testing framework featuring a very fast watch mode, Jest compatibility, and out-of-the-box support for TypeScript.
:::

import { TabItem, Tabs, Details } from "~/components";

import { FileTree } from "@astrojs/starlight/components";

:::note
For most users, Cloudflare recommends using the Workers Vitest integration. If you have been using test environments from Miniflare, refer to the [Migrate from Miniflare 2 guide](/workers/testing/vitest-integration/migration-guides/migrate-from-miniflare-2/).
:::

This guide will show you how to set up [Miniflare](/workers/testing/miniflare) to test your Workers. Miniflare is a low-level API that allows you to fully control how your Workers are run and tested.

To use Miniflare, make sure you've installed the latest version of Miniflare v3:
Expand Down
48 changes: 0 additions & 48 deletions src/content/docs/workers/testing/unit-testing.mdx
View file
Open in desktop

This file was deleted.

49 changes: 49 additions & 0 deletions src/content/docs/workers/testing/unstable_startworker.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
---
title: Wrangler's unstable_startWorker()
pcx_content_type: concept
sidebar:
order: 17
head: []
description: Write integration tests using Wrangler's `unstable_startWorker()` API
---

import { Render } from "~/components";
import { LinkButton } from "@astrojs/starlight/components";

:::note
For most users, Cloudflare recommends using the Workers Vitest integration. If you have been using `unstable_dev()`, refer to the [Migrate from `unstable_dev()` guide](/workers/testing/vitest-integration/migration-guides/migrate-from-unstable-dev/).
:::

:::caution
`unstable_startWorker()` is an experimental API subject to breaking changes.
:::

If you do not want to use Vitest, 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. Compared to using [Miniflare directly](/workers/testing/miniflare/writing-tests/) for testing, you can pass in a Wrangler configuration file, and it will automatically load the configuration for you.

This example uses `node:test`, but should apply to any testing framework:

```ts
import assert from "node:assert";
import test, { after, before, describe } from "node:test";
import { unstable_startWorker } from "wrangler";

describe("worker", () => {
let worker;

before(async () => {
worker = await unstable_startWorker({ config: "wrangler.json" });
});

test("hello world", async () => {
assert.strictEqual(
await (await worker.fetch("http://example.com")).text(),
"Hello world",
);
});

after(async () => {
await worker.dispose();
});
});

```
Loading
Loading