Skip to content

[workers] restructure workers testing docs #21127

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

Closed
wants to merge 1 commit into from
Closed

[workers] restructure workers testing docs #21127

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
34 changes: 17 additions & 17 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 @@ -7,26 +7,26 @@ sidebar:

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.
The Cloudflare Workers [Vitest integration](/workers/testing/vitest-integration) is the recommended way to test your applications, and allows for unit testing individual functions within your Worker or Pages Function.

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
Get started with Vitest
</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](/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 | ❌ | ✅ | ✅ |

<Render file="testing-pages-functions" product="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](/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 | ❌ | ✅ | ✅ |
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
19 changes: 11 additions & 8 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 @@ -8,7 +8,10 @@ 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.
For most users, Cloudflare recommends using the Workers Vitest integration for testing Workers and [Pages Functions](/pages/functions/) projects.

If you have been using the test environments from Miniflare 2 for integration testing and want to migrate to Cloudflare's Vitest integration, refer to the [Migrate from Miniflare 2 migration guide](/workers/testing/vitest-integration/get-started/migrate-from-miniflare-2/) for more information.

:::

import { TabItem, Tabs, Details } from "~/components";
Expand Down Expand Up @@ -98,13 +101,13 @@ The highlighted lines of the test file above demonstrate how to set up Miniflare
<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 is 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.
[`workerd`](https://github.com/cloudflare/workerd), which is why it is
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
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.

36 changes: 36 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,36 @@
---
title: unstable_startWorker()
pcx_content_type: concept
sidebar:
order: 17
head: []
description: Test multiple units of your Worker working together.
---

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

note: we recommend using vitest

## [Wrangler's `unstable_startWorker()` API](/workers/wrangler/api/#unstable_startworker)

:::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_startWorker } from "wrangler";

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.dispose();
}
```

<Render file="testing-pages-functions" product="workers" />
Loading
Loading