Перетворення коду

Jest виконує код у вашому проєкті як JavaScript. Проте, якщо ви використовуєте синтаксис, який не підтримується Node "з коробки" (наприклад, JSX, TypeScript, шаблони Vue), то слід перетворити цей код у звичайний JavaScript, подібний до того, що використовується для браузерів.

В Jest це реалізовано за допомогою опції конфігурації transform.

Перетворювач — це модуль, що надає метод для перетворення вихідних файлів. Наприклад, якби вам було потрібно використати нові можливості мови в ваших модулях або тестах, які ще не підтримуються Node, ви б могли під'єднати препроцесор коду, який перекладе його з майбутньої версії JavaScript на поточну.

Jest закешує результат перетворення та перевірятиме його дійсність на основі декількох факторів, таких, як джерело файлу, що трансформується, та зміна конфігурації.

Вбудовані опції

Jest підтримує один перетворювач "з коробки" – babel-jest. Він завантажує Babel конфігурацію вашого проєкту та перетворює будь-який файл, який відповідає регулярному виразу /\.[jt]sx?$/ (іншими словами, будь-який . s, .jsx, .ts або .tsx файл). Додатково, babel-jest додасть плагін Babel, необхідний для імітації підняття, про яку йде мова в ES Module mocking.

порада

Не забудьте явно додати babel-jest, якщо ви хочете використовувати його разом з додатковими препроцесорами коду:

"transform": {
  "\\.[jt]sx?$": "babel-jest",
  "\\.css$": "some-css-transformer",
}

Створення власних перетворювачів

You can write your own transformer. The API of a transformer is as follows:

interface TransformOptions<TransformerConfig = unknown> {
  supportsDynamicImport: boolean;
  supportsExportNamespaceFrom: boolean;
  /**
   * Значення дорівнює:
   * - `false`, якщо Jest запускається без прапору Node ESM `--experimental-vm-modules`
   * - `true`, якщо розширення файлу визначено в [extensionsToTreatAsEsm](Configuration.md#extensionstotreatasesm-arraystring)
   * та Jest запускається з прапором Node ESM `--experimental-vm-modules`
   *
   * Детальніше тут https://jestjs.io/docs/next/ecmascript-modules
   */
  supportsStaticESM: boolean;
  supportsTopLevelAwait: boolean;
  instrument: boolean;
  /** Кешована файлова система, яку використовує `jest-runtime` для покращення продуктивності. */
  cacheFS: Map<string, string>;
  /** Jest конфігурація нині запущеного проєкту. */
  config: ProjectConfig;
  /** Рядкова версія `config` - корисна для скидання кешу. */
  configString: string;
  /** Конфігурація перетворювача, передана користувачем через `transform`. */
  transformerConfig: TransformerConfig;
}

type TransformedSource = {
  code: string;
  map?: RawSourceMap | string | null;
};

interface SyncTransformer<TransformerConfig = unknown> {
  canInstrument?: boolean;

  getCacheKey?: (
    sourceText: string,
    sourcePath: string,
    options: TransformOptions<TransformerConfig>,
  ) => string;

  getCacheKeyAsync?: (
    sourceText: string,
    sourcePath: string,
    options: TransformOptions<TransformerConfig>,
  ) => Promise<string>;

  process: (
    sourceText: string,
    sourcePath: string,
    options: TransformOptions<TransformerConfig>,
  ) => TransformedSource;

  processAsync?: (
    sourceText: string,
    sourcePath: string,
    options: TransformOptions<TransformerConfig>,
  ) => Promise<TransformedSource>;
}

interface AsyncTransformer<TransformerConfig = unknown> {
  canInstrument?: boolean;

  getCacheKey?: (
    sourceText: string,
    sourcePath: string,
    options: TransformOptions<TransformerConfig>,
  ) => string;

  getCacheKeyAsync?: (
    sourceText: string,
    sourcePath: string,
    options: TransformOptions<TransformerConfig>,
  ) => Promise<string>;

  process?: (
    sourceText: string,
    sourcePath: string,
    options: TransformOptions<TransformerConfig>,
  ) => TransformedSource;

  processAsync: (
    sourceText: string,
    sourcePath: string,
    options: TransformOptions<TransformerConfig>,
  ) => Promise<TransformedSource>;
}

type Transformer<TransformerConfig = unknown> =
  | SyncTransformer<TransformerConfig>
  | AsyncTransformer<TransformerConfig>;

type TransformerCreator<
  X extends Transformer<TransformerConfig>,
  TransformerConfig = unknown,
> = (transformerConfig?: TransformerConfig) => X;

type TransformerFactory<X extends Transformer> = {
  createTransformer: TransformerCreator<X>;
};

note

Задля стислості, наведений вище код був скорочений. Повну версію можна знайти в GitHub репозиторії Jest (не забудьте обрати тег/коміт відповідно до вашої версії Jest).

Існує декілька способів імпортувати код у Jest - за допомогою Common JS (require) або модулів ECMAScript (import, який існує в статичній та динамічній версіях). За запитом, Jest пропускає файли через перетворення коду (наприклад, коли виконується require або import). Цей процес, відомий як "транспіляція", може відбуватися синхронно (у випадку require), або асинхронно (у випадку import або import(); останній також може виконуватись з Common JS модулів). З цієї причини, інтерфейс піддає обидві пари методів асинхронному та синхронному процесам: process{Async} та getCacheKey{Async}. Останній викликається, щоб з'ясувати, чи треба викликати process{Async}.

Asynchronous transpilation can fall back to the synchronous process call if processAsync is unimplemented, but synchronous transpilation cannot use the asynchronous processAsync call. If your codebase is ESM only, implementing the async variants are sufficient. Otherwise, if any code is loaded through require (including createRequire from within ESM), then you need to implement the synchronous process variant.

Be aware that node_modules is not transpiled with default config, the transformIgnorePatterns setting must be modified in order to do so.

Semi-related to this are the supports flags we pass (see CallerTransformOptions above), but those should be used within the transform to figure out if it should return ESM or CJS, and has no direct bearing on sync vs async

Though not required, we highly recommend implementing getCacheKey as well, so we do not waste resources transpiling when we could have read its previous result from disk. You can use @jest/create-cache-key-function to help implement it.

Instead of having your custom transformer implement the Transformer interface directly, you can choose to export createTransformer, a factory function to dynamically create transformers. This is to allow having a transformer config in your jest config.

note

ECMAScript module support is indicated by the passed in supports* options. Specifically supportsDynamicImport: true means the transformer can return import() expressions, which is supported by both ESM and CJS. If supportsStaticESM: true it means top level import statements are supported and the code will be interpreted as ESM and not CJS. See Node's docs for details on the differences.

порада

Make sure process{Async} method returns source map alongside with transformed code, so it is possible to report line information accurately in code coverage and test errors. Inline source maps also work but are slower.

During the development of a transformer it can be useful to run Jest with --no-cache to frequently delete cache.

Приклади

TypeScript з перевіркою типу

While babel-jest by default will transpile TypeScript files, Babel will not verify the types. If you want that you can use ts-jest.

Перетворення зображень на їх шлях

Importing images is a way to include them in your browser bundle, but they are not valid JavaScript. One way of handling it in Jest is to replace the imported value with its filename.

fileTransformer.js

const path = require('path');

module.exports = {
  process(sourceText, sourcePath, options) {
    return {
      code: `module.exports = ${JSON.stringify(path.basename(sourcePath))};`,
    };
  },
};

jest.config.js

module.exports = {
  transform: {
    '\\.(jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$':
      '<rootDir>/fileTransformer.js',
  },
};