RFC: Writing tests with wrangler 2.x

[threepointone]

tl;dr - Tests are important, and we should enable developers to write and run tests.

There are 2 classes of tests I think are important -

• Integration tests - tests that test the whole system.
• Unit tests - tests that test a single piece of code.

Integration tests

Simply, can we spin up a server that's running a worker, and make sure it's doing what we expect? To be more specific, can we feed it requests and make assertions on the reponses (and potential side effects, like modifications to a KV store/ Durable Object)?

What comes to mind (for me) is that this is a great usecase for wrangler as an api. So you should be able to write somthing like this:

import wrangler from 'wrangler';

const worker = wrangler.dev('./path/to/worker.js', {
  // it could read from a wrangler.toml automatically 
  // but you could also feed it additional configuration 
  config: {
    vars: {/* ... */},
    kv_namespaces: [/* ... */],  
  },
  local: true // maybe you want to turn on local mode for tests? In fact, this could probably be the default.
  // ...
})

const response = await worker.fetch('/some/path', {method: 'POST', body: {/* ... */}});

expect(response.status).toBe(200);
expect(await response.json()).toEqual({/* ... */});

worker.close();

I think this should be relatively simple to do. We already have it somewhat working for our own fixture tests like here https://github.com/cloudflare/wrangler2/blob/main/examples/local-mode-tests/tests/module.test.ts. A thing we should do is not create a new process for every run, but expose the main function from https://github.com/cloudflare/wrangler2/blob/e9789865fa9e80ec61f48aef614e6a74fce258f3/packages/wrangler/src/index.tsx#L2800; this will make tests faster, and it'll be easier to pass arguments and callbacks and such. We can discuss further details on the issue for exposing wrangler as an api (TBD).

Previously explored pretty comprehensively with miniflare (with Miniflare as an api + dispatchFetch() helpers) https://miniflare.dev/testing/ava

Unit tests

Unit tests are a bit trickier, expecially because they're tied to a runner, and we'll have to support that. Specifically, we should start with making a jest environment. I suspect this will take a fair amount of work. We can lean on the work already explored in https://miniflare.dev/testing/jest / https://github.com/cloudflare/miniflare/tree/master/packages/jest-environment-miniflare, but it'll take a fair amount of work to adapt our esbuild/module system to also work (or maybe it won't be hard? I dunno.)

We can tackle other runners like vitest etc once we have the jest one, I suspect it won't be hard once we figure that one out.

---

Things to consider:

• service bindings: How does one mock a service binding?
• Handling workers with custom builds; say someone's building their worker with a custom build with babel plugins and whatnot, how do we enable them to still write jest-style tests? How do module imports work? I don't think this is unsolvable, but it'll take some elbow grease.
• There are probably plenty of factors I haven't listed here, open to hearing about them as we explore this space.