Jest で「Your test suite must contain at least one test」エラー

2025.10.26

Jest を使ってテストを実行したとき、以下のようなメッセージが表示されて困ったことはないでしょうか？

Your test suite must contain at least one test.

このエラーは、Jest がテストを1件も検出できなかったときに出るメッセージです。テストフレームワークが正常に動いていても、実際にテスト関数 (test() または it()) が定義されていない、あるいは テストファイルそのものが認識されていない 状況で発生します。

本記事では、このエラーの原因を整理し、設定ミス・命名規則・TypeScript 環境・CI 実行時の挙動など、技術者が陥りやすい落とし穴とその解決法を詳しく解説します。

目次

1. エラーの基本的な意味と発生条件

このエラーが出るのは、Jest が「テストファイルは実行したが、内部にテストケースが存在しない」と判断した場合です。
実際には以下のようなケースで発生します。

  • ファイル名が Jest のテスト検出パターンに合致していない
  • test() / it() 関数を定義していない
  • テストがコメントアウトされている
  • TypeScript の設定により .spec.ts がビルド対象外
  • テストが非同期で実行されず、途中でスキップされている

例えば、以下のようなコードは Jest から見ると「空のテスト」と見なされます。

// sample.spec.js
describe('Sample Test Suite', () => {
  // テストケースを書き忘れている
})

この場合、テストスイート (describe) 自体は検出されますが、内部に test() がないため上記エラーが出ます。

2. 命名規則のミスによるテスト未検出

Jest はデフォルトで、以下のパターンにマッチするファイルのみをテストとして認識します。

  • *.test.js
  • *.spec.js
  • __tests__ ディレクトリ配下のファイル

TypeScript 環境で .ts や .tsx を使っている場合、設定によってはこれらが無視されることがあります。
たとえば、次のような構成だと Jest が .ts ファイルを検出できません。

src/
  ├── components/
  │    └── Button.tsx
  └── tests/
       └── Button.test.ts

jest.config.js にテスト拡張子を明示することで、この問題を防げます。

// jest.config.js
module.exports = {
  testMatch: ['**/?(*.)+(spec|test).[jt]s?(x)'],
  transform: {
    '^.+\\.[tj]sx?$': 'babel-jest'
  }
}

この設定により、.js, .jsx, .ts, .tsx ファイルがすべて検出対象になります。

よくある間違い例

  • ファイル名を test_sample.js にしてしまい、*.test.js とマッチしない
  • tests ディレクトリを test と singular にして Jest のルールから外れる
  • CI 環境で jest --testPathPattern オプションを付けてしまい、テスト対象外になる

3. 空のテストスイートが原因の場合

実際に describe ブロックを使っていても、内部にテストがなければ同様にエラーが出ます。

describe('Math operations', () => {
  // 何も書いていない
})

Jest のルール上、最低でも1つの test() または it() 関数を含める必要があります。

修正版は以下のようになります。

describe('Math operations', () => {
  test('adds numbers correctly', () => {
    expect(1 + 2).toBe(3)
  })
})

また、非同期テストの場合に Promise が返されない と Jest が「テストが実行されなかった」と誤解するケースもあります。

test('fetch data', async () => {
  fetch('/api/data') // await が抜けているため完了前に終了
})

このような場合は await を付けることで正常に認識されます。

test('fetch data', async () => {
  const res = await fetch('/api/data')
  expect(res.ok).toBe(true)
})

4. TypeScript + ts-jest 環境での設定不備

TypeScript を利用している場合、コンパイル対象の設定 (tsconfig.json) によっては Jest がファイルを読み取れず、結果として「テストが存在しない」と誤認するケースがあります。

よくある設定ミス

  • "include" に tests/ ディレクトリを含めていない
  • "exclude" に **/*.spec.ts が含まれている
  • ts-jest の設定を忘れている

次のように設定を見直しましょう。

// jest.config.js
module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  testMatch: ['**/?(*.)+(spec|test).[tj]s?(x)']
}

// tsconfig.json
{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es2020",
    "strict": true
  },
  "include": ["src", "tests"]
}

これで Jest が .ts テストを正しく解釈できるようになります。

5. CI / Docker 環境で発生する特殊ケース

CI/CD 環境（GitHub Actions、Docker、Jenkins など）では、テストパス指定やキャッシュの影響でファイルがスキップされることがあります。

たとえば、Docker イメージ内で実行するときに .spec.ts ファイルが .dockerignore で除外されていると、テストがゼロ扱いになります。

確認ポイント

  • .dockerignore に tests/ や *.spec.ts が入っていないか
  • CI のコマンドが jest tests/unit/ のように限定されすぎていないか
  • Jest の --findRelatedTests オプションを使っていないか

対策としては、jest --passWithNoTests を一時的に利用し、まずテスト検出状況を確認します。

npx jest --passWithNoTests --verbose

どのファイルがテストとして認識されているかをログで確認し、そこからファイル名や設定を修正しましょう。

6. 実務でのチェックリスト

Jest のテストが 1 件も認識されない場合、まず以下の手順で確認してください。

  1. テスト関数 (test() or it()) が存在するか
  2. ファイル名が .test.js / .spec.ts の形式か
  3. Jest の testMatch 設定が正しいか
  4. tsconfig.json に tests/ が含まれているか
  5. CI/Docker でテストファイルが除外されていないか

このチェックで 90%以上のケースは解決します。

もしどうしても検出されない場合は、Jest のバージョンやプリセット（babel-jest, ts-jest）を明示的にアップデートすることをおすすめします。

npm install --save-dev jest@latest ts-jest@latest

バージョン差による設定の初期値変更（特に testRegex）もあるため、Jest の公式ドキュメントを確認しておくとよいでしょう。

まとめ

「Your test suite must contain at least one test」エラーは、Jest が「テストを検出したが中にテスト関数がない」または「そもそもファイルが見つからない」場合に発生します。
最も多い原因は命名規則や設定ファイルの不整合であり、ファイル拡張子・testMatch の設定・TypeScript の include 設定を見直せば解消します。
CI や Docker 環境では .dockerignore や実行ディレクトリにも注意し、テスト検出ログで挙動を確認することが重要です。

参考

タイトルとURLをコピーしました