name: live-state-verify description: API やDBの値ではなく「実際に画面に出ている状態」をブラウザで読み戻してから断定する手順。価格・在庫・掲載文など外部に露出する状態を調査・報告するとき、変更の有無を問わず使う。

外に出ている状態は、実表示を読み戻してから断定する

「変更したあとテストする」の話ではない。変更していなくても、外部に露出している状態について 何かを主張するなら、その情報が実際に出ている画面を開いて読み戻してから言う。 調査・分析・レポートの段階が対象。

なぜ必要か（この手順が生まれた実例）

ある物件管理システムで「7室の説明文が空です」と報告したが、完全に誤りだった。 実際は全室に見出し42字・本文481字が入っており、公開サイトにも表示されていた。 3つの罠が重なっていた:

1. 別フィールドを見ていた — 見ていたのは定型文テンプレート用の項目で、本文は別の項目にあった。 フィールド名が似ていると、値が空でも「そういうものだ」と気付けない。
2. 無効なクエリパラメータが黙って無視された — includeTexts=true は不正値だったが API は エラーを返さず、当該キーごとレスポンスから消した。 all が唯一の有効値だった。400 が返っていれば即座に気付けた。
3. レスポンスが途中で切れていた — 中継層が45,000字で打ち切っており、後半のデータが そもそも読めていなかった。「読めていない」が「空」と同じ見え方になった。

根本原因は「値が取れていない」と「値が空」がAPI越しには区別できないこと。 実表示を見れば、この2つは一瞬で区別がつく。

判定の原則

• API の戻り値・DB/シートの値・送信ログ・ジョブの成功ログは 「システムがそう思っている状態」であって「実際にそう見えている状態」ではない。
• 反映確認は「新値が出ている」と「旧値が消えている」を必ずセットで見る。 片方だけだと二重表示・キャッシュ残り・別レイヤーの上書きを見逃す。
• 判定は目視の印象ではなく exit code で機械的に取る。
• スクリーンショットは必ず自分で開いて目視する。テキスト抽出だけでは描画崩れ・文字化け・ 重複描画が出ない。
• 代表1件だけ見て「反映OK」と言わない。対象が複数（商品・プラン・チャネル・言語・環境）なら 全件ループし、どれが緑でどれが赤かを一覧で出す。
• 「画面で確認してください」と依頼者に振らない。AI 側で開いて確認する。

実装（各リポジトリに1本置く汎用スクリプト）

npm i playwright +（初回のみ）npx playwright install chromium。

// tools/browser/verify-live.mjs
// 使い方: node tools/browser/verify-live.mjs <URL> [--expect "文字列"] [--not-expect "文字列"]
//                                                 [--shot out.png] [--wait ms] [--click セレクタ]
import { chromium } from 'playwright';
import { writeFileSync } from 'node:fs';

const args = process.argv.slice(2);
const url = args[0];
if (!url || url.startsWith('--')) { console.error('URL を指定してください'); process.exit(2); }
const many = (n) => args.filter((_, i) => args[i - 1] === n);
const one  = (n) => { const i = args.indexOf(n); return i >= 0 ? args[i + 1] : null; };

const expects = many('--expect');
const notExpects = many('--not-expect');
const clicks = many('--click');
const shot = one('--shot');
const saveText = one('--save-text');
const wait = Number(one('--wait')) || 5000;

const browser = await chromium.launch();
const page = await browser.newPage({ viewport: { width: 1280, height: 1000 }, locale: '<ロケール>' });
await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 90000 });
for (const sel of clicks) {
  try { await page.click(sel, { timeout: 15000 }); await page.waitForTimeout(2000); }
  catch { console.log(`WARN  クリックできず: ${sel}`); }
}
await page.waitForTimeout(wait);

const text = (await page.evaluate(() => document.body.innerText)).replace(/\n{3,}/g, '\n\n');
console.log('TITLE:', await page.title(), '/ CHARS:', text.length);

let failed = 0;
for (const e of expects)    { const hit = text.includes(e); if (!hit) failed++; console.log(`${hit ? 'OK  ' : 'MISS'}  出ているはず: ${JSON.stringify(e)}`); }
for (const e of notExpects) { const hit = text.includes(e); if (hit)  failed++; console.log(`${hit ? 'BAD ' : 'OK  '}  出てはいけない: ${JSON.stringify(e)}`); }

if (shot) { await page.screenshot({ path: shot, fullPage: true }); console.log('SHOT:', shot); }
if (saveText) { writeFileSync(saveText, text, 'utf8'); }
console.log(text.slice(0, 4000));
await browser.close();
process.exit(failed ? 1 : 0);

使い方

# 価格の反映確認（新値が出て、旧値が消えていること）
node tools/browser/verify-live.mjs "<公開URL>" --expect "<新価格>" --not-expect "<旧価格>" --shot out.png

# JS で後から描画される値
node tools/browser/verify-live.mjs "<URL>" --wait 8000 --expect "<期待値>"

# 検索ボタンを押さないと出ない値
node tools/browser/verify-live.mjs "<URL>" --click "<ボタンのセレクタ>" --expect "<期待値>"

CI にも node --check tools/**/*.mjs を足しておく。検証ツール自体が壊れると、 壊れていることに気付けなくなるのが一番まずい。

API 側を読むときに併せて潰す罠

• 無効なパラメータ値が黙殺されていないか: 付けた時と付けない時でレスポンス長が同じなら、 そのパラメータは効いていない。有効値をドキュメントで確認する。
• レスポンスが切れていないか: 中継層（プロキシ・サーバレス関数・スクリプト実行環境）に 文字数上限があるなら offset / nextOffset を持たせ、切れたことを呼び出し側が検知できる 形にする。切り捨てを黙って返す実装は「空」の誤読を必ず生む。
• 空が正常なレコードが混じっていないか: 集計用・セット販売用などの仮想レコードは 空で正常なことがある。「空がN件」と数える前に実体があるものだけに絞る。