dry run が本番と違う答えを返す — 副作用を止めた瞬間に消える判定

バッチ処理に --dry-run を付けるのは、副作用を止めて「何が起きるか」を先に見るためです。ところが、判定そのものが副作用の結果に依存していると、副作用を止めた瞬間にその判定も消えます。本番は正しく動くのに、dry の出力だけが間違っている、という状態になります。2026年8月16日に実際に踏んだ例をもとに、原因・直し方・回帰テストの書き方を整理します。

何が起きたか

題材は、過去の日付が付いたファイルを当日の日付へ改名してから処理するという、よくあるバッチです。改名後の名前は「当日の日付 + 元の名前の日付以降の部分」で決まります。

2026-08-09-report-blogger.md  →  2026-08-16-report-blogger.md
2026-08-11-report-blogger.md  →  2026-08-16-report-blogger.md   // 同じ名前になる

日付以外が同じファイルが2つあると、改名先が衝突します。 この実装には衝突を防ぐガードが入っていました。改名の直前に fs.existsSync で行き先を確認し、既にあればスキップする、というものです。

const to = path.join(dir, promotedName(base, today));
// 行き先が既にあればスキップ
if (fs.existsSync(to)) { warn(`skip: ${to}`); continue; }
if (!DRY) fs.renameSync(from, to);
log(`promote${DRY ? ' [dry]' : ''}: ${base} -> ${path.basename(to)}`);

本番実行ではこのガードは正しく効きます。1件目を renameSync した瞬間に行き先のファイルが実在するようになるので、2件目の existsSync が真になってスキップされます。データは失われません。

問題は dry のほうです。 if (!DRY) によって renameSync が飛ばされるため、行き先のファイルは最後まで作られません。したがって2件目の existsSync も偽のままで、両方とも「改名する」と表示されます。

$ node promote.js --dry
promote [dry]: 2026-08-09-report-blogger.md -> 2026-08-16-report-blogger.md
promote [dry]: 2026-08-11-report-blogger.md -> 2026-08-16-report-blogger.md

原因を一般化する

この形は rename に限りません。「これから作るもの」の重複を、外部の状態を見て判定している処理はすべて同じ穴を持ちます。

共通しているのは、「世界の現在の状態」を判定に使っていることです。本番ではループが進むにつれて世界が更新されるので判定が成立しますが、dry では世界が更新されないので判定が成立しません。

直し方：判定の相手を「計画」に変える

直し方は単純です。これから行う操作の結果を、自分で台帳に積みます。 判定は「外部の状態 または 台帳」の両方を見ます。台帳への追加は dry でも本番でも同じように行うので、両者の結論が一致します。

const claimed = new Set();   // このランで確保済みの行き先

for (const base of targets) {
  const toBase = promotedName(base, today);
  const to = path.join(dir, toBase);
  // 外部の状態と、このランの計画の両方を見る
  if (fs.existsSync(to) || claimed.has(toBase)) {
    warn(`skip: ${toBase} (${base} は元のまま残す)`);
    continue;
  }
  claimed.add(toBase);
  if (!DRY) fs.renameSync(from, to);
  log(`promote${DRY ? ' [dry]' : ''}: ${base} -> ${toBase}`);
}

修正後の dry の出力は次のようになります。本番と同じ結論です。

$ node promote.js --dry
promote [dry]: 2026-08-09-report-blogger.md -> 2026-08-16-report-blogger.md
skip: 2026-08-16-report-blogger.md (2026-08-11-report-blogger.md は元のまま残す)

あわせてスキップしたときのメッセージに「弾かれた側がどうなるか」を書くのも重要です。「スキップしました」だけだと、その1件が消えたのか残ったのかが読み手に分かりません。今回は「元の日付のまま残す」と明示しました。

回帰テスト：dry と本番を同じ入力で比べる

この種のバグは「片方のモードでしか出ない」ので、両方のモードを1つのテストで回すのが確実です。検査するのは「実行対象の件数が両モードで一致すること」です。

const { test } = require('node:test');
const assert = require('node:assert/strict');
const { spawnSync } = require('node:child_process');

test('日付以外が同名の対象が2件あっても、実行は1件だけ（dry も同じ判定）', () => {
  for (const dry of [true, false]) {
    const dir = makeWorkspace(['2026-08-09-z.md', '2026-08-11-z.md']);
    const args = ['promote.js', '--date', '2026-08-16'];
    if (dry) args.push('--dry');
    const r = spawnSync('node', args, { cwd: dir, encoding: 'utf8' });
    const out = (r.stdout || '') + (r.stderr || '');   // 警告は stderr に出る

    const promoted = out.split('\n').filter((l) => /^promote/.test(l));
    assert.equal(promoted.length, 1, `実行は1件だけのはず（dry=${dry}）`);
    assert.match(out, /^skip:/m);

    if (!dry) {
      // 弾かれた側は元の名前のまま残る（黙って消さない）
      const left = fs.readdirSync(dir).filter((f) => /^2026-08-(09|11)-z\.md$/.test(f));
      assert.equal(left.length, 1);
    }
  }
});

ここで一度つまずいた点

最初はテストヘルパに execFileSync を使っていて、非 dry のケースだけ警告メッセージを検出できませんでした。原因は出力先です。execFileSync は成功時に stdout しか返しません。警告は console.warn つまり stderr に出ているので、終了コード0の実行では消えてしまいます。dry のケースが通っていたのは、そちらがたまたま非0で終了して例外経路に入り、ヘルパが stdout と stderr を連結していたためでした。

両方の出力を検査したいテストでは spawnSync を使い、stdout と stderr を明示的に連結してから検査します。 「成功したときだけ検査が甘くなる」テストは、まさに今回のような静かな失敗を見逃します。

チェックリスト

既存のバッチに dry run があるなら、次の3点を確認してみてください。

1. ループの中で、直前の反復が作ったものを前提にした判定があるか。 existsSync・一覧の再取得・SELECT による重複確認が典型です。
2. その判定は dry でも成立するか。 成立しないなら、計画を積む台帳を1つ足します。
3. dry と本番を同じ入力で流し、実行対象の件数が一致するテストがあるか。 無ければ、上のかたちで1本足します。

dry run は、実行する前に人が判断するための機能です。判断の材料が本番とずれていると、機能そのものが逆に働きます。 「本番は正しいのだから軽微」と扱わず、出力の正確さも同じ重さで守る価値があります。