Jest を利用してテストを実行していると、突然以下のようなエラーに遭遇することがあります。
Test suite failed to run
SyntaxError: Unexpected token 'export'
これは特に ESM モジュールを読み込んでいる場合 に頻発するエラーです。従来の CommonJS 環境では問題なく動作していたコードが、ESM 化に伴って Jest 上で動かなくなるケースは多くの開発者が経験しているでしょう。
本記事では、このエラーの原因と解決方法について技術者向けに整理します。実際の設定例やコードも交えて解説します。
1. エラーの背景
Jest は長らく CommonJS を前提に設計されており、ESM（ECMAScript Modules）の完全サポートは比較的新しい機能です。
そのため、プロジェクト内に export を含む ESM モジュールが存在すると、Jest がデフォルトのままでは解釈できずエラーを投げます。特に node_modules 内のパッケージや、type: "module" を指定している場合にこの問題が顕在化します。多くの場合、Babel を通じて ESM をトランスパイルするか、Jest の transform 設定で適切に扱う必要があります。
2. よくある発生パターン
実際にこのエラーが出る典型的なパターンを挙げます。
package.jsonに"type": "module"を指定しているプロジェクトでテスト実行- ESM を前提とした外部ライブラリをインポートしている
- Jest の transform 設定が存在せず、素の ESM を読み込んでしまっている
babel-jestが導入されていない、あるいは設定されていない
これらのケースでは、Jest が export を含むファイルをそのまま解釈しようとして失敗します。そのため、どのモジュールを変換する必要があるのか を把握して対処することが重要です。
3. 解決方法: Babel と transform の設定
もっとも一般的な解決策は、babel-jest を導入して transform 設定を追加することです。これにより Jest 実行時に ESM を適切に変換して解釈させることができます。
まず babel-jest をインストールします。
npm install --save-dev babel-jest @babel/core @babel/preset-env
次に、プロジェクトルートに .babelrc または babel.config.js を配置します。
{
"presets": ["@babel/preset-env"]
}
その後、jest.config.js を以下のように設定します。
module.exports = {
transform: {
"^.+\\.[t|j]sx?$": "babel-jest"
}
};
これで Jest は ESM ファイルを Babel 経由で解釈するようになります。
4. NodeNext / ts-jest を利用する場合
TypeScript を利用しているプロジェクトでは、ESM サポートがさらに複雑になります。ts-jest を導入している場合は、以下のように設定します。
npm install --save-dev ts-jest @types/jest
tsconfig.jsonに以下のように指定します。
// jest.config.js
module.exports = {
preset: 'ts-jest',
testEnvironment: 'node',
extensionsToTreatAsEsm: ['.ts'],
globals: {
'ts-jest': {
useESM: true
}
}
};
さらに、tsconfig.json では以下を指定します。
{
"compilerOptions": {
"module": "NodeNext",
"moduleResolution": "NodeNext"
}
}
これにより TypeScript で書かれた ESM モジュールも Jest 上で正しく扱えるようになります。
5. よくある落とし穴と追加対処法
node_modules内の一部ライブラリは ESM 形式のみを提供しているため、Jest が解釈できずにエラーを出すことがあります。その場合はtransformIgnorePatternsを調整して特定のパッケージを変換対象に含める必要があります。- Babel 設定が二重になっていると、意図せずトランスパイルされないファイルが発生するケースがあります。必ずプロジェクト全体で設定を一貫させることが重要です。
- Jest のバージョンが古い場合、ESM サポート自体が不十分であり、最新のバージョンに更新することで解決する場合もあります。
これらの落とし穴は特に大規模プロジェクトで顕著に現れるため、チーム内で設定を共有しておくことが推奨されます。
6. まとめ
本記事では、Jest 実行時に発生する 「Unexpected token ‘export’」エラー の原因と解決策を解説しました。
- Jest はデフォルトで CommonJS 前提のため、ESM をそのまま解釈できない
babel-jestを導入して transform 設定を追加するのが基本的な対処法- TypeScript プロジェクトでは
ts-jestとNodeNext設定を組み合わせる - 一部ライブラリは transformIgnorePatterns の調整が必要になる
最終的に、このエラーは 「どのファイルを Jest にどう解釈させるか」 の問題です。適切な設定を行うことで安定したテスト環境を構築できます。
参考
- Jest 公式ドキュメント [https://jestjs.io/docs/ecmascript-modules]
- ts-jest ドキュメント [https://kulshekhar.github.io/ts-jest/]
- Babel-jest ドキュメント [https://github.com/facebook/jest/tree/main/packages/babel-jest]
