本線の CI の回で、テストが push のたびに走るようにはなりました。しばらくは平和でした。データベースを触るコードにテストを書くまでは。
これは深掘りです。本線の順路ではありません。 読まなくても本線は先へ進めます。 本線の 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つあります。どちらも間違いです。
- CI 側にだけ MySQL を用意する — 手元と CI で違う環境になり、片方でしか出ないバグが生まれる
- データベースを使うテストを諦め、モックに差し替える — 「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を変えない
この記事でやること
~/citlabに MySQL を使う Node.js の API と、データベースを本当に読み書きするテスト3本を作る- 開発用とは別の
compose.test.yamlを書き、データベースをtmpfsに載せる upの終了コードが「最初に終わったコンテナ」のものになることを確かめ、--exit-code-fromで外に出すrun --rmとup --abort-on-container-exitを両方走らせて、違いを表にするdown -vを毎回やって、前回のデータが残っていないことを確かめる- GitHub Actions のワークフローを全文書き、
services:を使う書き方と比べる - 遅くなる原因と不安定になる原因を、それぞれ潰して片づける
先に知る言葉
この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。
| 言葉 | 意味 |
|---|---|
| 終了コード | コマンドが終わるときに残す数字。0 が成功、0 以外が失敗。CI はこれだけを見て赤と緑を決める |
$? | シェルで直前のコマンドの終了コードが入っている変数。echo $? で読む |
| フィクスチャ | テストが動く前に用意しておくデータ。この記事ではテーブルと、その中身 |
| フレーキーテスト | 同じコードなのに、通ったり落ちたりするテスト。CI で一番嫌われる |
tmpfs | メモリ上の置き場。再起動で消える。詳しくはボリュームの回 |
| サービスコンテナ | GitHub Actions がジョブの横で立ててくれるコンテナ。services: で書く |
| マトリクス | 1つのジョブを、複数の条件(言語の版など)で並べて走らせる書き方 |
① 練習用のリポジトリを作る
本線の ~/server は使いません。 壊すと本線の続きができなくなるからです。
Node.js が入っているか確かめます。本線の API の回で入れているはずです。
v22.11.0
入っていなくても、この記事は最後まで進められます。 テストはコンテナの中で走らせるので、必要なのは Docker だけです。手元で直接走らせて比べたい人だけ、入っていると得をします。
package.json を作ります。
依存はこれ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つ走らせたとき | 平気 | お互いのデータを壊す |
| 落ちたとき | その場で分かる | どのテストが汚したのか分からない |
だから、データベースを使うテストには必ず決めておくことがあります。
- どのデータベースを使うか — 開発用と同じものは絶対に使わない(
TRUNCATEで自分の作業データが消えます) - いつ綺麗にするか — テスト全体の前か、テスト1本ごとか
- 誰が作るか — 手で作るのか、毎回コンテナごと作り直すのか
この記事の答えは、「専用のデータベースを、テストのたびにコンテナごと作り直す」です。一番乱暴に見えて、一番間違いが起きません。 綺麗にし忘れる余地が無いからです。
③ テストを3本書く
test/tasks.test.js を作ります。
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 の TRUNCATE | 1本ごとに空に戻す。 これが無いと、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 | |
|---|---|---|
| プロジェクト名 | citlab | citlab-test(同じにすると開発用のコンテナを巻き添えで止めます) |
| データベース名 | citlab | citlab_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 という段(ステージ)を作っていないことに注目してください。 理由は⑫に書きます。
走らせる
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 が出ている画面を撮ってください。
片づけます。
⑤ 終了コードは、黙って 0 になる
ここが、この記事で一番大事なところです。
わざとテストを1本壊します。3本目の期待値を 400 から 200 に書き換えてください。
assert.equal(res.status, 200); // ← わざと間違える
まず、オプションを何も付けずに走らせます。
テストは落ちます。画面にも # 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 だけを付けます。
今度は全部止まって、プロンプトが戻ります。そして echo $? が返す数字を、必ず自分の目で見てください。
1
1 が返りました。 今の Docker Compose(v2)は、--abort-on-container-exit のとき最初に終了したコンテナの終了コードを返します。この構成では test が最初に終わるので、テストの結果が出ています。
ただし、これは「最初に終わったのが test だった」からです。 db など別のコンテナが先に落ちれば、返るのはそのコンテナの終了コードです。どのコンテナの結果を返すべきかを、up は知りません。
CI はこの数字しか見ていません。 テストの結果を確実に渡すには、どのサービスの終了コードを返すかを指定します。
正しくはこう書きます。
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 の違い
同じテストを、別の書き方でも走らせられます。
これは終了コードがそのまま出ます。 --exit-code-from は要りません。run は「このコンテナで、このコマンドを1回だけ実行する」コマンドで、結果はそのコマンドのものだからです。
では run を CI で使えばいいのかというと、そう単純ではありません。
run --rm test | up --abort-on-container-exit --exit-code-from test | |
|---|---|---|
| 終了コード | ✅ そのまま出る | --exit-code-from を書かないと当てにならない |
| 立ち上がるもの | depends_on のものだけ | ファイルに書いた全サービス |
| 終わったあと | db は動いたまま残る | 全部止まる |
--rm | test コンテナだけ消える。ボリュームは残る | — |
| ポート公開 | 既定で公開しない(--service-ports が要る) | ファイルのとおり公開する |
| ログ | test の出力だけ | 全サービスが混ざる |
| コマンドの差し替え | ✅ 後ろに書けばその場で変えられる | ファイルを書き換える必要がある |
| 向いている場面 | 手元で1本だけ試す・デバッグ | CI |
run の一番おいしいところは、コマンドをその場で差し替えられることです。1本だけ走らせたいとき。
中を覗きたいとき。
このシェルの中では、db という名前でデータベースに繋がります。 手で SQL を叩いて、テストが何を残したのかを見られます。
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 を使ったら、必ず自分で片づけます。
⑦ 毎回 down -v して、残っていないことを確かめる
「毎回作り直している」を、信じずに確かめます。
まず、テストを走らせたあと down を付けずに、データを1件残してみます。
件数: 1
db はまだ動いています。 もう一度同じことをすると 2 件になります。ここが「前回のデータが残る」状態です。
down -v で消します。
件数: 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 を作ります。
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_request | PR のときも走らせる。 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 の回のとおりです。
[スクリーンショット: 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 の版を決めるのは | 自分の Dockerfile | setup-node とランナー(本番と違う版になりうる) |
| OS・入っている道具 | 自分のイメージのもの | ランナーのもの |
| 速さ | イメージのビルド分だけ遅い | ✅ 速い |
| 別のCIに引っ越せるか | ✅ docker compose があれば動く | 書き直しになる |
services: の待ち方 | healthcheck + depends_on | options: に文字列で書く(書式が独自) |
私の結論は、この記事の題材では 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 では変わっていないことのほうが珍しいので、ここは効きません。手元では効きます。
ただし --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 して ROLLBACK | DDL があると効かない |
この記事では1つ目にします。 package.json を直します。
「まず正しく。速いのは、遅くて困ってから。」 順番を逆にすると、速くて信用できないテストが残ります。
原因2 — 時刻に依存している
これは必ず一度は踏みます。
// ⚠️ 落ちるテスト
const created = await res.json();
assert.equal(created.created_at.slice(0, 10), new Date().toISOString().slice(0, 10));
手元では通り、CI で落ちます。 理由が2つ重なっています。
- タイムゾーンが違う。 私のVMは
Asia/Tokyo、GitHub のランナーはUTC。日付が9時間ずれます - 「いま」を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);
});
順序依存を見つける方法も書いておきます。
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 が何時間も回ります。 保険は先に張っておきます。
後片づけ
残っているものを確認します。
citlab も citlab-test も出てこなければ完了です。
イメージも消したいとき。
docker system prune -a は使いません。 他のプロジェクトのイメージまで消します。 名前を指定して消すほうが安全です。
練習用のフォルダごと消す場合。
~/server(本線で作ったもの)は消していません。 この記事は~/citlabの中だけで完結しています。
まとめ — 理解できたこと
- 「手元では通るのに CI で落ちる」の原因は環境の違い。 直すのはテストではなく、環境を揃える仕組み
- テスト用のデータベースは、開発用と完全に分ける。 プロジェクト名・データベース名・ファイルの3つとも分ける
- テスト用のデータは残さない。
tmpfsに載せれば「消し忘れ」という状態が消える docker compose upの終了コードは、既定ではテストの結果とは限らない。 最初に終わったコンテナの終了コードが返る--exit-code-from <サービス名>を必ず書く。--abort-on-container-exitだけでは、別のコンテナが先に落ちたときにその結果を拾ってしまうrun --rmは終了コードがそのまま出るが、dbが残る。 手元のデバッグ向き。CI はup --exit-code-fromdown -vは毎回、-fを付けて打つ。 素で打つと開発用のデータベースが消える- 後片づけが結果を上書きしないようにする。 終了コードを一度しまってから片づけて、最後に返す
- CI では
if: always()で片づけ、if: failure()でログを出す - GitHub Actions の
services:は速いが、手元で再現できない。 速さと再現性のどちらを取るかの選択 - CI が遅い原因はテストではない。 イメージのビルドとデータベースの起動待ちが大半
healthcheckのintervalの既定は 30 秒。 起動が速くても、次の判定まで待たされる- 不安定なテストの原因は「並列」「時刻」「順序」の3つ。 まず正しく、速いのは遅くて困ってから
idが 1 だと決めつけない。TRUNCATEとDELETEでAUTO_INCREMENTの扱いが違う- テストは本番と同じイメージで走らせる。
targetを変えた瞬間、テストしているものが本番と別物になる - CI を書いたら、必ず1度わざと壊して赤を見る。 緑は「通った」ではなく「見ていない」かもしれない
参考リンク
- roadmap.sh — Docker
- Docker 公式 — docker compose up
- Docker 公式 — docker compose run
- Docker 公式 — docker compose down
- Docker 公式 — Compose file: services
- Docker 公式 — tmpfs mounts
- Node.js 公式 — テストランナー
- MySQL 公式 — Docker で MySQL を動かす
- mysql2 — GitHub
- GitHub Actions のドキュメント
次に読む
この記事は 【深掘り】Docker の 10 / 11 本目です。
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。
roadmap.sh のどこをやっているか
- テスト用のデータベースを使い捨てにする
- CIで同じイメージを回す
この記事は、上の項目を実際に手を動かして確かめる回です。

コメント