Testcontainersでコンテナ間テストを試したら良かったと感じた話

GET /users

Response:
[
  {
    "email": "yamada@example.com",
    "displayName": "山田 太郎",
    "department": "A課"
  },
  {
    "email": "suzuki@example.com",
    "displayName": "鈴木 花子",
    "department": "B課"
  }
]

POST /users

Request Payload:
[
  {
    "email": "yamada@example.com",
    "displayName": "山田 太郎",
    "department": "A課"
  },
  {
    "email": "suzuki@example.com",
    "displayName": "鈴木 花子",
    "department": "B課"
  }
]

SELECT u.email, u.display_name, d.name AS department
FROM users u
JOIN departments d ON u.department_id = d.id
WHERE u.email = '...';

services:
  # DB
  db:
    image: postgres:18-alpine
    environment:
      POSTGRES_USER: testuser
      POSTGRES_PASSWORD: testpass
      POSTGRES_DB: testdb
      TZ: Asia/Tokyo
    volumes:
      - ./db/init.sql:/docker-entrypoint-initdb.d/init.sql:ro
    ports:
      - "5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U testuser -d testdb"]
      interval: 2s
      start_period: 5s

  # 外部API モック
  external-api-mock:
    build:
      context: ./external-api-mock
    environment:
      TZ: Asia/Tokyo
      PORT: "3000"
    ports:
      - "3000"
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:3000/users"]
      interval: 2s

  # バックエンドAPI
  api:
    build:
      context: ./api
    environment:
      TZ: Asia/Tokyo
      PORT: "3000"
      DATABASE_URL: postgresql://testuser:testpass@db:5432/testdb
    ports:
      - "3000"
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:3000/health"]
      interval: 2s

  # バッチ
  # バッチはジョブ実行型のため `healthcheck` を定義せず、Testcontainers の `Wait.forLogMessage` で完了ログを検知して次の処理に進みます
  batch:
    build:
      context: ./batch
    environment:
      TZ: Asia/Tokyo
      EXTERNAL_API_URL: http://external-api-mock:3000
      API_BASE_URL: http://api:3000
    depends_on:
      api:
        condition: service_healthy
      external-api-mock:
        condition: service_healthy

import { describe, it, expect, beforeAll, afterAll } from "vitest";
import {
  DockerComposeEnvironment,
  Wait,
  type StartedDockerComposeEnvironment,
} from "testcontainers";
import { Pool } from "pg";

let environment: StartedDockerComposeEnvironment;
let pool: Pool;

beforeAll(async () => {
  // 1. Testcontainers が Docker Compose でコンテナを起動
  // 2. テストしたいシナリオを実行（バッチコンテナ起動時に自動的にシナリオが実行される）
  // `withBuild()` は `docker compose up --build` に相当します。最新のイメージからコンテナを作成したいため、毎回ビルドを行っています。
  environment = await new DockerComposeEnvironment(".", "compose.test.yaml")
    .withBuild()
    .withWaitStrategy("batch-1", Wait.forLogMessage(/sync completed/))
    .up();

  const dbContainer = environment.getContainer("db-1");
  const dbPort = dbContainer.getMappedPort(5432);
  pool = new Pool({
    connectionString: `postgresql://testuser:testpass@localhost:${dbPort}/testdb`,
  });
});

afterAll(async () => {
  await pool?.end();
  await environment?.down();
});

// 3. テストコードを実行
describe("バッチ実行後のDB検証", () => {
  it.each([
    { email: "yamada@example.com", displayName: "山田 太郎", department: "A課" },
    { email: "suzuki@example.com", displayName: "鈴木 花子", department: "B課" },
  ])(
    "$email のユーザーが登録されていることを確認",
    async ({ email, displayName, department }) => {
      const result = await pool.query(
        `SELECT u.email, u.display_name, d.name AS department
         FROM users u
         JOIN departments d ON u.department_id = d.id
         WHERE u.email = $1`,
        [email],
      );

      expect(result.rows).toHaveLength(1);
      expect(result.rows[0].display_name).toBe(displayName);
      expect(result.rows[0].department).toBe(department);
    },
  );
});

% npx vitest run

 RUN  v2.1.9 /path/to/blog-2026-04

 ✓ tests/integration/batch.integration.test.ts (2) 45656ms
   ✓ バッチ実行後のDB検証 (2)
     ✓ 'yamada@example.com' のユーザーが登録されていることを確認
     ✓ 'suzuki@example.com' のユーザーが登録されていることを確認

 Test Files  1 passed (1)
      Tests  2 passed (2)
   Start at  17:01:54
   Duration  46.20s (transform 17ms, setup 0ms, collect 287ms, tests 45.66s, environment 0ms, prepare 39ms)