Testcontainersを利用し実際のデータベースを用いたテストを並列実行する

自分はDBをモックしてテストを行うのが嫌いですが、もし実際のDBを利用し並列実行する場合にポートやtruncate周りの問題が発生します。今回は、それを解決するためにTestcontainersとVitestを利用したコードで解決します。

Testcontiners

Docker社が買収したTestcontainersは、Dockerコンテナをテストで利用しやすくするライブラリです。開発時にdocker composeを利用している人が多いと思うので、そこで利用しているcompose.yamlの定義をまんまテストで再利用できる点も便利かなと思います。

Testcontainers

Testcontainers is an opensource library for providing lightweight, throwaway instances of common databases, Selenium web browsers, or anything else that can run in a Docker container.

testcontainers.com

ポート衝突の問題

一般的に開発時は固定のポートを利用するため、テストを並列で実行する場合にポートが衝突する問題が発生します。

なので、${DATABASE_PORT:-5432}:5432と書くことによりDATABASE_PORTという環境変数を尊重し、ない場合はデフォルトのポートを参照するように変更します。これにより、普段の開発時にはDATABASE_PORTを指定せず、テスト実行時だけそれぞれのテストスイートが実行時に指定できるようになります。

1
services:
2
  db:
3
    image: postgres:17
4
    ports:
5
      - ${DATABASE_PORT:-5432}:5432
6
    environment:
7
      - POSTGRES_USER=${DATABASE_USER}
8
      - POSTGRES_PASSWORD=${DATABASE_PASSWORD}
9
      - POSTGRES_DB=${DATABASE_DB}

この環境変数をTestcontainersでコンテナ起動時に上書きすることによりポートを動的に切り替えます。

1
// https://github.com/hiroppy/web-app-template/blob/main/tests/db.setup.ts
2

3
import { exec } from "node:child_process";
4
import { promisify } from "node:util";
5
import { Prisma, PrismaClient } from "@prisma/client";
6
import { DockerComposeEnvironment, Wait } from "testcontainers";
7
import { createDBUrl } from "../src/app/_utils/db";
8

9
const execAsync = promisify(exec);
10

11
const container = await new DockerComposeEnvironment(".", "compose.yml")
12
  .withEnvironmentFile(".env.test")
13
  .withEnvironment({
14
    DATABASE_PORT: port === "random" ? "0" : `${port}`, // 環境変数を差し込み、ポートを動的に変更
15
  })
16
  .withWaitStrategy("db", Wait.forListeningPorts())
17
  .up(["db"]);
18
const dbContainer = container.getContainer("db-1");
19
// これで実際にhost側にbindされたランダムなポートを得る
20
const mappedPort = dbContainer.getMappedPort(5432);
21
const url = createDBUrl({
22
  host: dbContainer.getHost(),
23
  port: mappedPort,
24
});
25

26
// migration
27
await execAsync(`DATABASE_URL=${url} npx prisma db push`);
28

29
const prisma = new PrismaClient({
30
  datasources: {
31
    db: {
32
      // prisma clientの初期URLはschemaに書かれたものなので上書きする必要がある
33
      url,
34
    },
35
  },
36
});

これにより、prismaのクライアント自体もURLを切り替えた状態で作成でき、テスト内ではこのクライアントを利用します。そしてそれぞれのテストスイート事にDBが隔離され、安全に並列実行できるようになります。

実際のコード例

compose.yml

1
volumes:
2
  db-data:
3

4
services:
5
  db:
6
    image: postgres:17
7
    ports:
8
      - ${DATABASE_PORT:-5432}:5432
9
    environment:
10
      - POSTGRES_USER=${DATABASE_USER}
11
      - POSTGRES_PASSWORD=${DATABASE_PASSWORD}
12
      - POSTGRES_DB=${DATABASE_DB}

db.setup.ts

これはunitだけでなく、e2eでも利用可能なので自分は汎用的にしています。

1
import { exec } from "node:child_process";
2
import { promisify } from "node:util";
3
import { Prisma, PrismaClient } from "@prisma/client";
4
import { DockerComposeEnvironment, Wait } from "testcontainers";
5
import { createDBUrl } from "../src/app/_utils/db";
6

7
const execAsync = promisify(exec);
8

9
export async function setupDB({ port }: { port: "random" | number }) {
10
  const container = await new DockerComposeEnvironment(".", "compose.yml")
11
    .withEnvironmentFile(".env.test")
12
    // overwrite environment variables
13
    .withEnvironment({
14
      DATABASE_PORT: port === "random" ? "0" : `${port}`,
15
    })
16
    .withWaitStrategy("db", Wait.forListeningPorts())
17
    .up(["db"]);
18
  const dbContainer = container.getContainer("db-1");
19
  const mappedPort = dbContainer.getMappedPort(5432);
20
  const url = createDBUrl({
21
    host: dbContainer.getHost(),
22
    port: mappedPort,
23
  });
24

25
  await execAsync(`DATABASE_URL=${url} npx prisma db push`);
26

27
  const prisma = new PrismaClient({
28
    datasources: {
29
      db: {
30
        url,
31
      },
32
    },
33
  });
34

35
  async function down() {
36
    await prisma.$disconnect();
37
    await container.down();
38
  }
39

40
  return <const>{
41
    container,
42
    port,
43
    prisma,
44
    truncate: () => truncate(prisma),
45
    down,
46
    async [Symbol.asyncDispose]() {
47
      await down();
48
    },
49
  };
50
}
51

52
export async function truncate(prisma: PrismaClient) {
53
  const tableNames = Prisma.dmmf.datamodel.models.map((model) => {
54
    return model.dbName || model.name.toLowerCase();
55
  });
56
  const truncateQuery = `TRUNCATE TABLE ${tableNames.map((name) => `"${name}"`).join(", ")} CASCADE`;
57

58
  await prisma.$executeRawUnsafe(truncateQuery);
59
}

vitest.helper.ts

実際のDBセットアップからtruncate、downまでをまとめたヘルパー関数です。vi.hoistedを利用する必要があります。

1
import type { User } from "next-auth";
2
import { afterAll, afterEach, expect, vi } from "vitest";
3

4
export async function setup() {
5
  const { container, prisma, truncate, down } = await vi.hoisted(async () => {
6
    const { setupDB } = await import("../../../tests/db.setup");
7

8
    return await setupDB({ port: "random" });
9
  });
10

11
  vi.mock("../_clients/prisma", () => ({
12
    prisma,
13
  }));
14

15
  afterAll(async () => {
16
    await down();
17
  });
18

19
  afterEach(async () => {
20
    await truncate();
21
  });
22

23
  return <const>{
24
    container,
25
    prisma,
26
    truncate,
27
    down,
28
    mock,
29
  };
30
}

テストスイート

1
import { beforeEach, describe, expect, test } from "vitest";
2
import { setup } from "./test.helper";
3

4
const { prisma, mock, createUser } = await setup();
5

6
describe("actions/items", () => {
7
  // ...
8
}):