Local development and testing
Cloudflare Workers can be fully developed and tested locally - providing confidence that the applications you develop locally work the same way in production. This allows you to be more efficient and effective by providing a faster feedback loop and removing the need to test against remote resources. Local development runs against the same production runtime used by Cloudflare Workers, workerd.
In addition to testing Workers locally with wrangler dev
, the use of Miniflare allows you to test other Developer Platform products locally, such as R2, KV, D1, and Durable Objects.
Start a local development server
Wrangler provides a dev
command that starts a local server for developing your Worker. Make sure you have npm
installed and run the following in the folder containing your Worker application:
$ npx wrangler dev
wrangler dev
will run the preview of the Worker directly on your local machine. wrangler dev
uses a combination of workerd
and Miniflare, a simulator that allows you to test your Worker against additional resources like KV, Durable Objects, WebSockets, and more. Resources such as KV, Durable Objects, D1, and R2 will be stored and persisted locally and not affect live production or preview data.
Develop locally using remote resources and bindings
wrangler dev
runs locally by default. This means that all resources and bindings are simulated locally as well. However, there may be times you need to develop against remote resources and bindings. To run wrangler dev
remotely, add the --remote
flag:
$ npx wrangler dev --remote
Remote resources to use during wrangler dev --remote
are specified with preview ID/names such as preview_id
or preview_bucket name
. Preview resources can be resources separate from production resources to prevent changing production data in development. wrangler dev --remote
only supports preview ID/names for storage resources such as KV, R2, and D1. To change production data in wrangler dev --remote
, set the preview ID/name of the resource to the ID/name of the production resource.
Customize wrangler dev
You can customize how wrangler dev
works to fit your needs. Refer to the wrangler dev
documentation for available configuration options.
DevTools
Wrangler supports using the Chrome DevTools to view logs/sources, set breakpoints, and profile CPU/memory usage. With wrangler dev
running, press the d key in your terminal to open a DevTools session connected to your Worker from any Chromium-based browser.
Debug via breakpoints
As of Wrangler 3.9.0, you can debug via breakpoints in your Worker. Breakpoints provide the ability to see exactly what is happening at a given point in the execution of your Worker. This functionality exists in both DevTools and VS Code.
For more information on breakpoint debugging via Chrome’s DevTools, refer to Chrome’s article on breakpoints.
Setup VS Code to use breakpoints
To setup VS Code for breakpoint debugging Workers:
- Create a
.vscode
folder in your project’s root folder if one does not exist. - Within that folder, create a
launch.json
file with the following content:
{ "configurations": [ { "name": "Wrangler", "type": "node", "request": "attach", "port": 9229, "cwd": "/", "resolveSourceMapLocations": null, "attachExistingChildren": false, "autoAttachChildProcesses": false, "sourceMaps": true // works with or without this line } ]
}
Open your project in VS Code, open a new terminal window from VS Code, and run
npx wrangler dev
to start the local dev server.At the top of the Run & Debug panel, you should see an option to select a configuration. Choose Wrangler, and select the play icon. You should see Wrangler: Remote Process [0] show up in the Call Stack panel on the left.
Go back to a
.js
or.ts
file in your project and add at least one breakpoint.Open your browser and go to the Worker’s local URL (default
http://127.0.0.1:8787
). The breakpoint should be hit, and you should see details about your code at the specified line.
Test Workers
Integration testing
Wrangler offers an experimental API, unstable_dev
, that will allow you to start a server for integration testing.
For more information and examples, refer to the unstable_dev
guide.
Advanced local testing via Miniflare
Miniflare is a simulator for developing and testing Workers. It supports simulating and mocking resources like: KV, Durable Objects, R2, D1, and Queues.
Miniflare is fully local, and is built on top of the Workers runtime, workerd
to ensure that local behavior accurately reflects production. All of this makes it a great tool for writing tests or advanced use cases.
Related resources
- Log from Workers - Access logs and exceptions for your Workers using the dashboard or
wrangler tail
.