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 all 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
6 changes: 6 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,12 @@
/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/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
2 changes: 1 addition & 1 deletion src/content/docs/agents/getting-started/testing-your-agent.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ $ npx vitest
Test Files 1 passed (1)
```

Review the [documentation on testing](/workers/testing/vitest-integration/get-started/write-your-first-test/) for additional examples and test configuration.
Review the [documentation on testing](/workers/testing/vitest-integration/write-your-first-test/) for additional examples and test configuration.

## Running Agents locally

Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/workers/observability/source-maps.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ When `upload_source_maps` is set to `true`, Wrangler will automatically generate

:::note

Miniflare can also [output source maps](https://miniflare.dev/developing/source-maps) for use in local development or [testing](/workers/testing/integration-testing/#miniflares-api).
Miniflare can also [output source maps](https://miniflare.dev/developing/source-maps) for use in local development or [testing](/workers/testing/miniflare/writing-tests).

:::

Expand Down
28 changes: 14 additions & 14 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 @@ -9,26 +9,26 @@ 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 you to run tests to _inside_ the Workers runtime, and unit test individual functions within your Worker.

<LinkButton href="/workers/testing/vitest-integration/get-started/write-your-first-test/">
<LinkButton href="/workers/testing/vitest-integration/write-your-first-test/">
Get started with Vitest
</LinkButton>

## Testing comparison matrix

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.

6 changes: 5 additions & 1 deletion src/content/docs/workers/testing/miniflare/core/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,10 @@
---
title: Core
order: 2

sidebar:
order: 4
group:
hideIndex: true
---

import { DirectoryListing } from "~/components";
Expand Down
6 changes: 5 additions & 1 deletion src/content/docs/workers/testing/miniflare/developing/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
---
order: 4
sidebar:
order: 4
group:
hideIndex: true

title: "Developing"
---

Expand Down
3 changes: 2 additions & 1 deletion src/content/docs/workers/testing/miniflare/get-started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
---
order: 1
sidebar:
order: 2
title: Get Started
---

Expand Down
4 changes: 2 additions & 2 deletions 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,10 +2,10 @@
title: Miniflare
pcx_content_type: navigation
sidebar:
order: 15
order: 1
head:
- tag: title
content: miniflare
content: Miniflare
---

import { DirectoryListing, LinkButton } from "~/components";
Expand Down
1 change: 1 addition & 0 deletions src/content/docs/workers/testing/miniflare/migrations/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ head:
content: Migrations
description: Review migration guides for specific versions of Miniflare.
sidebar:
order: 5
group:
hideIndex: true
---
Expand Down
5 changes: 4 additions & 1 deletion src/content/docs/workers/testing/miniflare/storage/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
---
title: Storage
order: 2
sidebar:
order: 6
group:
hideIndex: true
---

import { DirectoryListing } from "~/components";
Expand Down
10 changes: 5 additions & 5 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 @@ -2,19 +2,19 @@
title: Writing tests
pcx_content_type: concept
sidebar:
order: 1
order: 3
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.

Loading
Loading