Add Vitest environment, closes #342

The Vitest environment behaves almost identically to the Jest
environment. Due to Vitest custom environment API restrictions,
isolated storage must be installed manually in each test file. Call
the `setupMiniflareIsolatedStorage()` global function and use the
returned `describe` function instead of the regular
`describe`/`suite` functions imported from `vitest`.

Author: mrbbot

package-lock.json

@@ -31,7 +31,7 @@
   "devDependencies": {
     "@ava/typescript": "^2.0.0",
     "@microsoft/api-extractor": "^7.19.4",
-    "@types/node": "^18.7.6",
+    "@types/node": "^18.7.15",
     "@types/rimraf": "^3.0.2",
     "@types/which": "^2.0.1",
     "@typescript-eslint/eslint-plugin": "^5.9.1",

package.json

@@ -1,4 +1,4 @@
-# `@miniflare/jest`
+# `jest-environment-miniflare`
 
 Jest testing module for [Miniflare](https://github.com/cloudflare/miniflare): a
 fun, full-featured, fully-local simulator for Cloudflare Workers. See

packages/jest-environment-miniflare/README.md

@@ -1,7 +1,7 @@
 {
   "name": "jest-environment-miniflare",
   "version": "2.7.1",
-  "description": "Jest testing module for Miniflare: a fun, full-featured, fully-local simulator for Cloudflare Workers",
+  "description": "Jest testing environment for Miniflare: a fun, full-featured, fully-local simulator for Cloudflare Workers",
   "keywords": [
     "cloudflare",
     "workers",
@@ -35,17 +35,9 @@
     "extends": "../../package.json"
   },
   "dependencies": {
-    "@miniflare/cache": "2.7.1",
-    "@miniflare/core": "2.7.1",
-    "@miniflare/durable-objects": "2.7.1",
-    "@miniflare/html-rewriter": "2.7.1",
-    "@miniflare/kv": "2.7.1",
     "@miniflare/runner-vm": "2.7.1",
     "@miniflare/shared": "2.7.1",
-    "@miniflare/sites": "2.7.1",
-    "@miniflare/storage-memory": "2.7.1",
-    "@miniflare/web-sockets": "2.7.1",
-    "miniflare": "2.7.1",
+    "@miniflare/shared-test-environment": "2.7.1",
     "@jest/environment": ">=27",
     "@jest/fake-timers": ">=27",
     "@jest/types": ">=27",
@@ -63,6 +55,7 @@
     "jest": "^28.1.0",
     "jest-mock": "^28.1.0",
     "jest-util": "^28.1.0",
+    "miniflare": "2.7.1",
     "react-dom": "^18.1.0"
   }
 }

packages/jest-environment-miniflare/package.json

@@ -6,65 +6,22 @@ import type {
 } from "@jest/environment";
 import { LegacyFakeTimers, ModernFakeTimers } from "@jest/fake-timers";
 import type { Circus, Config, Global } from "@jest/types";
-import { CachePlugin } from "@miniflare/cache";
-import {
-  BindingsPlugin,
-  CorePlugin,
-  MiniflareCore,
-  createFetchMock,
-} from "@miniflare/core";
-import {
-  DurableObjectId,
-  DurableObjectStorage,
-  DurableObjectsPlugin,
-} from "@miniflare/durable-objects";
-import { HTMLRewriterPlugin } from "@miniflare/html-rewriter";
-import { KVPlugin } from "@miniflare/kv";
-import { R2Plugin } from "@miniflare/r2";
+import { MiniflareCore } from "@miniflare/core";
 import { VMScriptRunner, defineHasInstances } from "@miniflare/runner-vm";
-import { Context, NoOpLog } from "@miniflare/shared";
-import { SitesPlugin } from "@miniflare/sites";
-import { WebSocketPlugin } from "@miniflare/web-sockets";
+import {
+  PLUGINS,
+  StackedMemoryStorageFactory,
+  createMiniflareEnvironment,
+} from "@miniflare/shared-test-environment";
 import { ModuleMocker } from "jest-mock";
 import { installCommonGlobals } from "jest-util";
-import { MockAgent } from "undici";
-import { StackedMemoryStorageFactory } from "./storage";
-
-declare global {
-  function getMiniflareBindings<Bindings = Context>(): Bindings;
-  function getMiniflareDurableObjectStorage(
-    id: DurableObjectId
-  ): Promise<DurableObjectStorage>;
-  function getMiniflareFetchMock(): MockAgent;
-  function flushMiniflareDurableObjectAlarms(
-    ids: DurableObjectId[]
-  ): Promise<void>;
-}
-
-// MiniflareCore will ensure CorePlugin is first and BindingsPlugin is last,
-// so help it out by doing it ourselves so it doesn't have to. BuildPlugin
-// is intentionally omitted as the worker should only be built once per test
-// run, as opposed to once per test suite. The user is responsible for this.
-const PLUGINS = {
-  CorePlugin,
-  KVPlugin,
-  R2Plugin,
-  DurableObjectsPlugin,
-  CachePlugin,
-  SitesPlugin,
-  HTMLRewriterPlugin,
-  WebSocketPlugin,
-  BindingsPlugin,
-};
 
 export type Timer = {
   id: number;
   ref: () => Timer;
   unref: () => Timer;
 };
 
-const log = new NoOpLog();
-
 // Adapted from jest-environment-node:
 // https://github.com/facebook/jest/blob/8f2cdad7694f4c217ac779d3f4e3a150b5a3d74d/packages/jest-environment-node/src/index.ts
 export default class MiniflareEnvironment implements JestEnvironment<Timer> {
@@ -81,7 +38,7 @@ export default class MiniflareEnvironment implements JestEnvironment<Timer> {
 
   private readonly storageFactory = new StackedMemoryStorageFactory();
   private readonly scriptRunner: VMScriptRunner;
-  private readonly mockAgent: MockAgent;
+  private mf?: MiniflareCore<typeof PLUGINS>;
 
   constructor(
     config:
@@ -102,8 +59,6 @@ export default class MiniflareEnvironment implements JestEnvironment<Timer> {
     defineHasInstances(this.context);
     this.scriptRunner = new VMScriptRunner(this.context);
 
-    this.mockAgent = createFetchMock();
-
     const global = (this.global = vm.runInContext("this", this.context));
     global.global = global;
     global.self = global;
@@ -162,93 +117,30 @@ export default class MiniflareEnvironment implements JestEnvironment<Timer> {
 
   async setup(): Promise<void> {
     const global = this.global as any;
-
-    const mf = new MiniflareCore(
-      PLUGINS,
+    const [mf, mfGlobalScope] = await createMiniflareEnvironment(
       {
-        log,
         storageFactory: this.storageFactory,
         scriptRunner: this.scriptRunner,
-        // Only run the script if we're using Durable Objects and need to have
-        // access to the exported classes. This means we're only running the
-        // script in modules mode, so we don't need to worry about
-        // addEventListener being called twice (once when the script is run, and
-        // again when the user imports the worker in Jest tests).
-        scriptRunForModuleExports: true,
       },
+      this.config.testEnvironmentOptions,
       {
-        // Autoload configuration files from default locations by default,
-        // like the CLI (but allow the user to disable this/customise locations)
-        wranglerConfigPath: true,
-        packagePath: true,
-        envPathDefaultFallback: true,
-
-        // Apply user's custom Miniflare options
-        ...this.config.testEnvironmentOptions,
-
-        globals: {
-          ...(this.config.testEnvironmentOptions?.globals as any),
-
-          // Make sure fancy jest console and faked timers are included
-          console: global.console,
-          setTimeout: global.setTimeout,
-          setInterval: global.setInterval,
-          clearTimeout: global.clearTimeout,
-          clearInterval: global.clearInterval,
-        },
-
-        // These options cannot be overwritten:
-        // - We get the global scope once, so watch mode wouldn't do anything,
-        //   apart from stopping Jest exiting
-        watch: false,
-        // - Persistence must be disabled for stacked storage to work
-        kvPersist: false,
-        cachePersist: false,
-        durableObjectsPersist: false,
-        // - Allow all global operations, tests will be outside of a request
-        //   context, but we definitely want to allow people to access their
-        //   namespaces, perform I/O, etc.
-        globalAsyncIO: true,
-        globalTimers: true,
-        globalRandom: true,
-        // - Use the actual `Date` class. We'll be operating outside a request
-        //   context, so we'd be returning the actual time anyway, and this
-        //   might mess with Jest's own mocking.
-        actualTime: true,
-        // - We always want getMiniflareFetchMock() to return this MockAgent
-        fetchMock: this.mockAgent,
+        // Make sure fancy jest console and faked timers are included
+        console: global.console,
+        setTimeout: global.setTimeout,
+        setInterval: global.setInterval,
+        clearTimeout: global.clearTimeout,
+        clearInterval: global.clearInterval,
       }
     );
+    this.mf = mf;
 
-    const mfGlobalScope = await mf.getGlobalScope();
-    mfGlobalScope.global = global;
-    mfGlobalScope.self = global;
     // Make sure Miniflare's global scope is assigned to Jest's global context,
     // even if we didn't run a script because we had no Durable Objects
     Object.assign(global, mfGlobalScope);
-
-    // Add a way of getting bindings in modules mode to allow seeding data.
-    // These names are intentionally verbose so they don't collide with anything
-    // else in scope.
-    const bindings = await mf.getBindings();
-    global.getMiniflareBindings = () => bindings;
-    global.getMiniflareDurableObjectStorage = async (id: DurableObjectId) => {
-      const plugin = (await mf.getPlugins()).DurableObjectsPlugin;
-      const storage = mf.getPluginStorage("DurableObjectsPlugin");
-      const state = await plugin.getObject(storage, id);
-      return state.storage;
-    };
-    global.getMiniflareFetchMock = () => this.mockAgent;
-    global.flushMiniflareDurableObjectAlarms = async (
-      ids?: DurableObjectId[]
-    ): Promise<void> => {
-      const plugin = (await mf.getPlugins()).DurableObjectsPlugin;
-      const storage = mf.getPluginStorage("DurableObjectsPlugin");
-      return plugin.flushAlarms(storage, ids);
-    };
   }
 
   async teardown(): Promise<void> {
+    await this.mf?.dispose();
     this.fakeTimers?.dispose();
     this.fakeTimersModern?.dispose();
     this.context = null;

packages/jest-environment-miniflare/src/index.ts

@@ -46,3 +46,12 @@ describe("more KV tests", () => {
     });
   });
 });
+
+test("KV test 7", async () => {
+  await append("m");
+  expect(await get()).toBe("abm");
+});
+test("KV test 8", async () => {
+  await append("n");
+  expect(await get()).toBe("abn");
+});

packages/jest-environment-miniflare/test/fixtures/kv.worker.spec.js

@@ -0,0 +1,57 @@
+import { MiniflareCore } from "@miniflare/core";
+import {
+  DurableObjectId,
+  DurableObjectStorage,
+} from "@miniflare/durable-objects";
+import { Context } from "@miniflare/shared";
+import { MockAgent } from "undici";
+import { PLUGINS } from "./plugins";
+
+declare global {
+  function getMiniflareBindings<Bindings = Context>(): Bindings;
+  function getMiniflareDurableObjectStorage(
+    id: DurableObjectId
+  ): Promise<DurableObjectStorage>;
+  function getMiniflareFetchMock(): MockAgent;
+  function flushMiniflareDurableObjectAlarms(
+    ids: DurableObjectId[]
+  ): Promise<void>;
+}
+
+export interface MiniflareEnvironmentUtilities {
+  getMiniflareBindings<Bindings = Context>(): Bindings;
+  getMiniflareDurableObjectStorage(
+    id: DurableObjectId
+  ): Promise<DurableObjectStorage>;
+  getMiniflareFetchMock(): MockAgent;
+  flushMiniflareDurableObjectAlarms(ids: DurableObjectId[]): Promise<void>;
+}
+
+export async function createMiniflareEnvironmentUtilities(
+  mf: MiniflareCore<typeof PLUGINS>,
+  fetchMock: MockAgent
+): Promise<MiniflareEnvironmentUtilities> {
+  // Add a way of getting bindings in modules mode to allow seeding data.
+  // These names are intentionally verbose, so they don't collide with anything
+  // else in scope.
+  const bindings = await mf.getBindings();
+  return {
+    getMiniflareBindings<Bindings>() {
+      return bindings as Bindings;
+    },
+    async getMiniflareDurableObjectStorage(id: DurableObjectId) {
+      const plugin = (await mf.getPlugins()).DurableObjectsPlugin;
+      const storage = mf.getPluginStorage("DurableObjectsPlugin");
+      const state = await plugin.getObject(storage, id);
+      return state.storage;
+    },
+    getMiniflareFetchMock() {
+      return fetchMock;
+    },
+    async flushMiniflareDurableObjectAlarms(ids?: DurableObjectId[]) {
+      const plugin = (await mf.getPlugins()).DurableObjectsPlugin;
+      const storage = mf.getPluginStorage("DurableObjectsPlugin");
+      return plugin.flushAlarms(storage, ids);
+    },
+  };
+}

packages/shared-test-environment/src/globals.ts

@@ -0,0 +1,82 @@
+import {
+  MiniflareCore,
+  MiniflareCoreContext,
+  MiniflareCoreOptions,
+  createFetchMock,
+} from "@miniflare/core";
+import { Context, NoOpLog } from "@miniflare/shared";
+import { createMiniflareEnvironmentUtilities } from "./globals";
+import { PLUGINS } from "./plugins";
+
+export * from "./plugins";
+export * from "./storage";
+export type { MiniflareEnvironmentUtilities } from "./globals";
+
+const log = new NoOpLog();
+
+export async function createMiniflareEnvironment(
+  ctx: Pick<MiniflareCoreContext, "storageFactory" | "scriptRunner">,
+  options: MiniflareCoreOptions<typeof PLUGINS>,
+  globalOverrides?: Context
+): Promise<[mf: MiniflareCore<typeof PLUGINS>, globals: Context]> {
+  const fetchMock = createFetchMock();
+  const mf = new MiniflareCore(
+    PLUGINS,
+    {
+      log,
+      ...ctx,
+      // Only run the script if we're using Durable Objects and need to have
+      // access to the exported classes. This means we're only running the
+      // script in modules mode, so we don't need to worry about
+      // addEventListener being called twice (once when the script is run, and
+      // again when the user imports the worker in Jest tests).
+      scriptRunForModuleExports: true,
+    },
+    {
+      // Autoload configuration files from default locations by default,
+      // like the CLI (but allow the user to disable this/customise locations)
+      wranglerConfigPath: true,
+      packagePath: true,
+      envPathDefaultFallback: true,
+
+      // Apply user's custom Miniflare options
+      ...options,
+
+      globals: {
+        ...(options?.globals as any),
+        ...globalOverrides,
+      },
+
+      // These options cannot be overwritten:
+      // - We get the global scope once, so watch mode wouldn't do anything,
+      //   apart from stopping Jest exiting
+      watch: false,
+      // - Persistence must be disabled for stacked storage to work
+      kvPersist: false,
+      cachePersist: false,
+      durableObjectsPersist: false,
+      // - Allow all global operations, tests will be outside of a request
+      //   context, but we definitely want to allow people to access their
+      //   namespaces, perform I/O, etc.
+      globalAsyncIO: true,
+      globalTimers: true,
+      globalRandom: true,
+      // - Use the actual `Date` class. We'll be operating outside a request
+      //   context, so we'd be returning the actual time anyway, and this
+      //   might mess with Jest's own mocking.
+      actualTime: true,
+      // - We always want getMiniflareFetchMock() to return this MockAgent
+      fetchMock,
+    }
+  );
+
+  const mfGlobalScope = await mf.getGlobalScope();
+  mfGlobalScope.global = global;
+  mfGlobalScope.self = global;
+
+  // Attach Miniflare utility methods to global
+  const mfUtilities = await createMiniflareEnvironmentUtilities(mf, fetchMock);
+  Object.assign(mfGlobalScope, mfUtilities);
+
+  return [mf, mfGlobalScope];
+}