Перетворення коду
Jest виконує код у вашому проєкті як JavaScript. Проте, якщо ви використовуєте синтаксис, який не підтримується Node "з коробки" (наприклад, JSX, TypeScript, шаблони Vue), то слід перетворити цей код у звичайний JavaScript, подібний до того, що використовується для браузерів.
В Jest це реалізовано за допомогою опції конфігурації transform
.
Перетворювач — це модуль, що надає метод для перетворення вихідних файлів. Наприклад, якби вам було потрібно використати нові можливості мови в ваших модулях або тестах, які ще не підтримуються Node, ви б могли під'єднати препроцесор коду, який перекладе його з майбутньої версії JavaScript на поточну.
Jest закешує результат перетворення та перевірятиме його дійсність на основі декількох факторів, таких, як джерело файлу, що трансформується, та зміна конфігурації.
Вбудовані опції
Jest ships with one transformer out of the box – 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>;
};
Задля стислості, наведений вище код був скорочений. Full code can be found in Jest repo on GitHub (remember to choose the right tag/commit for your version of Jest).
Існує декілька способів імпортувати код у Jest - за допомогою Common JS (require
) або модулів ECMAScript (import
, який існує в статичній та динамічній версіях). За запитом, Jest пропускає файли через перетворення коду (наприклад, коли виконується require
або import
). Цей процес, відомий як "транспіляція", може відбуватися синхронно (у випадку require
), або асинхронно (у випадку import
або import()
; останній також може виконуватись з Common JS модулів). З цієї причини, інтерфейс піддає обидві пари методів асинхронному та синхронному процесам: process{Async}
та getCacheKey{Async}
. Останній викликається, щоб з'ясувати, чи треба викликати process{Async}
.
Асинхронна транспіляція може повернутися до синхронного процесу
виклику, якщо processAsync
не реалізовано, але синхронна транспіляція не може використовувати асинхронний processAsync
виклик. Якщо ESM є вашою кодовою базою, достатньо реалізувати лише асинхронні варіанти. Інакше, якщо будь-яку частину коду завантажувати через require
(createRequire
з ESM включно), доведеться прописувати синхронний варіант process
.
Майте на увазі, що node_modules
не транспілюється з налаштуванням за замовчуванням, для цього повинні бути змінені налаштування transformIgnorePatterns
.
Частково до цього причетні прапори підтримки, які ми передаємо (CallerTransformOptions
, як приклад), але во ни мають використовуватись всередині перетворення, аби зрозуміти, повертається ESM чи CJS, та не впливають на питання синхронності.
Хоч це й не обов'язково, ми дуже рекомендуємо реалізувати getCacheKey
, аби не витрачати ресурси на перетворення коду та зчитати попередній результат з диска. You can use @jest/create-cache-key-function
to help implement it.
Замість прямої реалізації у вашому власному перетворювачі інтерфейсу Transformer
, ви можете експортувати createTransformer
- фабричний метод для динамічного створення перетворювачів. Це дозволить отримати конфігурацію перетворювача у вашій конфігурації Jest.
На підтримку модулю ECMAScript вказують опції, передані в supports*
. 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.