next

Edit

コードの変換

Jest はプロジェクト内のコードを JavaScript として実行しますが、Node.js でサポートされていない構文 (JSX、TypeScript の型、Vue のテンプレートなど) を使用している場合は、ブラウザ用にビルドする場合と同様に、コードをプレーンな JavaScript に変換する必要があります。

Jest は、このような変換を transform 設定オプションによりサポートしています。

transformerはソースファイルを変換する同期処理を行う関数を提供するモジュールです。 たとえば、まだ Node ではサポートされていない新しい言語の機能をモジュールやテストで使用したい場合、将来の JavaScript のバージョンを現在のバージョンのものに変換する多くのコンパイラの中の1つをプラグインとして利用するでしょう。

Jest は変換の結果をキャッシュし、変換されるファイルのソースや設定の変更など、多くの要因に基づいてその結果を無効にしようとします。

デフォルト

Jest は、babel-jest と呼ばれる transformer を初めから同梱しています。 これは、プロジェクトの Babel の設定を自動的に読み込み、/\.[jt]sx?$/ という正規表現に一致するすべてのファイルを変換します。つまり、.js、.jsx、.ts、.tsx で終わるすべてのファイルです。 さらに、babel-jest は ES Module moking で説明した mock hoisting に必要な Babel プラグインを追加します。

transform 設定オプションをオーバーライドした場合、 babel-jest は無効になります。 その場合、Babel を使いたい場合には手動で追加する必要があります。

カスタムの transformer を書く

自分自身でも transformer を書けます。 transformer の API は以下のとおりです。

interface Transformer<OptionType = unknown> {
  /**
   * Indicates if the transformer is capabale 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) => Transformer;

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

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

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;
  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 in code [here](https://github.com/facebook/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 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.

Note that 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.

コーディング例

型チェック付き TypeScript

babel-jest はデフォルトで TypeScript ファイルをトランスパイルしますが、Babel は型検証を行いません。 型検証を行いたい場合は、 ts-jest を利用できます。

画像をパスに変換する

画像のインポートはブラウザ向けバンドルに画像をインクルードする方法の1つですが、それらは有効な JavaScript ではありません。 Jest でこれを扱う方法の1つは、インポートされた値をそのファイル名で置き換えることです。

// fileTransformer.js
const path = require('path');

module.exports = {
  process(src, filename, config, options) {
    return 'module.exports = ' + JSON.stringify(path.basename(filename)) + ';';
  },
};

// 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',
  },
};
← Environment Variables