JestでECMAScript Modulesをテストする

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

Takahiro Iwasa

2024-02-24

7 min read

Jestを使ってECMAScript Modules (ESM) をテストしていると、次のようなエラーに遭遇することがあります。

SyntaxError: Cannot use import statement outside a module

これは対象のモジュールがimportキーワードを使用していることが原因です。幸い、Jestはこうしたエラーを解消するためのESMの実験的サポートを提供しています。

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モジュールはECMAScript Module (ESM) であり、エクスポートにexportキーワードを使用しています。これはnode_modules/hast-util-from-html/index.jsにあるファイルを確認することで分かります。以下はそのモジュールのエクスポート構造の抜粋です。

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起動フラグという4つの異なるレイヤーにまたがる変更が必要でした。これは、「type: moduleを追加するだけ」では元のエラーが解決しない理由をよく表しています。.js拡張子のためのmoduleNameMapperの書き換えは忘れやすく、後になって誤診断されやすい部分でもあります。TypeScriptのソースコードでは拡張子なしでインポートする一方、コンパイル後のESM出力では拡張子が必要になるためです。このマッピングを削除してしまうと、元のSyntaxErrorとはまったく異なる形で失敗するため、なぜそこにあるのかを文書化しておく価値があります。

記事一覧に戻る