はじめに

Next.jsでWebアプリケーションを開発していると、必ずぶつかる壁があります。それはデータベースのテスト環境をどう整えるかという問題です。

「本番環境と同じPostgreSQLでテストしたいけど、毎回手動でデータベースをリセットするのは面倒...」
「docker-composeでテスト用DBを立てているけど、テスト間でデータが残ってしまう...」
「CIでテストを回すときにデータベースの準備が大変...」

今回紹介するTestcontainersを使えば、これらの問題をすべて解決できます。テストのたびに自動的にクリーンなPostgreSQLコンテナが起動し、テスト終了後は自動で削除される——そんな理想的なテスト環境を構築していきます。

Testcontainersとは？

Testcontainersは、テスト実行時に動的にDockerコンテナを起動・管理するライブラリです。元々はJava向けに開発されましたが、現在はNode.js、Python、Go、.NETなど多くの言語で利用できます。

なぜTestcontainersが革命的なのか？

従来のテスト環境では以下のような問題がありました：

🔴 従来の問題点

手動でのデータベース準備が必要
テスト間でデータが残留する
開発者ごとに環境が異なる
CIでの環境構築が複雑

🟢 Testcontainersによる解決

テストごとに自動でクリーンなDBを用意
テスト終了後は自動でコンテナを削除
Dockerさえあればどこでも同じ環境
CIでもローカルでも同じコードでテスト可能

主な特徴

特徴	詳細
完全な分離	各テストで独立したコンテナを使用
自動管理	コンテナの起動・停止を自動化
本番同等環境	実際のPostgreSQLでテスト実行
言語サポート	Node.js、Java、Python等をサポート
CI/CD対応	GitHub Actions、Jenkins等で動作

今回構築するシステムの全体像

今回は、テストファイル名に対応するSQLファイルを自動で読み込む仕組みを構築します。例えば、users.test.tsを実行すると、自動的にusers.sqlが読み込まれて初期データが投入されます。

アーキテクチャ図

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   テストファイル  │───▶│  Testcontainers  │───▶│ PostgreSQLコンテナ │
│   (*.test.ts)   │    │                  │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│    SQLファイル   │    │   Jest/Vitest    │    │   自動クリーンアップ │
│   (初期データ)   │    │   (テストランナー) │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘

ディレクトリ構成

最終的には以下のような構成になります：

my-nextjs-app/
├── package.json
├── jest.config.js
├── sql/                       # テスト用SQLファイル
│   ├── users.sql             # ユーザー関連テスト用データ
│   └── posts.sql             # 投稿関連テスト用データ
├── tests/                     # テストファイル群
│   ├── setup/
│   │   ├── testcontainers.ts # Testcontainers設定
│   │   └── database.ts       # DB初期化処理
│   ├── users.test.ts         # ユーザー機能のテスト
│   └── posts.test.ts         # 投稿機能のテスト
└── src/                       # アプリケーションコード
    └── pages/

実装の流れ

ステップ1: 必要なパッケージのインストール

まず、プロジェクトに必要なパッケージをインストールします。

# Testcontainers関連
npm install --save-dev testcontainers

# テスト関連
npm install --save-dev jest ts-jest @types/jest

# PostgreSQL関連
npm install pg @types/pg

ステップ2: Jest設定

プロジェクトルートにjest.config.jsを作成し、Testcontainersを使うための設定を行います。重要なのは、セットアップファイルの指定とテストのタイムアウト設定です。Dockerコンテナの起動には時間がかかるため、十分な余裕を持たせましょう。

module.exports = {
  testEnvironment: 'node',
  setupFilesAfterEnv: ['<rootDir>/tests/setup/database.ts'],
  testMatch: ['<rootDir>/tests/**/*.test.ts'],
  testTimeout: 30000, // Dockerコンテナ起動を考慮
  verbose: true,
}

ステップ3: Testcontainers設定

tests/setup/testcontainers.tsでPostgreSQLコンテナの管理を行います。ここでは、コンテナの起動・停止と、データベースクライアントの管理を行います。

import { GenericContainer, Wait } from 'testcontainers';
import { Client } from 'pg';

let postgresContainer = null;
let dbClient = null;

export const startPostgresContainer = async () => {
  if (postgresContainer && dbClient) {
    return dbClient;
  }

  console.log('🐳 PostgreSQLコンテナを起動しています...');
  
  postgresContainer = await new GenericContainer('postgres:15-alpine')
    .withExposedPorts(5432)
    .withEnvironment({
      POSTGRES_PASSWORD: 'testpassword',
      POSTGRES_USER: 'testuser',
      POSTGRES_DB: 'testdb',
    })
    .withWaitStrategy(
      Wait.forLogMessage('database system is ready to accept connections', 2)
    )
    .start();

  dbClient = new Client({
    host: postgresContainer.getHost(),
    port: postgresContainer.getMappedPort(5432),
    user: 'testuser',
    password: 'testpassword',
    database: 'testdb',
  });

  await dbClient.connect();
  console.log('✅ データベースに接続しました');
  
  return dbClient;
};

ステップ4: データベース初期化処理

tests/setup/database.tsで、各テストの前後に実行される処理を定義します。ここが今回の核心部分で、テストファイル名に基づいてSQLファイルを自動で読み込む仕組みを実装します。

import { readFileSync, existsSync } from 'fs';
import path from 'path';
import { startPostgresContainer, stopPostgresContainer } from './testcontainers';

let testDbClient;

beforeAll(async () => {
  console.log('🚀 テスト環境をセットアップしています...');
  testDbClient = await startPostgresContainer();
}, 60000);

beforeEach(async () => {
  // データベースをリセット
  await testDbClient.query('DROP SCHEMA IF EXISTS public CASCADE');
  await testDbClient.query('CREATE SCHEMA public');
  
  // テストファイル名に対応するSQLファイルを読み込み
  const testFilePath = expect.getState().testPath;
  if (testFilePath) {
    const testFileName = path.basename(testFilePath, '.test.ts');
    const sqlFilePath = path.resolve(__dirname, '../../sql', `${testFileName}.sql`);
    
    if (existsSync(sqlFilePath)) {
      console.log(`📄 ${testFileName}.sql を読み込んでいます`);
      const sqlContent = readFileSync(sqlFilePath, 'utf8');
      await testDbClient.query(sqlContent);
    }
  }
}, 30000);

afterAll(async () => {
  console.log('🧹 テスト環境をクリーンアップしています...');
  await stopPostgresContainer();
}, 30000);

export const getTestDbClient = () => testDbClient;

ステップ5: SQLファイルの準備

各テストに対応するSQLファイルをsql/ディレクトリに配置します。ファイル名は「テストファイル名.sql」の形式にします。

sql/users.sql

CREATE TABLE IF NOT EXISTS users (
  id SERIAL PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  name VARCHAR(100) NOT NULL,
  age INTEGER,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

INSERT INTO users (email, name, age) VALUES 
  ('alice@example.com', 'Alice Johnson', 28),
  ('bob@example.com', 'Bob Smith', 35),
  ('charlie@example.com', 'Charlie Brown', 22);

sql/posts.sql

CREATE TABLE IF NOT EXISTS users (
  id SERIAL PRIMARY KEY,
  name VARCHAR(100) NOT NULL
);

CREATE TABLE IF NOT EXISTS posts (
  id SERIAL PRIMARY KEY,
  title VARCHAR(200) NOT NULL,
  content TEXT,
  user_id INTEGER REFERENCES users(id),
  published BOOLEAN DEFAULT false
);

INSERT INTO users (name) VALUES ('Author One'), ('Author Two');
INSERT INTO posts (title, content, user_id, published) VALUES 
  ('First Post', 'Content of first post', 1, true),
  ('Draft Post', 'Content of draft', 2, false);

ステップ6: テストコードの作成

最後に、実際のテストコードを書きます。データベースクライアントを取得して、通常のSQLクエリでテストを行います。

tests/users.test.ts

import { getTestDbClient } from './setup/database';

describe('ユーザー機能のテスト', () => {
  
  test('初期データが正しく挿入されていること', async () => {
    const client = getTestDbClient();
    const result = await client.query('SELECT * FROM users');
    
    expect(result.rows).toHaveLength(3);
    expect(result.rows[0].name).toBe('Alice Johnson');
  });

  test('新しいユーザーを作成できること', async () => {
    const client = getTestDbClient();
    
    await client.query(
      'INSERT INTO users (email, name, age) VALUES ($1, $2, $3)',
      ['eve@example.com', 'Eve Wilson', 27]
    );
    
    const result = await client.query('SELECT COUNT(*) as count FROM users');
    expect(parseInt(result.rows[0].count)).toBe(4);
  });

  test('メールアドレスの重複制約が機能すること', async () => {
    const client = getTestDbClient();
    
    await expect(
      client.query(
        'INSERT INTO users (email, name, age) VALUES ($1, $2, $3)',
        ['alice@example.com', 'Another Alice', 25]
      )
    ).rejects.toThrow();
  });
});

tests/posts.test.ts

import { getTestDbClient } from './setup/database';

describe('投稿機能のテスト', () => {

  test('投稿一覧を取得できること', async () => {
    const client = getTestDbClient();
    const result = await client.query(`
      SELECT p.*, u.name as author_name
      FROM posts p
      JOIN users u ON p.user_id = u.id
      ORDER BY p.id
    `);
    
    expect(result.rows).toHaveLength(2);
    expect(result.rows[0].title).toBe('First Post');
    expect(result.rows[0].author_name).toBe('Author One');
  });

  test('公開済み投稿のみ取得できること', async () => {
    const client = getTestDbClient();
    const result = await client.query(
      'SELECT * FROM posts WHERE published = true'
    );
    
    expect(result.rows).toHaveLength(1);
    expect(result.rows[0].title).toBe('First Post');
  });
});

実際の動作

テストを実行すると、以下のような流れで動作します：

テスト開始: PostgreSQLコンテナが自動で起動
各テスト前: データベースがリセットされ、対応するSQLファイルが読み込まれる
テスト実行: クリーンな状態でテストが実行される
テスト終了: コンテナが自動で停止・削除される

npm test

# 出力例:
# 🐳 PostgreSQLコンテナを起動しています...
# ✅ データベースに接続しました
# 📄 users.sql を読み込んでいます
# ✅ ユーザー機能のテスト > 初期データが正しく挿入されていること
# 📄 posts.sql を読み込んでいます  
# ✅ 投稿機能のテスト > 投稿一覧を取得できること
# 🧹 テスト環境をクリーンアップしています...

この仕組みのメリット

1. 開発体験の向上

テストごとに必要なデータを個別に定義できる
SQLファイルなので、データベース管理ツールでそのまま実行可能
複雑なテストデータも簡単に作成できる

2. 保守性の向上

テストデータがコードと分離されているため見通しが良い
SQLファイルを使い回すことで、開発環境でも同じデータを使用可能
データベーススキーマの変更時も、SQLファイルを更新するだけ

3. チーム開発での一貫性

Dockerさえあれば、どの環境でも同じテスト結果が得られる
CI/CDパイプラインでも同じ仕組みが動作する
新しいメンバーも特別な環境構築なしでテストを実行可能

4. 本番環境に近いテスト

実際のPostgreSQLを使用するため、SQLiteなどでは検出できない問題も発見可能
インデックスや制約の動作も正確にテストできる
パフォーマンステストも可能

注意点とベストプラクティス

パフォーマンスに関する注意点

Dockerコンテナの起動には時間がかかるため、以下の点に注意しましょう：

テスト分割: あまりに細かくテストを分けすぎると、総実行時間が長くなる
beforeAll/afterAll: 可能な限りコンテナの起動回数を減らす設計にする
CI環境: GitHub ActionsなどのCI環境では、Dockerの並列実行に注意

セキュリティの考慮

テスト環境では以下の点に注意してください：

テスト用のクレデンシャルは本番環境と完全に分離する
SQLファイルには機密情報を含めない
本番データベースへの接続は絶対に行わない

SQLファイルの管理

命名規則: テストファイル名と対応させる規則を徹底する
バージョン管理: SQLファイルもGitで管理し、スキーマ変更を追跡する
再利用性: 共通部分は別ファイルに分離して include する仕組みを検討

発展的な活用方法

1. マイグレーションとの連携

実際のプロジェクトでは、マイグレーションファイルと組み合わせることが多いでしょう。以下のような仕組みも検討できます：

// マイグレーション実行後にテストデータを投入
beforeEach(async () => {
  await runMigrations(client);  // マイグレーション実行
  await loadTestData(client);   // テストデータ投入
});

2. 複数データベースのテスト

マイクロサービス構成の場合は、複数のデータベースコンテナを並行して起動することも可能です：

const userDbContainer = await new GenericContainer('postgres:15-alpine')...
const orderDbContainer = await new GenericContainer('postgres:15-alpine')...

3. Next.js APIとの統合テスト

Next.js APIルートと組み合わせることで、エンドツーエンドに近いテストも実現できます：

test('API経由でユーザー作成ができること', async () => {
  const response = await fetch('/api/users', {
    method: 'POST',
    body: JSON.stringify({ name: 'Test User', email: 'test@example.com' })
  });
  
  expect(response.status).toBe(201);
  
  // データベースを直接確認
  const client = getTestDbClient();
  const result = await client.query('SELECT * FROM users WHERE email = $1', ['test@example.com']);
  expect(result.rows).toHaveLength(1);
});

まとめ

Testcontainers と SQLファイルの組み合わせは、Next.js + PostgreSQL のテスト環境構築において非常に強力な手法です。

この仕組みの最大の価値は「開発者体験の向上」です。 テストを書くのが楽しくなり、結果的により品質の高いアプリケーションを開発できるようになります。

特に、テストファイル名とSQLファイル名を対応させる仕組みは、直感的で分かりやすく、チーム開発での混乱を避けることができます。

参考リンク