Jest で ECMAScript Modules をテストする

package.json、TypeScript、Jest の設定を連携させ、Jest の "Cannot use import statement outside a module" エラーを解消する方法を紹介します。

Takahiro Iwasa

2024-02-24

6 min read

Jest を使って ECMAScript Modules (ESM) をテストすると、次のエラーが発生することがあります。

SyntaxError: Cannot use import statement outside a module

これは、Jest が import を含むファイルを CommonJS として実行した場合に発生します。Jest は ESM の実験的サポートを提供していますが、Node.js、TypeScript、Jest の各設定で一貫して有効にする必要があります。

ESM パッケージの作成

まず、次のコマンドで新しい ESM パッケージを作成します。

mkdir jest-esm && cd jest-esm
npm init -y

必要な開発用依存関係をインストールします。

npm i -D typescript jest @types/jest ts-node ts-jest

package.json に "type": "module" を追加します。

package.json は次のようになります。

1
{
2
  "name": "jest-esm",
3
  "version": "1.0.0",
4
  "description": "",
5
  "main": "index.js",
6
  "type": "module",
7
  "scripts": {
8
    "test": "echo \"Error: no test specified\" && exit 1"
9
  },
10
  "author": "",
11
  "license": "ISC",
12
  "devDependencies": {
13
    "@types/jest": "^29.5.12",
14
    "jest": "^29.7.0",
15
    "ts-jest": "^29.1.2",
16
    "ts-node": "^10.9.2",
17
    "typescript": "^5.3.3"
18
  }
19
}

TypeScript の設定

次のコマンドで tsconfig.json ファイルを生成します。

npx tsc --init

tsconfig.json ファイルを更新します。

1
@@ -14 +14 @@
2
-    "target": "es2016",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
3
+    "target": "es6",                                     /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
4
@@ -28 +28 @@
5
-    "module": "commonjs",                                /* Specify what module code is generated. */
6
+    "module": "es6",                                     /* Specify what module code is generated. */
7
@@ -30 +30 @@
8
-    // "moduleResolution": "node10",                     /* Specify how TypeScript looks up a file from a given module specifier. */
9
+    "moduleResolution": "node",                          /* Specify how TypeScript looks up a file from a given module specifier. */

Jest の設定

次のコマンドを実行して Jest の設定を作成します。

“test” スクリプトに Jest を使用する: Yes
設定に TypeScript を使用する: Yes
テスト環境: jsdom
カバレッジレポートを追加する: No
カバレッジのプロバイダー: v8
モック呼び出しを自動的にクリアする…: No

npm init jest@latest

生成された jest.config.ts を次のように編集します。

1
// preset: undefined,
2
preset: 'ts-jest',

ESM のサポート

Node.js の実験的な VM モジュールを有効にするため、package.json の test スクリプトを更新します。

1
"scripts": {
2
   "test": "jest"
3
   "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
4
}

Jest が ESM として扱うファイルの拡張子を指定するため、jest.config.ts に extensionsToTreatAsEsm を追加します。

1
extensionsToTreatAsEsm: ['.ts'],

ts-jest での ESM 設定については、公式ドキュメントを参照してください。

.js 拡張子を扱うため、jest.config.ts に moduleNameMapper を追加します。

1
// moduleNameMapper: {},
2
moduleNameMapper: {
3
  '^(\\.{1,2}/.*)\\.js$': '$1',
4
},

ESM をサポートするように transform 設定を更新します。

1
// transform: undefined,
2
transform: {
3
  '^.+\\.tsx?$': [
4
    'ts-jest',
5
    {
6
      useESM: true,
7
    },
8
  ],
9
},

ESM モジュールの作成

動作確認用に、hast-util-from-html パッケージをインストールします。

npm i hast-util-from-html

hast-util-from-html は ESM 専用のパッケージです。node_modules/hast-util-from-html/index.js を確認すると、ESM 構文でエクスポートされていることが分かります。

1
/**
2
 * @typedef {import('hast-util-from-parse5')} DoNotTouchItRegistersData
3
 *
4
 * @typedef {import('./lib/index.js').ErrorCode} ErrorCode
5
 * @typedef {import('./lib/index.js').ErrorSeverity} ErrorSeverity
6
 * @typedef {import('./lib/index.js').OnError} OnError
7
 * @typedef {import('./lib/index.js').Options} Options
8
 */
9

10
export { fromHtml } from './lib/index.js';

index.ts を作成します。

1
import { fromHtml } from 'hast-util-from-html';
2

3
export default function JestEsm(): void {
4
  const root = fromHtml(
5
    '<span><a href="https://github.com">GitHub</a></span>',
6
    { fragment: true }
7
  );
8
  console.info(root);
9
}

ESM のテスト

index.spec.ts を作成します。

1
import JestEsm from './index';
2

3
test('case1', () => {
4
  JestEsm();
5
});

テストを実行します。

npm run test

次のようなエラーが表示された場合、

1
● Validation Error:
2

3
  Test environment jest-environment-jsdom cannot be found. Make sure the testEnvironment configuration option points to an existing node module.
4

5
  Configuration Documentation:
6
  https://jestjs.io/docs/configuration
7

8

9
As of Jest 28 "jest-environment-jsdom" is no longer shipped by default, make sure to install it separately.

不足しているパッケージをインストールします。

npm i -D jest-environment-jsdom

再度テストを実行します。

npm run test

期待される出力は次の通りです。

1
 PASS  ./index.spec.ts
2
  ✓ case1 (20 ms)
3

4
Test Suites: 1 passed, 1 total
5
Tests:       1 passed, 1 total
6
Snapshots:   0 total
7
Time:        1 s
8
Ran all test suites.

まとめ

package.json、TypeScript、Jest を連携させて設定すると、実際の ESM パッケージをインポートするテストが SyntaxError: Cannot use import statement outside a module で失敗せず、正常に通るようになりました。

このテストを通すには、package.json の type フィールド、TypeScript のモジュール設定、Jest 自体の設定、実験的 VM モジュール用の Node.js 起動フラグという 4 つの設定をそろえる必要があります。type: module を追加するだけでは、元のエラーは解消しません。

moduleNameMapper の規則は、相対インポートの .js 接尾辞を取り除き、対応する TypeScript ソースを Jest が解決できるようにします。テスト環境における ESM 形式のインポート解決に固有の回避策なので、別のプロジェクトでも使う場合は、その目的を記録しておくとよいでしょう。

記事一覧に戻る