When a Dry Run Disagrees With the Real Run — the check that vanishes with the side effect

You add --dry-run to a batch job to suppress side effects and see what would happen first. But if a check itself depends on the result of a side effect, suppressing the effect also removes the check. The real run behaves correctly while only the dry run prints the wrong answer. Based on a case hit on 16 August 2026, here is the cause, the fix and the regression test.

What happened

The job renames files carrying an older date to today's date before processing them, which is a common shape. The new name is "today's date plus whatever follows the date in the original name".

2026-08-09-report-blogger.md  →  2026-08-16-report-blogger.md
2026-08-11-report-blogger.md  →  2026-08-16-report-blogger.md   // the same name

Two files that differ only in their date collide at the destination. The implementation had a guard for that: just before renaming, it checked the destination with fs.existsSync and skipped if it was already taken.

const to = path.join(dir, promotedName(base, today));
// skip if the destination already exists
if (fs.existsSync(to)) { warn(`skip: ${to}`); continue; }
if (!DRY) fs.renameSync(from, to);
log(`promote${DRY ? ' [dry]' : ''}: ${base} -> ${path.basename(to)}`);

In a real run the guard works. The moment the first renameSync completes, the destination exists, so the second iteration's existsSync returns true and that file is skipped. Nothing is lost.

The dry run is the problem. if (!DRY) skips renameSync, so the destination is never created. The second existsSync stays false and both files are reported as being renamed.

$ 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

Generalising the cause

The shape is not specific to renaming. Any code that checks "what I am about to create" against external state has the same hole.

What they share is that the check reads the current state of the world. In a real run the world advances as the loop proceeds, so the check holds; in a dry run it never advances, so the check does not.

The fix: check against the plan, not the world

The fix is simple. Record the results of the operations you intend to perform in your own ledger and check both the external state and the ledger. The ledger is updated in both modes, so both reach the same conclusion.

const claimed = new Set();   // destinations claimed by this run

for (const base of targets) {
  const toBase = promotedName(base, today);
  const to = path.join(dir, toBase);
  // consult both the world and this run's plan
  if (fs.existsSync(to) || claimed.has(toBase)) {
    warn(`skip: ${toBase} (${base} stays under its original name)`);
    continue;
  }
  claimed.add(toBase);
  if (!DRY) fs.renameSync(from, to);
  log(`promote${DRY ? ' [dry]' : ''}: ${base} -> ${toBase}`);
}

After the fix the dry run prints the same conclusion as the real run.

$ 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 stays under its original name)

It also matters that the skip message says what happens to the rejected item. "Skipped" alone leaves the reader unsure whether that file was deleted or kept. Here it states explicitly that the file stays under its original date.

Regression test: run both modes on the same input

Because this class of bug appears in one mode only, exercising both modes in a single test is the reliable approach. What you assert is that the number of eligible items is the same.

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

test('two targets differing only by date promote exactly once (dry agrees)', () => {
  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 || '');   // warnings go to stderr

    const promoted = out.split('\n').filter((l) => /^promote/.test(l));
    assert.equal(promoted.length, 1, `exactly one promotion expected (dry=${dry})`);
    assert.match(out, /^skip:/m);

    if (!dry) {
      // the rejected file is still there under its original name
      const left = fs.readdirSync(dir).filter((f) => /^2026-08-(09|11)-z\.md$/.test(f));
      assert.equal(left.length, 1);
    }
  }
});

One thing that tripped us up

The first version of the test used execFileSync, and the warning was invisible in the non-dry case only. The reason is where it is written. execFileSync returns stdout alone when the process succeeds, and the warning goes to console.warn, that is stderr. The dry case passed because it happened to exit non-zero and take the exception path, where the helper concatenated stdout and stderr.

When a test needs both streams, use spawnSync and concatenate stdout and stderr explicitly. A test that inspects less when the command succeeds is exactly the kind that lets a quiet failure through.

Checklist

If your batch job has a dry-run mode, three things are worth checking.

1. Is there a check inside the loop that assumes what the previous iteration created? existsSync, re-listing, and SELECT-based duplicate checks are the usual suspects.
2. Does that check still hold in a dry run? If not, add a ledger that records the plan.
3. Is there a test that runs both modes on the same input and asserts an equal count? If not, add one in the shape above.

A dry run exists so that a person can decide before anything is executed. When the material for that decision diverges from the real run, the feature works against you. "The real run is correct, so it is minor" is the wrong reading: the accuracy of the output deserves the same weight.