Тестовое окружение

Jest предоставляет параметр environment для запуска кода в определённом окружении. Вы можете изменить поведение окружения с помощью параметра testEnvironmentOptions.

По умолчанию доступны следующие окружения:

node — окружение по умолчанию
jsdom эмулирует окружение браузера, предоставляя Browser API, и использует пакет jsdom

Окружения для отдельных файлов

информация

Каждый набор тестов выполняется в собственном экземпляре TestEnvironment. setup и teardown вызываются один раз для каждого набора.

Если задать параметр testEnvironment в конфигурации, он будет применяться ко всем файлам тестов в проекте. Для более точной настройки можно использовать прагмы docblock, чтобы указать окружение для отдельных файлов. Прагмы docblock — это комментарии, которые начинаются с @jest-environment, за которым следует имя окружения:

Со встроенными окружениями:

JavaScript
TypeScript

/**
 * @jest-environment jsdom
 */

test('use jsdom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

my-test.spec.js

/**
 * @jest-environment jsdom
 */

test('use jsdom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

my-test.spec.ts

С пользовательским окружением:

JavaScript
TypeScript

/**
 * @jest-environment ./my-custom-environment.js
 */

test('use jsdom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

my-test.spec.js

/**
 * @jest-environment ./my-custom-environment.ts
 */

test('use jsdom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

my-test.spec.ts

Расширение встроенных окружений

Jest позволяет расширять встроенные окружения, такие как NodeEnvironment или JSDOMEnvironment, чтобы создавать собственные пользовательские окружения. Это полезно, если вы хотите добавить дополнительные возможности или изменить поведение существующих окружений.

Пример расширения NodeEnvironment:

JavaScript
TypeScript

// An example of a custom Node environment

const NodeEnvironment = require('jest-environment-node');

/**
 * @implements {import('jest-environment-node').NodeEnvironment}
 */
class CustomNodeEnvironment extends NodeEnvironment {
  constructor(config, context) {
    super(config, context);
    console.log(config.globalConfig);
    console.log(config.projectConfig);
    this.testPath = context.testPath;
    this.docblockPragmas = context.docblockPragmas;
  }

  async setup() {
    await super.setup();
    await someSetupTasks(this.testPath);
    this.global.someGlobalObject = createGlobalObject();

    // Will trigger if docblock contains @my-custom-pragma my-pragma-value
    if (this.docblockPragmas['my-custom-pragma'] === 'my-pragma-value') {
      // ...
    }
  }

  async teardown() {
    this.global.someGlobalObject = destroyGlobalObject();
    await someTeardownTasks();
    await super.teardown();
  }

  getVmContext() {
    return super.getVmContext();
  }

  async handleTestEvent(event, state) {
    if (event.name === 'test_start') {
      // ...
    }
  }
}

module.exports = CustomNodeEnvironment;

custom-node-environment.js

// An example of a custom Node environment

import NodeEnvironment from 'jest-environment-node';

export default class CustomNodeEnvironment extends NodeEnvironment {
  constructor(config, context) {
    super(config, context);
    console.log(config.globalConfig);
    console.log(config.projectConfig);
    this.testPath = context.testPath;
    this.docblockPragmas = context.docblockPragmas;
  }

  async setup() {
    await super.setup();
    await someSetupTasks(this.testPath);
    this.global.someGlobalObject = createGlobalObject();

    // Will trigger if docblock contains @my-custom-pragma my-pragma-value
    if (this.docblockPragmas['my-custom-pragma'] === 'my-pragma-value') {
      // ...
    }
  }

  async teardown() {
    this.global.someGlobalObject = destroyGlobalObject();
    await someTeardownTasks();
    await super.teardown();
  }

  getVmContext() {
    return super.getVmContext();
  }

  async handleTestEvent(event, state) {
    if (event.name === 'test_start') {
      // ...
    }
  }
}

custom-node-environment.ts

и укажите его в конфигурации Jest

JavaScript
TypeScript

const {defineConfig} = require('jest');

module.exports = defineConfig({
  testEnvironment: './custom-node-environment.js',
});

jest.config.js

import {defineConfig} from 'jest';

export default defineConfig({
  testEnvironment: './custom-node-environment.ts',
});

jest.config.ts

примечание

Любые прагмы docblock в файле теста (например, @my-custom-pragma my-value) передаются конструктору окружения как context.docblockPragmas.

handleTestEvent необязателен. Если он возвращает Promise, jest-circus ожидает его завершения, прежде чем продолжить, — за исключением следующих синхронных событий: start_describe_definition, finish_describe_definition, add_hook, add_test и error.

совет

Jest также предоставляет пакет @jest/environment-jsdom-abstract, который упрощает создание собственного пользовательского тестового окружения на основе jsdom или использование собственной установленной версии jsdom.

JavaScript
TypeScript

const JSDOMEnvironment = require('@jest/environment-jsdom-abstract');
const jsdom = require('jsdom');

class CustomJSDOMEnvironment extends JSDOMEnvironment {
  constructor(config, context) {
    super(config, context, jsdom);
  }

  // Override methods to customize behavior
}

module.exports = CustomJSDOMEnvironment;

custom-jsdom-environment.js

import JSDOMEnvironment from '@jest/environment-jsdom-abstract';
import jsdom from 'jsdom';

export default class CustomJSDOMEnvironment extends JSDOMEnvironment {
  constructor(config, context) {
    super(config, context, jsdom);
  }

  // Override methods to customize behavior
}

custom-jsdom-environment.ts

и укажите его в конфигурации Jest

JavaScript
TypeScript

const {defineConfig} = require('jest');

module.exports = defineConfig({
  testEnvironment: './custom-jsdom-environment.js',
});

jest.config.js

import {defineConfig} from 'jest';

export default defineConfig({
  testEnvironment: './custom-jsdom-environment.ts',
});

jest.config.ts

Пользовательское окружение

Вы можете создать собственный пакет для расширения окружения Jest. Для этого создайте пакет с именем или укажите путь к допустимому файлу JS/TS. Этот пакет должен экспортировать объект со структурой Environment:

совет

Рекомендуется давать пользовательскому окружению имя с префиксом jest-environment-, чтобы его можно было легко распознать как окружение Jest.

JavaScript
TypeScript

/**
 * @implements {import('@jest/environment').JestEnvironment}
 */
class CustomEnvironment {
  // Implement the required methods here

  // Example of a method
  getVmContext() {
    return null;
  }
}

module.exports = CustomEnvironment;

environment.js

import type {JestEnvironment} from '@jest/environment';

export default class CustomEnvironment implements JestEnvironment {
  // Implement the required methods here

  // Example of a method
  getVmContext() {
    return null;
  }
}

environment.ts

и укажите его в конфигурации Jest

JavaScript
TypeScript

const {defineConfig} = require('jest');

module.exports = defineConfig({
  testEnvironment: './environment.js',
});

jest.config.js

import {defineConfig} from 'jest';

export default defineConfig({
  testEnvironment: './environment.ts',
});

jest.config.ts

Тестовое окружение

Окружения для отдельных файлов

Расширение встроенных окружений

Пользовательское окружение

См. также