コードの変換
Jestはプロジェクト内のコードをJavaScriptとして実行しますが、Node.jsでサポートされていない構文 (JSX、TypeScriptの型、Vueのテンプレートなど) を使用している場合は、ブラウザ用にビルドする場合と同様に、コードをプレーンなJavaScriptに変換する必要があります。
Jest supports this via the transform configuration option.
Transformerはソースファイルを変換する同期処理を行う関数を提供するモジュールです。 例えばまだnodeではサポートされていない新しい言語の機能をモジュールやテストで使用したい時、将来のJavaScriptのバージョンを現在のものに変換する多くのコンパイラの中の１つをプラグインとして利用するでしょう。
Jestは変換の結果をキャッシュし、変換されるファイルのソースや設定の変更など、多くの要因に基づいてその結果を無効にしようとします。
デフォルト
Jest ships with one transformer out of the box - babel-jest. It will automatically load your project's Babel configuration and transform any file matching the following RegEx: /\.[jt]sx?$/ meaning any .js, .jsx, .ts and .tsx file. In addition, babel-jest will inject the Babel plugin necessary for mock hoisting talked about in ES Module mocking.
If you override the transform configuration option babel-jest will no longer be active, and you'll need to add it manually if you wish to use Babel.
Writing custom transformers
You can write your own transformer. The API of a transformer is as follows:
interface SyncTransformer<OptionType = unknown> {
/**
* Indicates if the transformer is capable of instrumenting the code for code coverage.
*
* If V8 coverage is _not_ active, and this is `true`, Jest will assume the code is instrumented.
* If V8 coverage is _not_ active, and this is `false`. Jest will instrument the code returned by this transformer using Babel.
*/
canInstrument?: boolean;
createTransformer?: (options?: OptionType) => SyncTransformer<OptionType>;
getCacheKey?: (
sourceText: string,
sourcePath: Config.Path,
options: TransformOptions<OptionType>,
) => string;
getCacheKeyAsync?: (
sourceText: string,
sourcePath: Config.Path,
options: TransformOptions<OptionType>,
) => Promise<string>;
process: (
sourceText: string,
sourcePath: Config.Path,
options: TransformOptions<OptionType>,
) => TransformedSource;
processAsync?: (
sourceText: string,
sourcePath: Config.Path,
options: TransformOptions<OptionType>,
) => Promise<TransformedSource>;
}
interface AsyncTransformer<OptionType = unknown> {
/**
* Indicates if the transformer is capable of instrumenting the code for code coverage.
*
* If V8 coverage is _not_ active, and this is `true`, Jest will assume the code is instrumented.
* If V8 coverage is _not_ active, and this is `false`. Jest will instrument the code returned by this transformer using Babel.
*/
canInstrument?: boolean;
createTransformer?: (options?: OptionType) => AsyncTransformer<OptionType>;
getCacheKey?: (
sourceText: string,
sourcePath: Config.Path,
options: TransformOptions<OptionType>,
) => string;
getCacheKeyAsync?: (
sourceText: string,
sourcePath: Config.Path,
options: TransformOptions<OptionType>,
) => Promise<string>;
process?: (
sourceText: string,
sourcePath: Config.Path,
options: TransformOptions<OptionType>,
) => TransformedSource;
processAsync: (
sourceText: string,
sourcePath: Config.Path,
options: TransformOptions<OptionType>,
) => Promise<TransformedSource>;
}
type Transformer<OptionType = unknown> =
| SyncTransformer<OptionType>
| AsyncTransformer<OptionType>;
interface TransformOptions<OptionType> {
/**
* If a transformer does module resolution and reads files, it should populate `cacheFS` so that
* Jest avoids reading the same files again, improving performance. `cacheFS` stores entries of
* <file path, file contents>
*/
cacheFS: Map<string, string>;
config: Config.ProjectConfig;
/** A stringified version of the configuration - useful in cache busting */
configString: string;
instrument: boolean;
// names are copied from babel: https://babeljs.io/docs/en/options#caller
supportsDynamicImport: boolean;
supportsExportNamespaceFrom: boolean;
/**
* The value is:
* - `false` if Jest runs without Node ESM flag `--experimental-vm-modules`
* - `true` if the file extension is defined in [extensionsToTreatAsEsm](Configuration.md#extensionstotreatasesm-arraystring)
* and Jest runs with Node ESM flag `--experimental-vm-modules`
*
* See more at https://jestjs.io/docs/27.x/ecmascript-modules
*/
supportsStaticESM: boolean;
supportsTopLevelAwait: boolean;
/** the options passed through Jest's config by the user */
transformerConfig: OptionType;
}
type TransformedSource =
| {code: string; map?: RawSourceMap | string | null}
| string;
// Config.ProjectConfig can be seen in code [here](https://github.com/jestjs/jest/blob/v26.6.3/packages/jest-types/src/Config.ts#L323)
// RawSourceMap comes from [`source-map`](https://github.com/mozilla/source-map/blob/0.6.1/source-map.d.ts#L6-L12)
As can be seen, only process or processAsync is mandatory to implement, although we highly recommend implementing getCacheKey as well, so we don't waste resources transpiling the same source file when we can read its previous result from disk. You can use @jest/create-cache-key-function to help implement it.
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 TransformedSource contains a source map, so it is possible to report line information accurately in code coverage and test errors. Inline source maps also work but are slower.
コーディング例
型チェック付きTypeScript
babel-jestはデフォルトでTypeScriptファイルをトランスパイルしますが、Babelはタイプを検証しません。 そうしたい場合は、 ts-jestを使うことができます。
画像をパスに変換する
画像のインポートは、ブラウザのバンドルに含める１つの方法ですが、有効なJavaScriptではありません。 Jestでこれを扱う一つの方法は、インポートされた値をそのファイル名で置き換えることです。
const path = require('path');
module.exports = {
process(src, filename, config, options) {
return `module.exports = ${JSON.stringify(path.basename(filename))};`;
},
};
module.exports = {
transform: {
'\\.(jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$':
'<rootDir>/fileTransformer.js',
},
};