Cloudflare Docs
Workers
Cloudflare Docs
Workers
Search icon (depiction of a magnifying glass)
GitHub icon
Visit Workers on GitHub
Set theme to dark (⇧+D)

Wrangler API

Wrangler offers an experimental API to programmatically manage your Cloudflare Workers.

  • unstable_dev - Start a local server for running integration tests against your Worker.

​​ unstable_dev

Start a local HTTP server for testing your Worker.

Once called, unstable_dev will return a fetch() function for invoking your Worker without needing to know the address or port, as well as a stop() function to shut down the HTTP server.

​​ Constructor

const worker = await unstable_dev(script, options, apiOptions)

​​ Parameters

  • script string

    • A string containing a path to your Worker script, relative to your Worker project’s root directory.

  • options object optional

    • Optional options object containing wrangler dev configuration settings.

  • apiOptions object optional

    • Optional API options object containing disableExperimentalWarning. Set disableExperimentalWarning to true to disable Wrangler’s warning about using unstable_ prefixed APIs.

​​ Return Type

unstable_dev() returns an object containing the following methods:

  • fetch() Promise<Response>

    • Send a request to your Worker. Returns a Promise that resolves with a Response object.
    • Refer to Fetch.

  • stop() Promise<void>

    • Shuts down the dev server.

​​ Usage

When initiating each test suite, use a beforeAll() function to start unstable_dev(). The beforeAll() function is used to minimize overhead: starting the dev server takes a few hundred milliseconds, starting and stopping for each individual test adds up quickly, slowing your tests down.

In each test case, call await worker.fetch(), and check that the response is what you expect.

To wrap up a test suite, call await worker.stop() in an afterAll function.

src/index.test.js
const { unstable_dev } = require("wrangler");



describe("Worker", () => {
	let worker;


	beforeAll(async () => {
		worker = await unstable_dev(
			"src/index.js",
			{},
			{ disableExperimentalWarning: true }
		);
	});


	afterAll(async () => {
		await worker.stop();
	});


	it("should return Hello World", async () => {
		const resp = await worker.fetch();
		if (resp) {
			const text = await resp.text();
			expect(text).toMatchInlineSnapshot(`"Hello World!"`);
		}
	});

});

src/index.test.ts
import { unstable_dev } from "wrangler";

import type { UnstableDevWorker } from "wrangler";



describe("Worker", () => {
	let worker: UnstableDevWorker;


	beforeAll(async () => {
		worker = await unstable_dev(
			"src/index.ts",
			{},
			{ disableExperimentalWarning: true }
		);
	});


	afterAll(async () => {
		await worker.stop();
	});


	it("should return Hello World", async () => {
		const resp = await worker.fetch();
		if (resp) {
			const text = await resp.text();
			expect(text).toMatchInlineSnapshot(`"Hello World!"`);
		}
	});

});