Cloudflare Docs
Workers
Cloudflare Docs
Workers
GitHub icon
Edit this page on GitHub
Set theme to dark (⇧+D)
  1. Products
  2. Workers
  3. Observability
  4. Local development and testing

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.

​​ Clear Wrangler’s local storage

Wrangler will store all locally created resources and storage in a .wrangler folder inside your Worker directory. This folder should be added to your .gitignore file.

If you need to clear local storage, delete the .wrangler/state folder. It will be recreated the next time you run wrangler dev.

​​ 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 in your Worker project:

  1. Create a .vscode folder in your project’s root folder if one does not exist.
  2. 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
      }
  ]

}

  1. 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.

  2. 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.

  3. Go back to a .js or .ts file in your project and add at least one breakpoint.

  4. 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.