DockerでCIのテストを回す — 手元では通るのにCIで落ちる

DockerでCIのテストを回す。コンテナとテスト用データベース、チェックを表示するパソコン。

本線の CI の回で、テストが push のたびに走るようにはなりました。しばらくは平和でした。データベースを触るコードにテストを書くまでは。

前回: Dockerでの開発ワークフロー — bind mountでnode_modulesが消える

これは深掘りです。本線の順路ではありません。 読まなくても本線は先へ進めます。 本線の pushしてもVMには届かない — GitHub ActionsとCI/CD の続きとして、あの回の最後で「MySQL を CI で立てて、データベースを使うテストも回す」を「まだ」と書いて残した部分を、実際にやる回です。

この記事のコマンドは、断りがない限りすべてVMの中(Ubuntu Server)で打ちます。 Windows の PowerShell ではありません。 プロンプトが ユーザー名@ホスト名:~$ になっていれば、Linux の中にいます。 前提: Dockerの導入を終えて、docker ps が sudo なしで通ること。 本線で作った ~/server には一切触りません。 練習用に ~/citlab を新しく作って、そこだけで完結させます。

手元で走らせます。

✔ 最初は空の配列が返る (18.4ms)
✔ POST すると 201 と id が返る (9.1ms)
✔ title が空なら 400 (2.2ms)

3本とも通ります。push します。GitHub Actions が赤くなります。

Error: connect ECONNREFUSED 127.0.0.1:3306

私のPCには MySQL が入っています。 去年、本線のデータベースの回で入れたものが、そのまま動き続けています。テストはそれに繋いで、通っていました。

GitHub の実行環境には、MySQL は入っていません。 入っていないので、繋がりません。当たり前です。

ここで多くの人がやることは2つあります。どちらも間違いです。

  1. CI 側にだけ MySQL を用意する — 手元と CI で違う環境になり、片方でしか出ないバグが生まれる
  2. データベースを使うテストを諦め、モックに差し替える — 「SQL が間違っている」という一番よく起きるバグが、テストをすり抜けるようになる

やるべきことは、手元と CI で同じものを動かすことです。 そのための道具は、もう持っています。コンテナです。

対象レベル: 中級〜上級 / 区分: 発展

目次

この記事でわかること

  • 「手元では通るのに CI で落ちる」の原因は、ほぼ全部「環境が違う」こと。 直す場所はテストではなく環境の作り方
  • docker compose up の終了コードは、既定ではテストの結果とは限らない。 --abort-on-container-exit だけだと「最初に終わったコンテナ」の終了コードが返る
  • テスト用のデータベースは、テストのたびに作り直すのが一番簡単で、一番速い。 tmpfs に載せればディスクにすら書かない
  • docker compose run --rm と up --abort-on-container-exit は用途が違う。 手元のデバッグ向きと CI 向き
  • GitHub Actions の services: は速いが、手元で同じものを再現できない。何を捨てているのかを知って選ぶ
  • テストが不安定になる原因は、たいてい「並列」「時刻」「順序」の3つ。 それぞれ直し方が違う
  • テストは本番と同じイメージで走らせる。 そのためにマルチステージの target を変えない

この記事でやること

  1. ~/citlab に MySQL を使う Node.js の API と、データベースを本当に読み書きするテスト3本を作る
  2. 開発用とは別の compose.test.yaml を書き、データベースを tmpfs に載せる
  3. up の終了コードが「最初に終わったコンテナ」のものになることを確かめ、--exit-code-from で外に出す
  4. run --rm と up --abort-on-container-exit を両方走らせて、違いを表にする
  5. down -v を毎回やって、前回のデータが残っていないことを確かめる
  6. GitHub Actions のワークフローを全文書き、services: を使う書き方と比べる
  7. 遅くなる原因と不安定になる原因を、それぞれ潰して片づける

先に知る言葉

この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。

言葉意味
終了コードコマンドが終わるときに残す数字。0 が成功、0 以外が失敗。CI はこれだけを見て赤と緑を決める
$?シェルで直前のコマンドの終了コードが入っている変数。echo $? で読む
フィクスチャテストが動く前に用意しておくデータ。この記事ではテーブルと、その中身
フレーキーテスト同じコードなのに、通ったり落ちたりするテスト。CI で一番嫌われる
tmpfsメモリ上の置き場。再起動で消える。詳しくはボリュームの回
サービスコンテナGitHub Actions がジョブの横で立ててくれるコンテナ。services: で書く
マトリクス1つのジョブを、複数の条件(言語の版など)で並べて走らせる書き方

① 練習用のリポジトリを作る

本線の ~/server は使いません。 壊すと本線の続きができなくなるからです。

bash
$ mkdir ~/citlab
$ cd ~/citlab

Node.js が入っているか確かめます。本線の API の回で入れているはずです。

bash
$ node -v
v22.11.0

入っていなくても、この記事は最後まで進められます。 テストはコンテナの中で走らせるので、必要なのは Docker だけです。手元で直接走らせて比べたい人だけ、入っていると得をします。

package.json を作ります。

bash
$ npm init -y
$ npm pkg set type=module
$ npm pkg set scripts.start="node server.js"
$ npm pkg set scripts.test="node --test test/"
$ npm install mysql2

依存はこれ1つだけです。 テストの道具は入れません。Node.js には node --test という組み込みのテストランナーが入っているので、Jest も Vitest も要りません。本線の CI の回と同じ方針です。

package.json がこうなっていれば正解です。

{
  "name": "citlab",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node server.js",
    "test": "node --test test/"
  },
  "dependencies": {
    "mysql2": "^3.11.0"
  }
}

npm install が package-lock.json を作っています。 これは消さずに Git に入れます。理由は本線の CI の回の npm ci のところに書いたとおりで、版を固定するファイルが無いと、CI は毎回違うものを入れるからです。

データベースに繋ぐところ

db.js を作ります。

import mysql from 'mysql2/promise';

export const pool = mysql.createPool({
  host: process.env.DB_HOST ?? '127.0.0.1',
  port: Number(process.env.DB_PORT ?? 3306),
  user: process.env.DB_USER ?? 'root',
  password: process.env.DB_PASSWORD ?? '',
  database: process.env.DB_NAME ?? 'citlab',
  connectionLimit: 5,
});

// データベースが受付を始めるまで待つ
export async function waitForDb(retries = 30) {
  for (let i = 1; i <= retries; i++) {
    try {
      await pool.query('SELECT 1');
      return;
    } catch (e) {
      if (i === retries) throw e;
      await new Promise((r) => setTimeout(r, 1000));
    }
  }
}

export async function initSchema() {
  await pool.query(`CREATE TABLE IF NOT EXISTS tasks (
    id INT AUTO_INCREMENT PRIMARY KEY,
    title VARCHAR(100) NOT NULL,
    done TINYINT(1) NOT NULL DEFAULT 0,
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
  )`);
}

接続先を全部、環境変数から読んでいます。 これが一番大事な行です。ここがソースコードに直書きされていると、テスト用のデータベースに繋ぎ替えることができません。

waitForDb を入れている理由はCompose の深掘りの回に書いたとおりです。healthcheck は起動の瞬間しか守ってくれないので、アプリ側にも待つ処理が要ります。

API 本体

app.js です。

import http from 'node:http';
import { pool } from './db.js';

function send(res, status, body) {
  const json = JSON.stringify(body);
  res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
  res.end(json);
}

function readJson(req) {
  return new Promise((resolve) => {
    let buf = '';
    req.on('data', (c) => (buf += c));
    req.on('end', () => {
      try {
        resolve(JSON.parse(buf || '{}'));
      } catch {
        resolve({});
      }
    });
  });
}

export function createServer() {
  return http.createServer(async (req, res) => {
    try {
      if (req.method === 'GET' && req.url === '/tasks') {
        const [rows] = await pool.query(
          'SELECT id, title, done FROM tasks ORDER BY id'
        );
        return send(res, 200, rows);
      }
      if (req.method === 'POST' && req.url === '/tasks') {
        const body = await readJson(req);
        const title = String(body.title ?? '').trim();
        if (!title) return send(res, 400, { error: 'title は必須です' });
        const [r] = await pool.execute(
          'INSERT INTO tasks (title) VALUES (?)',
          [title]
        );
        return send(res, 201, { id: r.insertId, title, done: 0 });
      }
      send(res, 404, { error: 'not found' });
    } catch (e) {
      send(res, 500, { error: e.message });
    }
  });
}

createServer を export していて、この中では listen していません。 テストから同じサーバーを、別のポートで立ち上げたいからです。

server.js は、本番用の入口です。

import { createServer } from './app.js';
import { waitForDb, initSchema } from './db.js';

await waitForDb();
await initSchema();

const port = Number(process.env.PORT ?? 3000);
createServer().listen(port, () => {
  console.log(`listening on ${port}`);
});

② テストがデータベースを使うと、何が変わるか

普通のテストは、関数に値を入れて、返ってきた値を見るだけです。何度走らせても同じです。

データベースを使うテストは、そうではありません。 テストが状態を残すからです。

状態を持たないテストデータベースを使うテスト
2回目に走らせたとき1回目と同じ結果1回目のデータが残っている
順番を入れ替えたとき同じ結果結果が変わることがある
同時に2つ走らせたとき平気お互いのデータを壊す
落ちたときその場で分かるどのテストが汚したのか分からない

だから、データベースを使うテストには必ず決めておくことがあります。

  1. どのデータベースを使うか — 開発用と同じものは絶対に使わない(TRUNCATE で自分の作業データが消えます)
  2. いつ綺麗にするか — テスト全体の前か、テスト1本ごとか
  3. 誰が作るか — 手で作るのか、毎回コンテナごと作り直すのか

この記事の答えは、「専用のデータベースを、テストのたびにコンテナごと作り直す」です。一番乱暴に見えて、一番間違いが起きません。 綺麗にし忘れる余地が無いからです。

③ テストを3本書く

test/tasks.test.js を作ります。

bash
$ mkdir ~/citlab/test
import { test, before, beforeEach, after } from 'node:test';
import assert from 'node:assert/strict';
import { createServer } from '../app.js';
import { pool, waitForDb, initSchema } from '../db.js';

let base;
let server;

before(async () => {
  await waitForDb();
  await initSchema();
  server = createServer();
  await new Promise((r) => server.listen(0, r));
  base = `http://127.0.0.1:${server.address().port}`;
});

beforeEach(async () => {
  await pool.query('TRUNCATE TABLE tasks');
});

after(async () => {
  server.close();
  await pool.end();
});

test('最初は空の配列が返る', async () => {
  const res = await fetch(`${base}/tasks`);
  assert.equal(res.status, 200);
  assert.deepEqual(await res.json(), []);
});

test('POST すると 201 と id が返る', async () => {
  const res = await fetch(`${base}/tasks`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ title: '牛乳を買う' }),
  });
  assert.equal(res.status, 201);
  const created = await res.json();
  assert.ok(created.id > 0);

  const list = await (await fetch(`${base}/tasks`)).json();
  assert.equal(list.length, 1);
  assert.equal(list[0].title, '牛乳を買う');
});

test('title が空なら 400', async () => {
  const res = await fetch(`${base}/tasks`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ title: '   ' }),
  });
  assert.equal(res.status, 400);

  const list = await (await fetch(`${base}/tasks`)).json();
  assert.equal(list.length, 0);
});

この3本には、意図して入れてあるものが4つあります。

書いたこと理由
server.listen(0)0 は「空いているポートを OS に選ばせる」という意味。 3000 番を固定で使うと、開発サーバーが動いていると落ちます
beforeEach の TRUNCATE1本ごとに空に戻す。 これが無いと、2本目のデータが3本目に見えます
assert.ok(created.id > 0)assert.equal(created.id, 1) と書かない。 id は前回の続きから振られることがあり、1 だとは限りません
after の pool.end()閉じないとテストが終わりません。 接続が生きている限り、Node.js は終了しないためです

3本目でわざと、失敗したあとの状態も確かめています。 「400 を返した」だけでなく「そのとき保存もされていない」まで見ないと、400 を返しつつ書き込んでいるコードを通してしまいます。

④ テスト専用の Compose ファイルを作る

まず開発用を書きます。compose.yaml です。

name: citlab

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      DB_HOST: db
      DB_USER: root
      DB_PASSWORD: devpass
      DB_NAME: citlab
    depends_on:
      db:
        condition: service_healthy

  db:
    image: mysql:8.4
    environment:
      MYSQL_ROOT_PASSWORD: devpass
      MYSQL_DATABASE: citlab
    volumes:
      - db-data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "-pdevpass"]
      interval: 2s
      timeout: 3s
      retries: 30
      start_period: 20s

volumes:
  db-data:

開発用のデータベースには名前付きボリュームが付いています。 消えては困るからです。

テスト用は、ここが正反対になります。 compose.test.yaml を作ります。

name: citlab-test

services:
  test:
    build: .
    command: ["node", "--test", "test/"]
    environment:
      DB_HOST: db
      DB_USER: root
      DB_PASSWORD: testpass
      DB_NAME: citlab_test
      TZ: UTC
    depends_on:
      db:
        condition: service_healthy

  db:
    image: mysql:8.4
    environment:
      MYSQL_ROOT_PASSWORD: testpass
      MYSQL_DATABASE: citlab_test
      TZ: UTC
    command: ["--performance-schema=OFF"]
    volumes:
      - type: tmpfs
        target: /var/lib/mysql
        tmpfs:
          size: 1073741824
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "-ptestpass"]
      interval: 2s
      timeout: 3s
      retries: 30
      start_period: 20s

開発用との違いは4つです。ここが記事の中心です。

開発用 compose.yamlテスト用 compose.test.yaml
プロジェクト名citlabcitlab-test(同じにすると開発用のコンテナを巻き添えで止めます)
データベース名citlabcitlab_test(別物にする)
データの置き場名前付きボリューム(残る)tmpfs(メモリ。残らない)
ポート公開3000:3000書かない(テストは中で完結する)

なぜ tmpfs なのか

テスト用のデータベースに、残ってほしいものは1つもありません。 それどころか、残ると事故になります。

tmpfs はメモリ上の置き場なので、コンテナが消えれば中身も消えます。 ディスクに一切書きません。「消し忘れ」という状態が存在しなくなります。

副産物として速くなります。データベースの書き込みはディスクに確実に届いたことを確かめてから返すのが仕事なので、そこがメモリになると効きます。

tmpfs の細かい話はボリュームの回に書いてあります。 ここでは「消える置き場を、消えてほしいものに使っている」だけです。 size を書いているのは、既定がメモリの半分だからです。 VMのメモリが 2GB しかない環境で、テストが暴走してメモリを食い尽くすのを防ぎます。

Dockerfile

FROM node:22-slim AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev

FROM node:22-slim AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY --from=deps /app/node_modules ./node_modules
COPY . .
CMD ["node", "server.js"]

.dockerignore も置きます。

node_modules
.git
compose*.yaml

test という段(ステージ)を作っていないことに注目してください。 理由は⑫に書きます。

走らせる

bash
$ cd ~/citlab
$ docker compose -f compose.test.yaml up --build --abort-on-container-exit --exit-code-from test
citlab-test-db-1    | [Server] /usr/sbin/mysqld: ready for connections.
citlab-test-test-1  | ✔ 最初は空の配列が返る (61.2ms)
citlab-test-test-1  | ✔ POST すると 201 と id が返る (14.8ms)
citlab-test-test-1  | ✔ title が空なら 400 (5.9ms)
citlab-test-test-1  | # pass 3
citlab-test-test-1  | # fail 0
citlab-test-test-1 exited with code 0
Aborting on container exit...

[スクリーンショット: 01_テストが3本通る.png] docker compose -f compose.test.yaml up --build --abort-on-container-exit --exit-code-from test を実行して、# pass 3 と # fail 0 が出ている画面を撮ってください。

片づけます。

bash
$ docker compose -f compose.test.yaml down -v

⑤ 終了コードは、黙って 0 になる

ここが、この記事で一番大事なところです。

わざとテストを1本壊します。3本目の期待値を 400 から 200 に書き換えてください。

  assert.equal(res.status, 200);   // ← わざと間違える

まず、オプションを何も付けずに走らせます。

bash
$ docker compose -f compose.test.yaml up --build

テストは落ちます。画面にも # fail 1 と出ます。そして、プロンプトが戻ってきません。

citlab-test-test-1  | # fail 1
citlab-test-test-1 exited with code 1
(db は動き続けていて、ここで止まったまま)

up は「全部のコンテナを立ち上げて、見張る」コマンドです。 1つが死んでも、残りは動いています。だから終わりません。Ctrl + C で抜けます。

この状態を CI に置くと、ジョブは終わらずタイムアウトまで回り続けます。

次に、--abort-on-container-exit だけを付けます。

bash
$ docker compose -f compose.test.yaml up --build --abort-on-container-exit
$ echo $?

今度は全部止まって、プロンプトが戻ります。そして echo $? が返す数字を、必ず自分の目で見てください。

1

1 が返りました。 今の Docker Compose(v2)は、--abort-on-container-exit のとき最初に終了したコンテナの終了コードを返します。この構成では test が最初に終わるので、テストの結果が出ています。

ただし、これは「最初に終わったのが test だった」からです。 db など別のコンテナが先に落ちれば、返るのはそのコンテナの終了コードです。どのコンテナの結果を返すべきかを、up は知りません。

CI はこの数字しか見ていません。 テストの結果を確実に渡すには、どのサービスの終了コードを返すかを指定します。

正しくはこう書きます。

bash
$ docker compose -f compose.test.yaml up --build --abort-on-container-exit --exit-code-from test
$ echo $?
1

--exit-code-from test は「test サービスの終了コードを、そのまま外に出せ」という意味です。

書き方終わるか終了コード
up終わらない(他のコンテナが生きている)—
up --abort-on-container-exit終わる最初に終わったコンテナの結果(test とは限らない)
up --abort-on-container-exit --exit-code-from test終わる✅ test の結果がそのまま出る

--exit-code-from を書くと --abort-on-container-exit は自動で付きます。 それでも私は両方書きます。読んだ人に、なぜ止まるのかが見えるからです。

もう1つの書き方として、up -d で背中に回してから docker compose -f compose.test.yaml wait test で待つ方法もあります。wait は指定したサービスの終了コードを返します。CI のログが混ざらない利点がありますが、落ちたときにログを別途取りに行く手間が増えます。この記事では --exit-code-from で通します。

壊したテストは元に戻しておいてください。

  assert.equal(res.status, 400);

⑥ 使い捨ての実行 — run --rm と up の違い

同じテストを、別の書き方でも走らせられます。

bash
$ docker compose -f compose.test.yaml run --rm test
$ echo $?

これは終了コードがそのまま出ます。 --exit-code-from は要りません。run は「このコンテナで、このコマンドを1回だけ実行する」コマンドで、結果はそのコマンドのものだからです。

では run を CI で使えばいいのかというと、そう単純ではありません。

run --rm testup --abort-on-container-exit --exit-code-from test
終了コード✅ そのまま出る--exit-code-from を書かないと当てにならない
立ち上がるものdepends_on のものだけファイルに書いた全サービス
終わったあとdb は動いたまま残る全部止まる
--rmtest コンテナだけ消える。ボリュームは残る—
ポート公開既定で公開しない(--service-ports が要る)ファイルのとおり公開する
ログtest の出力だけ全サービスが混ざる
コマンドの差し替え✅ 後ろに書けばその場で変えられるファイルを書き換える必要がある
向いている場面手元で1本だけ試す・デバッグCI

run の一番おいしいところは、コマンドをその場で差し替えられることです。1本だけ走らせたいとき。

bash
$ docker compose -f compose.test.yaml run --rm test node --test test/tasks.test.js

中を覗きたいとき。

bash
$ docker compose -f compose.test.yaml run --rm test bash

このシェルの中では、db という名前でデータベースに繋がります。 手で SQL を叩いて、テストが何を残したのかを見られます。

bash
$ mysql -h db -u root -ptestpass citlab_test -e "SELECT * FROM tasks;"

mysql コマンドは node:22-slim のイメージには入っていません。 上の行を test コンテナの中で打つと command not found になります。データベースを覗くときは、mysql が入っている db 側で打ちます。

docker compose -f compose.test.yaml exec db mysql -u root -ptestpass citlab_test -e "SELECT * FROM tasks;"

run を使ったら、必ず自分で片づけます。

bash
$ docker compose -f compose.test.yaml down -v

⑦ 毎回 down -v して、残っていないことを確かめる

「毎回作り直している」を、信じずに確かめます。

まず、テストを走らせたあと down を付けずに、データを1件残してみます。

bash
$ docker compose -f compose.test.yaml run --rm test node -e "
  import('./db.js').then(async (m) => {
    await m.waitForDb(); await m.initSchema();
    await m.pool.execute('INSERT INTO tasks (title) VALUES (?)', ['残るか確認']);
    const [r] = await m.pool.query('SELECT COUNT(*) c FROM tasks');
    console.log('件数:', r[0].c);
    await m.pool.end();
  });
  "
件数: 1

db はまだ動いています。 もう一度同じことをすると 2 件になります。ここが「前回のデータが残る」状態です。

down -v で消します。

bash
$ docker compose -f compose.test.yaml down -v
$ docker compose -f compose.test.yaml run --rm test node -e "
  import('./db.js').then(async (m) => {
    await m.waitForDb(); await m.initSchema();
    const [r] = await m.pool.query('SELECT COUNT(*) c FROM tasks');
    console.log('件数:', r[0].c);
    await m.pool.end();
  });
  "
件数: 0

0 に戻りました。 テーブルすら消えていて、initSchema が作り直しています。

[スクリーンショット: 02_down-vで0件に戻る.png] down -v の前が「件数: 1」、あとが「件数: 0」になっている画面を、続けて撮ってください。

down -v の -v はボリュームを消すオプションです。 今回のデータベースは tmpfs なので、実はコンテナを消した時点でデータは消えています。それでも -v を付けます。

  • 匿名ボリュームは、tmpfs にしていても付いていることがある(イメージの VOLUME 命令)
  • 将来 tmpfs を普通のボリュームに変えたとき、-v を書き忘れていると静かにデータが残る

down -v は、必ず -f compose.test.yaml を付けて打ちます。 素で docker compose down -v と打つと、compose.yaml(開発用)が対象になり、開発中のデータベースが消えます。 私はこれを1度やりました。

Makefile にしておくと、-f の付け忘れが起きません。

test:
	docker compose -f compose.test.yaml up --build \
	  --abort-on-container-exit --exit-code-from test
	docker compose -f compose.test.yaml down -v

test-clean:
	docker compose -f compose.test.yaml down -v

Makefile の行頭はスペースではなくタブです。 スペースだと missing separator で止まります。

ただし、上の Makefile には穴があります。 1行目が失敗すると、make はそこで止まり、down -v が実行されません。 直します。

test:
	docker compose -f compose.test.yaml up --build \
	  --abort-on-container-exit --exit-code-from test; \
	  status=$$?; \
	  docker compose -f compose.test.yaml down -v; \
	  exit $$status

終了コードを一度しまっておいて、片づけたあとに返しています。 ⑤でやったことと同じ話が、ここでも出てきます。「片づけ」が「結果」を上書きしないようにするという一点です。

⑧ GitHub Actions で同じことを回す

手元でやったことを、そのまま書くだけです。 .github/workflows/test.yml を作ります。

bash
$ mkdir -p ~/citlab/.github/workflows
name: test

on:
  push:
    branches: [main]
  pull_request:

jobs:
  container-test:
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - name: ソースを取ってくる
        uses: actions/checkout@v4

      - name: コンテナでテストを走らせる
        run: >
          docker compose -f compose.test.yaml up --build
          --abort-on-container-exit --exit-code-from test

      - name: 失敗したときはログを出す
        if: failure()
        run: docker compose -f compose.test.yaml logs --no-color

      - name: 後片づけ
        if: always()
        run: docker compose -f compose.test.yaml down -v

手元との差は1行もありません。 run: の中身は、⑤で自分の手で打ったコマンドそのままです。これが「環境を揃える」の意味です。

書いてあることを1つずつ。

行何のためか
on: pull_requestPR のときも走らせる。 main に入る前に落ちてほしい
timeout-minutes: 15保険。 待ち続けるジョブは課金と待ち時間を無限に食う
--exit-code-from testこれが無いと、先に終わった別のコンテナの結果が返りうる(⑤)
if: failure() の logs落ちたときだけ、データベース側のログも出す。 原因が db にあることが多い
if: always() の down -v落ちても必ず片づける。 これが if: 無しだと、失敗時に飛ばされます

docker compose は ubuntu-latest のランナーに最初から入っています。 インストールする手順は要りません。 actions/checkout@v4 の @v4 は版の固定です。 省くと動きません。

push します。GitHub 側の作り方は本線の Git と GitHub の回のとおりです。

bash
$ cd ~/citlab
$ printf 'node_modules\n' > .gitignore
$ git init -b main
$ git add -A
$ git commit -m "コンテナでテストを回す"
$ git remote add origin git@github.com:あなたの名前/citlab.git
$ git push -u origin main

[スクリーンショット: 03_Actionsが緑になる.png] GitHub の Actions タブで、container-test ジョブが緑のチェックになっている画面を撮ってください。

必ず1度、赤も見てください。 ③のテストをまたわざと壊して push します。赤くなれば、CI は本当に見ています。⑤の罠に落ちていない証拠です。

⑨ services: を使う方法との比較

GitHub Actions には、ジョブの横にコンテナを立ててくれる services: という書き方があります。同じことをこう書けます。

jobs:
  service-test:
    runs-on: ubuntu-latest
    timeout-minutes: 15

    services:
      db:
        image: mysql:8.4
        env:
          MYSQL_ROOT_PASSWORD: testpass
          MYSQL_DATABASE: citlab_test
        ports:
          - 3306:3306
        options: >-
          --health-cmd="mysqladmin ping -h 127.0.0.1 -ptestpass"
          --health-interval=2s
          --health-timeout=3s
          --health-retries=30

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm ci
      - run: npm test
        env:
          DB_HOST: 127.0.0.1
          DB_USER: root
          DB_PASSWORD: testpass
          DB_NAME: citlab_test
          TZ: UTC

こちらのほうが速いです。 イメージを作らないからです。では、何を捨てているのか。

compose.test.yaml を回すservices: を使う
手元で同じものが動くか✅ 同じコマンドで動く動かない。GitHub の中でしか再現できない
Node.js の版を決めるのは自分の Dockerfilesetup-node とランナー(本番と違う版になりうる)
OS・入っている道具自分のイメージのものランナーのもの
速さイメージのビルド分だけ遅い✅ 速い
別のCIに引っ越せるか✅ docker compose があれば動く書き直しになる
services: の待ち方healthcheck + depends_onoptions: に文字列で書く(書式が独自)

私の結論は、この記事の題材では compose.test.yaml です。 理由は速さではありません。CI が落ちたときに、手元でまったく同じコマンドを打てるからです。

「CI でだけ落ちる」を調べる作業は、services: を選ぶと極端に苦しくなります。 直せるまで push を繰り返すことになり、1回3分の待ちが延々と積み上がります。

services: が向いているのは、こういう場合です。

  • アプリをコンテナにしていない(そもそも Dockerfile が無い)
  • 複数の言語の版で試したい(setup-node とマトリクスの組み合わせが強い)
  • とにかく1分でも速くしたい

⑩ CI で遅くなる原因

私の場合、この構成は最初 1回 6 分かかっていました。中身を割ると、こうでした。

原因実測対策
毎回イメージを作り直している約 3 分キャッシュ(後述)
データベースの起動待ち約 40 秒tmpfs / performance-schema=OFF / interval を短く
--build を毎回付けている↑に含む変わっていないなら作り直さない
テスト本体約 3 秒ここは最初から速い

テストの実行時間は 3 秒です。残りの 5 分 57 秒は、テストではありません。

1. 毎回イメージを作る

CI には、キャッシュが1つもありません。 毎回まっさらな機械が割り当てられるので、npm ci はインターネットから取り直しになります。

ここはレイヤーキャッシュの回の話がそのまま効きます。 Dockerfile の行の順番が正しければ、キャッシュを CI に持ち込んだときに効く範囲が変わります。キャッシュの持ち込み方(--cache-from や GitHub Actions のキャッシュ)は、あの回で扱った内容の続きなので、ここでは繰り返しません。

この記事でやる分の対策は1つだけです。イメージを小さくすること。 node:22 ではなく node:22-slim を使っているのがそれです。理由はイメージのサイズの回にあります。

2. データベースの起動待ち

MySQL の初回起動は、データを初期化するので遅いです。 tmpfs にしてある時点でだいぶ速くなりますが、まだ削れます。

    healthcheck:
      interval: 2s        # ⚠️ 既定は 30s。1回目の判定まで30秒待つことになる
      start_period: 20s   # この間の失敗は「失敗」に数えない

interval の既定は 30 秒です。 これを直さないと、5 秒で起動していても、次の判定まで 25 秒待たされます。 私の 40 秒のうち、半分以上がこれでした。

もっと速くしたいなら、そもそも軽いデータベースを使う手もあります。 ただし本番が MySQL なら、テストも MySQL にすべきです。 SQLite に差し替えて速くしたテストは、MySQL でしか出ないバグを一切見つけてくれません。 ⑫の話につながります。

3. 毎回 --build する

ソースが変わっていないなら、作り直す必要はありません。 ただし CI では変わっていないことのほうが珍しいので、ここは効きません。手元では効きます。

bash
$ # 手元でテストだけ回すとき(アプリを直していないなら)
$ docker compose -f compose.test.yaml up --abort-on-container-exit --exit-code-from test

ただし --build を外すと、「ソースを直したのにテスト結果が変わらない」が起きます。 迷ったら付けてください。時間より、嘘の結果のほうが高くつきます。

⑪ テストが不安定になる原因

同じコードなのに、通ったり落ちたりするテスト(フレーキーテスト)は、CI で一番たちが悪いものです。「もう一度走らせたら通った」を1度でも許すと、その CI は誰も信じなくなります。

データベースを使うテストで不安定になる原因は、経験上ほぼ3つです。

原因1 — 並列実行で、同じデータベースを共有している

node --test は、テストファイルを並列に走らせます。 ファイルが1つのうちは平気ですが、2つ目を足した瞬間に壊れます。

// test/tasks.test.js  → beforeEach で TRUNCATE
// test/health.test.js → 3件入れてから数を数える

片方の TRUNCATE が、もう片方の途中で走ります。 落ちたり通ったりします。

直し方は3つあります。

直し方書き方向き不向き
並列をやめるnode --test --test-concurrency=1 test/一番簡単。テストが増えると遅い
ファイルごとに別のデータベースcitlab_test_tasks のように、ファイルごとに別名で作る速いが下準備が要る
TRUNCATE をやめてトランザクションで巻き戻す各テストを BEGIN して ROLLBACKDDL があると効かない

この記事では1つ目にします。 package.json を直します。

bash
$ npm pkg set scripts.test="node --test --test-concurrency=1 test/"

「まず正しく。速いのは、遅くて困ってから。」 順番を逆にすると、速くて信用できないテストが残ります。

原因2 — 時刻に依存している

これは必ず一度は踏みます。

// ⚠️ 落ちるテスト
const created = await res.json();
assert.equal(created.created_at.slice(0, 10), new Date().toISOString().slice(0, 10));

手元では通り、CI で落ちます。 理由が2つ重なっています。

  1. タイムゾーンが違う。 私のVMは Asia/Tokyo、GitHub のランナーは UTC。日付が9時間ずれます
  2. 「いま」を2回取っている。 保存した瞬間と、比べた瞬間。日付が変わる境目に走ると落ちます

直し方は2つです。

    environment:
      TZ: UTC     # ← コンテナ側を揃える。テストにも db にも書く

そして、テストで「いま」と比べません。

// 幅で見る(前後1分に入っていればよい)
const t = new Date(created.created_at + 'Z').getTime();
assert.ok(Math.abs(Date.now() - t) < 60_000);

時刻とタイムゾーンの話そのものは、本線の日付と時刻の回にまとまっています。 ここで言いたいのは、「9時間ずれる」は CI で初めて表に出ることが多いという一点です。

原因3 — 順序に依存している

前のテストが残したものを、次のテストが当てにしている状態です。手元では書いた順に走るので気づきません。

// ⚠️ 2本目が、1本目の残したデータを前提にしている
test('1件作る', ...);
test('一覧に1件ある', async () => {
  const list = await (await fetch(`${base}/tasks`)).json();
  assert.equal(list.length, 1);   // ← 1本目に依存
});

直し方はいつも同じです。1本のテストの中で、必要なものを自分で作ること。

test('一覧に1件ある', async () => {
  await fetch(`${base}/tasks`, { method: 'POST', /* ... */ });  // 自分で作る
  const list = await (await fetch(`${base}/tasks`)).json();
  assert.equal(list.length, 1);
});

順序依存を見つける方法も書いておきます。

bash
$ # ファイルを1本ずつ、単独で走らせる。落ちたら順序依存
$ docker compose -f compose.test.yaml run --rm test node --test test/tasks.test.js

id を当てにするのも順序依存の一種です。 TRUNCATE TABLE は AUTO_INCREMENT を 1 に戻しますが、DELETE FROM は戻しません。どちらで消したかによって id が変わるテストは、必ずいつか落ちます。 ③で assert.ok(created.id > 0) と書いたのはこのためです。

⑫ 本番と同じイメージでテストする

Dockerfile に test という段を作りたくなります。 こういう形です。

# ⚠️ この記事では、これをやりません
FROM node:22-slim AS test
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci                 # ← devDependencies も入れる
COPY . .
CMD ["node", "--test", "test/"]

そして compose.test.yaml にこう書く。

  test:
    build:
      context: .
      target: test     # ⚠️ 本番と違う段を作っている

動きます。速くもなります。でも、テストしているものが本番と違います。

違うもの何が起きるか
入っているパッケージ--omit=dev を付けていないので、本番に無いものがあってもテストは通る
NODE_ENV本番だけ production。環境変数で挙動が変わるライブラリがある
ファイルの構成テスト段にだけあるファイルを、うっかり本番のコードから読んでしまう

そして一番怖いのは、これが「テストは通ったのに本番で落ちる」という形でしか表に出ないことです。 テストが守るはずだったところが、そのまま穴になります。

この記事の構成では、target を書いていません。 compose.test.yaml の test サービスは、本番と同じ runtime 段のイメージを、コマンドだけ変えて動かしています。

  test:
    build: .                              # ← target を書かない = 最後の段 = 本番と同じ
    command: ["node", "--test", "test/"]  # ← 変えているのはここだけ

これができるのは、テストに追加のライブラリが1つも要らないからです。 node --test は Node.js に組み込まれています。依存を増やさない選択が、ここで効いてきます。

テストファイル自体は本番イメージにも入ります。 数十KBです。気になるなら、こう分けられます。

やり方本番イメージ手間
テストも COPY する(この記事)テストが数十KB入る✅ 何もしない
.dockerignore で外し、テスト時だけ bind mount✅ 完全に同じcompose.test.yaml に volumes: が1行増える
target: test を作る✅ 完全に同じテストしているものが本番と別物になる

下2つのうち、選ぶなら真ん中です。 一番下は、得るものより失うものが大きいと考えています。

どうしても devDependencies が要るテスト(ブラウザを動かす E2E など)は、話が変わります。そのときは「本番と同じイメージ」を諦める代わりに、何を諦めたのかを Dockerfile にコメントで残します。 黙って別物にするのが一番まずいやり方です。

つまずいたところ

1. --exit-code-from を知らずに、何の終了コードを見ているか分かっていなかった

⑤に書いたとおりです。--abort-on-container-exit だけでも、たまたま test が先に終われば正しい結果が出ます。 ですが db が先に落ちれば別の番号になる、何の結果を返しているか説明できない CIでした。

CI を書いたら、必ず1度わざと壊して赤を確認する。 これを習慣にしました。緑は「通った」ではなく「見ていない」かもしれません。

2. docker compose down -v で開発中のデータベースを消した

-f compose.test.yaml を付け忘れました。compose.yaml が既定で読まれるので、開発用のボリュームが消えました。

compose.test.yaml に name: citlab-test を書いてプロジェクト名を分けたのはこの直後です。名前を分けても -f の付け忘れは防げませんが、docker compose ls でどちらのプロジェクトが動いているかが見えるようになりました。⑦の Makefile が本当の対策です。

3. TRUNCATE が Cannot truncate a table referenced in a foreign key constraint で落ちた

このあと tasks に紐づく別のテーブルを足したときに出ました。外部キーで参照されているテーブルは TRUNCATE できません。

この記事の構成なら、悩む必要はありません。データベースごと捨てているからです。 消し方に困ったら、down -v して立て直すのが最短です。それでも1本ごとに綺麗にしたいときは、子のテーブルから順に DELETE します。

4. CI だけ waitForDb のリトライを使い切って落ちた

手元では 5 秒で立ち上がる MySQL が、CI では 25 秒かかりました。ランナーのディスクとメモリが、私のVMより遅かったからです。

retries を増やして直りましたが、本当の対策は healthcheck + depends_on: condition: service_healthy のほうでした。 アプリ側のリトライは保険であって、待つ仕事はまず Compose にやらせます。 Compose の深掘りの回に書いたとおりです。

5. テストが終わってもコンテナが終わらなかった

pool.end() を書き忘れていました。接続が生きている間、Node.js のプロセスは終わりません。 テストは全部通っているのに、--exit-code-from が待ち続けます。

timeout-minutes を書いていなければ、ここで CI が何時間も回ります。 保険は先に張っておきます。

後片づけ

bash
$ cd ~/citlab
$ docker compose -f compose.test.yaml down -v
$ docker compose down -v

残っているものを確認します。

bash
$ docker ps -a
$ docker volume ls
$ docker compose ls

citlab も citlab-test も出てこなければ完了です。

イメージも消したいとき。

bash
$ docker image rm citlab-app citlab-test-test
$ docker image prune -f

docker system prune -a は使いません。 他のプロジェクトのイメージまで消します。 名前を指定して消すほうが安全です。

練習用のフォルダごと消す場合。

bash
$ cd ~ && rm -rf ~/citlab

~/server(本線で作ったもの)は消していません。 この記事は ~/citlab の中だけで完結しています。

まとめ — 理解できたこと

  • 「手元では通るのに CI で落ちる」の原因は環境の違い。 直すのはテストではなく、環境を揃える仕組み
  • テスト用のデータベースは、開発用と完全に分ける。 プロジェクト名・データベース名・ファイルの3つとも分ける
  • テスト用のデータは残さない。tmpfs に載せれば「消し忘れ」という状態が消える
  • docker compose up の終了コードは、既定ではテストの結果とは限らない。 最初に終わったコンテナの終了コードが返る
  • --exit-code-from <サービス名> を必ず書く。 --abort-on-container-exit だけでは、別のコンテナが先に落ちたときにその結果を拾ってしまう
  • run --rm は終了コードがそのまま出るが、db が残る。 手元のデバッグ向き。CI は up --exit-code-from
  • down -v は毎回、-f を付けて打つ。 素で打つと開発用のデータベースが消える
  • 後片づけが結果を上書きしないようにする。 終了コードを一度しまってから片づけて、最後に返す
  • CI では if: always() で片づけ、if: failure() でログを出す
  • GitHub Actions の services: は速いが、手元で再現できない。 速さと再現性のどちらを取るかの選択
  • CI が遅い原因はテストではない。 イメージのビルドとデータベースの起動待ちが大半
  • healthcheck の interval の既定は 30 秒。 起動が速くても、次の判定まで待たされる
  • 不安定なテストの原因は「並列」「時刻」「順序」の3つ。 まず正しく、速いのは遅くて困ってから
  • id が 1 だと決めつけない。 TRUNCATE と DELETE で AUTO_INCREMENT の扱いが違う
  • テストは本番と同じイメージで走らせる。 target を変えた瞬間、テストしているものが本番と別物になる
  • CI を書いたら、必ず1度わざと壊して赤を見る。 緑は「通った」ではなく「見ていない」かもしれない

参考リンク


次に読む

この記事は 【深掘り】Docker の 10 / 11 本目です。

記事
← 前の記事Dockerでの開発ワークフロー — bind mountでnode_modulesが消える
→ 次の記事本番のDocker Composeを組む — 決めることは8つある

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

DevOps›Docker — Testing & CI
  • テスト用のデータベースを使い捨てにする
  • CIで同じイメージを回す

この記事は、上の項目を実際に手を動かして確かめる回です。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次