← Cloudflare Workers / workers / testing / vitest-integration

Изоляция и параллелизм

Узнайте, как интеграция Workers с Vitest запускает ваши тесты, изолирует их друг от друга и импортирует модули.

Запустить тесты

Когда вы запускаете тесты с интеграцией Workers Vitest, Vitest выполнит следующее:

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

Модель изоляции

Изоляция хранилища выполняется на уровне тестового файла. Каждый тестовый файл получает собственную среду хранения, и любые записи в хранилище в рамках одного тестового файла не видны другим тестовым файлам. Интеграция Workers с Vitest по возможности повторно использует Workers и их кеши модулей между запусками тестов. Копия всех вспомогательных workers существует в каждом workerd процесс.

По умолчанию тестовые файлы выполняются параллельно. Чтобы тестовые файлы использовали общее хранилище (например, для интеграционных тестов, зависящих от общего состояния), используйте флаги Vitest --max-workers=1 --no-isolate.

Модули

У каждого Worker есть собственный кэш модулей. Поскольку Workers используются повторно между тестовыми запусками, их кэши модулей также используются повторно. Vitest сбрасывает часть кэша модулей в начале каждого тестового запуска на основе изменённых файлов.

Плагин Workers Vitest выполняет код внутри Cloudflare Worker, который Vitest обычно запускал бы внутри Node.js Worker thread ↗. Чтобы это стало возможным, плагин автоматически внедряет nodejs_compat, [no_nodejs_compat_v2] и export_commonjs_default флаги совместимости. Это минимальная настройка совместимости, при которой Vitest всё ещё работает корректно, но без лишних полифилов и глобальных объектов. Если в конфигурации уже указан флаг совместимости с Node.js, плагин Vitest не добавляет эти флаги повторно.

Внимание

Использование плагина Workers Vitest может привести к тому, что после развёртывания поведение вашего Worker будет отличаться, так как nodejs_compat флаг включён по умолчанию. Это означает, что специфичные для Node.js API и модули доступны при запуске тестов. Однако Cloudflare Workers не поддерживают эти API Node.js в production-окружении, если вы не укажете этот флаг в конфигурации своего Worker.

Если у вас нет nodejs_compat или nodejs_compat_v2 флаг в конфигурации и импортируете модуль Node.js в код своего Worker, ваши тесты могут проходить успешно, однако вы не сможете развернуть этот Worker, поскольку вызов загрузки (через REST API или через Wrangler) вызовет ошибку.

Однако, если вы используете глобальные объекты Node.js, которые не поддерживаются средой выполнения, загрузка Worker пройдёт успешно, но в продакшен-коде могут появиться ошибки. Рассмотрим искусственный пример, иллюстрирующий эту проблему.

Файл конфигурации Wrangler не задаёт ни nodejs_compat или nodejs_compat_v2:

{ "name": "test",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-08-28"
	# no nodejs_compat flags here
}

name = "test"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-08-28"

В нашем src/index.ts файле мы используем process объект, являющийся глобальным объектом Node.js и недоступный в среде выполнения Workerd:

export default {
	async fetch(request, env, ctx): Promise<Response> {
		process.env.TEST = "test";
		return new Response(process.env.TEST);
	},
} satisfies ExportedHandler<Env>;

Тест представляет собой простую проверку того, что Worker смог использовать process.

it('responds with "test"', async () => {
	const response = await exports.default.fetch("https://example.com/");
	expect(await response.text()).toMatchInlineSnapshot(`"test"`);
});

Теперь, если мы выполним npm run test, видно, что тесты будут pass:

 ✓ test/index.spec.ts (1)
   ✓ responds with "test"

 Test Files  1 passed (1)
      Tests  1 passed (1)

И мы можем выполнить wrangler dev и wrangler deploy без проблем. Он похоже на наш код в порядке. Однако в продакшене этот код завершится с ошибкой, так как process недоступен в среде выполнения Workerd.

Чтобы исправить эту проблему, нужно либо отказаться от использования Node.js API, либо добавить nodejs_compat флаг в конфигурацию Wrangler.