「検証したのに何も検証していなかった」を潰す — 定期実行の反映を3層で exit code 判定する

自動化した処理（毎朝のバッチ、cron、スケジュール実行）が本当に外に出たかを機械判定するための型。 success:true や「ジョブ成功」ログは システムがそう思っている状態 であって、 実際にそう見えている状態 ではない。この2つは日常的にズレる。

先に結論: 検証はこの2つで空振りする

罠1. 検証スクリプトが「実行できたか」しか見ていない

# これは判定になっていない
node verify.mjs "<公開ページURL>" && echo PASS

ページが開けたら PASS。値が1円も変わっていなくても PASS する。 実際にこれで「反映を確認した」と報告しかけた。判定にするには 期待値の突き合わせを必ず書く:

node verify.mjs "<URL>" --expect "<新しい値>" --not-expect "<古い値>"

--not-expect（旧値が消えていること）は --expect とセットで書く。 新値がどこかに出ていても、古い値が別の場所に残っていれば利用者は古い方を見る。

罠2. 検証ツールが既定ブランチに無い

引き継ぎ・手順書に「翌朝これを回せ」と書いたコマンドが、main では存在しなかった （作業ブランチにしか置かず、PR が認証待ちで止まっていた）。翌朝の担当が打つと Cannot find module で終わる。「ツールを作った」と「既定ブランチで走る」は別の事実。

• 手順書にコマンドを書く前に、素の既定ブランチで1回実行する。
• 走らないなら、手順書に書く前にマージする。PR CLI が使えなくても git merge --no-ff <branch> + git push でよい。

3層で判定する（1つでも落ちたら exit 1）

層	何を見るか	落ちた時に分かること
A 実行された	ジョブの最終実行の日時と結果（管理APIの status）	起動していない（トリガ消失・権限）
B データが変わった	保存先（DB / 外部API / シート）の実値を読み戻す	計算はできたが書けていない（送信経路）
C 実表示に出た	公開ページをヘッドレスブラウザで開いて文字列を突き合わせ	書けたが利用者には別の値が見えている

B と C を別の経路で取るのが要点。同じ API を2回読んでも「取れなかった」と「空だった」の 区別がつかない。C だけは人が見る画面から取る。

C の判定を「開けた」から「その額が出ている」へ

B で読んだ実値から期待文字列を組み立てて C に渡すと、A/B/C が1本に繋がる:

// B: 保存先の実値
const unitPrice = await api.readValue(targetDate);       // 例: 19700

// C: 実表示。B の値 × 数量が画面に出ているはず
const expectTotal = `JPY ${(unitPrice * nights).toLocaleString('en-US')}`;
const args = [url, '--wait', '9000', '--expect', expectTotal];
if (OLD_TOTAL) args.push('--not-expect', OLD_TOTAL);     // 旧値が残っていないか

これで「API はこう言っているが画面は違う」が FAIL として出る。 FAIL は不便ではなく、それが検知したかった事象そのもの。

対照（コントロール）を必ず1つ入れる

変わってほしい対象だけを見ると「全体が別要因で上がった」を取り逃す。 変わらないはずの1件を同じ判定に入れる（例: 対象外の日付が旧値のままであること）。 これが崩れていたら、原因は仕込んだ変更ではない。

そのまま使えるスケルトン

const results = [];
const add = (name, pass, detail) => {
  results.push({ name, pass });
  console.log(`${pass ? 'PASS' : 'FAIL'}  ${name}\n      ${detail}`);
};

// A) 実行されたか
const st = await api.getStatus();
add('A 期待日に成功している', String(st.lastRun.date).startsWith(EXPECT_DATE) && st.lastRun.result === 'ok',
    `lastRun = ${st.lastRun.date} / ${st.lastRun.result} / ${st.lastRun.count} 件`);

// B) 保存先の実値（対象 + 対照）
add('B1 対象が新しい値になっている', targets.every(v => v > THRESHOLD), `実値 ${JSON.stringify(targets)}`);
add('B2 対照は変わっていない',      control <= THRESHOLD,               `対照 = ${control}`);

// C) 実表示（B の値から期待文字列を作って突き合わせ）
add('C 実表示', browserCheck(url, expectTotal, oldTotal), `期待 ${expectTotal} / 旧値なし`);

const failed = results.filter(r => !r.pass);
console.log(`\n=== ${failed.length ? `FAIL ${failed.length}/${results.length}` : `ALL PASS`} ===`);
process.exit(failed.length ? 1 : 0);

運用の作法

• スクリーンショットは自分で開いて目視する。 テキスト抽出だけでは描画崩れ・文字化け・ 二重表示を見逃す。1枚に対象が複数出るページなら、そこが全件確認の入口になる。
• 判定を回した時刻と exit code を手順書に残す。 「検証した」ではなく 「--not-expect "<旧値>" 付きで 4/4 PASS、exit 0」と書く。
• 反映前に1回、反映後に1回回す。反映前に FAIL するなら、その FAIL は正しい （＝この判定は変化を検知できる）。反映前から PASS するなら、その判定は壊れている。