--- 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`。 ```javascript // tools/browser/verify-live.mjs // 使い方: node tools/browser/verify-live.mjs [--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); ``` ### 使い方 ```bash # 価格の反映確認（新値が出て、旧値が消えていること） node tools/browser/verify-live.mjs "<公開URL>" --expect "<新価格>" --not-expect "<旧価格>" --shot out.png # JS で後から描画される値 node tools/browser/verify-live.mjs "" --wait 8000 --expect "<期待値>" # 検索ボタンを押さないと出ない値 node tools/browser/verify-live.mjs "" --click "<ボタンのセレクタ>" --expect "<期待値>" ``` CI にも `node --check tools/**/*.mjs` を足しておく。**検証ツール自体が壊れると、 壊れていることに気付けなくなる**のが一番まずい。 ## API 側を読むときに併せて潰す罠 - **無効なパラメータ値が黙殺されていないか**: 付けた時と付けない時で**レスポンス長が同じ**なら、 そのパラメータは効いていない。有効値をドキュメントで確認する。 - **レスポンスが切れていないか**: 中継層（プロキシ・サーバレス関数・スクリプト実行環境）に 文字数上限があるなら `offset` / `nextOffset` を持たせ、**切れたことを呼び出し側が検知できる** 形にする。切り捨てを黙って返す実装は「空」の誤読を必ず生む。 - **空が正常なレコードが混じっていないか**: 集計用・セット販売用などの仮想レコードは 空で正常なことがある。「空がN件」と数える前に実体があるものだけに絞る。 ---