← Cloudflare Workers / workers / testing / vitest-integration / migration-guides

Переход от тестовых окружений Miniflare 2

Miniflare 2 ↗ предоставленные пользовательские окружения для Jest и Vitest в jest-environment-miniflare и vitest-environment-miniflare пакеты соответственно. @cloudflare/vitest-plugin пакет предоставляет аналогичную функциональность, используя современные версии Miniflare и workerd среда выполнения ↗. workerd это та же среда выполнения JavaScript/WebAssembly, на которой работают Cloudflare Workers. Использование workerd уменьшает расхождения в поведении между тестами и развёрнутым кодом. См. Анонс Miniflare 3 ↗, где это описано подробнее.

Сначала удалите старое окружение и установите плагин Vitest. Окружения Vitest могут изменять только глобальную область видимости, тогда как плагин запускает тесты в отдельной среде выполнения. В данном случае плагин запускает ваши тесты внутри workerd ↗ вместо Node.js.

npm uninstall vitest-environment-miniflare
npm install --save-dev vitest@^4.1.0
npm install --save-dev @cloudflare/vitest-plugin

После установки интеграции Workers Vitest обновите файл конфигурации Vitest, чтобы использовать cloudflareTest() плагин Vite вместо этого. Большая часть конфигурации Miniflare, ранее указываемой в environmentOptions можно переместить в miniflare параметр в cloudflareTest(). См. Miniflare WorkerOptions интерфейс ↗ с поддерживаемыми параметрами и Руководство по переходу с Miniflare версии 2 на версию 3 для дополнительной информации. Если вы полагались на конфигурацию, хранившуюся в файле Wrangler, задайте wrangler.configPath тоже.

+ import { cloudflareTest } from "@cloudflare/vitest-plugin";
+ import { defineConfig } from "vitest/config";

- export default defineWorkersConfig({
-   test: {
-     environment: "miniflare",
-     environmentOptions: { ... },
-   },
- });
+ export default defineConfig({
+   plugins: [
+     cloudflareTest({
+       miniflare: { ... },
+       wrangler: { configPath: "./wrangler.jsonc" },
+     }),
+   ],
+ });

Если вы используете TypeScript, обновите tsconfig.json чтобы включить нужный ambient types:

  {
    "compilerOptions": {
      ...,
      "types": [
				...
-       "vitest-environment-miniflare/globals"
+       "@cloudflare/vitest-plugin/types"
      ]
    },
  }

Чтобы получить доступ к привязки в ваших тестах используйте env вспомогательную функцию из cloudflare:workers модуль.

  import { it } from "vitest";
+ import { env } from "cloudflare:workers";

  it("does something", () => {
-   const env = getMiniflareBindings();
    // ...
  });

Если вы используете TypeScript, необходимо определить тип env для ваших тестов. См. Определение типов для инструкций по настройке.

По умолчанию изоляция хранилища выполняется на уровне тестового файла. Вам больше не нужно добавлять setupMiniflareIsolatedStorage() в ваших тестах.

- const describe = setupMiniflareIsolatedStorage();
+ import { describe } from "vitest";

new ExecutionContext() конструктор и getMiniflareWaitUntil() функция теперь createExecutionContext() и waitOnExecutionContext() соответственно. Обратите внимание на waitOnExecutionContext() теперь возвращает пустой Promise<void> вместо Promise, разрешающийся в результаты всех waitUntil(), то есть переданные Promises.

+ import { createExecutionContext, waitOnExecutionContext } from "cloudflare:test";

  it("does something", () => {
    // ...
-   const ctx = new ExecutionContext();
+   const ctx = createExecutionContext();
    const response = worker.fetch(request, env, ctx);
-   await getMiniflareWaitUntil(ctx);
+   await waitOnExecutionContext(ctx);
  });

getMiniflareFetchMock() функция больше не доступна. Чтобы имитировать исходящие запросы, используйте @msw/cloudflare ↗. См. Подмена исходящих запросов для инструкций по настройке.

getMiniflareDurableObjectStorage(), getMiniflareDurableObjectState(), getMiniflareDurableObjectInstance(), а также runWithMiniflareDurableObjectGates() функции были заменены одной runInDurableObject() функцию из cloudflare:test модуль. runInDurableObject() функция принимает DurableObjectStub с обратным вызовом, принимающим Durable Object и соответствующий DurableObjectState в качестве аргументов. Объединение этих функций в одну упрощает поверхность API и гарантирует, что доступ к экземплярам осуществляется с правильным контекстом запроса и поведение блокировки доступа ↗. См. страница Test APIs для дополнительных сведений.

+ import { env } from "cloudflare:workers";
+ import { runInDurableObject } from "cloudflare:test";

  it("does something", async () => {
-   const env = getMiniflareBindings();
    const id = env.OBJECT.newUniqueId();
+   const stub = env.OBJECT.get(id);

-   const storage = await getMiniflareDurableObjectStorage(id);
-   doSomethingWith(storage);
+   await runInDurableObject(stub, async (instance, state) => {
+     doSomethingWith(state.storage);
+   });

-   const state = await getMiniflareDurableObjectState(id);
-   doSomethingWith(state);
+   await runInDurableObject(stub, async (instance, state) => {
+     doSomethingWith(state);
+   });

-   const instance = await getMiniflareDurableObjectInstance(id);
-   await runWithMiniflareDurableObjectGates(state, async () => {
-     doSomethingWith(instance);
-   });
+   await runInDurableObject(stub, async (instance) => {
+     doSomethingWith(instance);
+   });
  });

flushMiniflareDurableObjectAlarms() функция была заменена на runDurableObjectAlarm() функцию из cloudflare:test модуль. runDurableObjectAlarm() функция принимает один DurableObjectStub и возвращает Promise который разрешается в true если alarm был запланирован и alarm() обработчик был выполнен, или false в противном случае. Чтобы «сбросить» alarm нескольких инстансов, вызовите runDurableObjectAlarm() в цикле.

+ import { env } from "cloudflare:workers";
+ import { runDurableObjectAlarm } from "cloudflare:test";

  it("does something", async () => {
-   const env = getMiniflareBindings();
    const id = env.OBJECT.newUniqueId();
-   await flushMiniflareDurableObjectAlarms([id]);
+   const stub = env.OBJECT.get(id);
+   const ran = await runDurableObjectAlarm(stub);
  });

Наконец, getMiniflareDurableObjectIds() функция была заменена на listDurableObjectIds() функцию из cloudflare:test модуль. listDurableObjectIds() функция теперь принимает DurableObjectNamespace экземпляр вместо пространства имён string для более строгой типизации. Обратите внимание на listDurableObjectIds() функция учитывает изоляцию хранилища. Идентификаторы объектов, созданных в других тестовых файлах, не возвращаются.

+ import { env } from "cloudflare:workers";
+ import { listDurableObjectIds } from "cloudflare:test";

  it("does something", async () => {
-   const ids = await getMiniflareDurableObjectIds("OBJECT");
+   const ids = await listDurableObjectIds(env.OBJECT);
  });