Skip to content

[workers] Update vitest getting started guide #21454

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 3 commits into from
Apr 8, 2025
Merged

[workers] Update vitest getting started guide #21454

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
91775a5
update write your first test
emily-shen Apr 7, 2025
b117c04
tidy up various overviews
emily-shen Apr 7, 2025
6b721d8
pr feedback
emily-shen Apr 7, 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
32 changes: 17 additions & 15 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,28 @@ 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 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/">
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 | ❌ | ✅ | ✅ |
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 | ❌ | ✅ | ✅ |

<Render file="testing-pages-functions" product="workers" />
27 changes: 3 additions & 24 deletions src/content/docs/workers/testing/vitest-integration/get-started/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,33 +3,12 @@ pcx_content_type: navigation
title: Get started
sidebar:
order: 1
group:
hideIndex: true
Copy link
Member

@edmundhung edmundhung Apr 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like most of this pages is moved to the overview of the vitest-integration. Should we redirect people to the overview page instead of keeping a duplicate here?

Copy link
Contributor Author

@emily-shen emily-shen Apr 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i think you need an index.mdx at every level, so we can't get rid of it entirely, just hide it like this. Would love to though if you know how!

I also plan to move some pages around so its not so nested, but that PR was getting super confusing to review so i'm going to do content updates here first, then move pages around.

head: []
description: Install and set up the Workers Vitest integration.

---

import { DirectoryListing } from "~/components"

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. In this integration, Cloudflare provides a custom pool that allows your Vitest tests to run *inside* the Workers runtime.

The Workers Vitest integration:

* Supports both **unit tests** and **integration tests**.
* Provides direct access to Workers runtime APIs and bindings.
* Implements isolated per-test storage.
* Runs tests fully-locally using [Miniflare](https://miniflare.dev/).
* Leverages Vitest's hot-module reloading for near instant reruns.
* Provides a declarative interface for mocking outbound requests.
* Supports projects with multiple Workers.

Get started with one of the available guides:
import { DirectoryListing } from "~/components";

<DirectoryListing />

:::caution


The Workers Vitest integration does not support testing Workers using the service worker format. [Migrate to the ES modules format](/workers/reference/migrate-to-module-workers/) to use the Workers Vitest integration.


:::
Loading
Loading