Playwrightでレスポンシブとダークモードを一括撮影し比較レポートを生成する

Playwrightでレスポンシブとダークモードを一括撮影し比較レポートを生成する

公開: 2026/11/15
更新: 2026/11/15
目次
開閉

CSSのレイアウトを調整したり、共通コンポーネントのスタイルを変更したりしたあと、表示崩れが起きていないかを確認する作業には意外と時間がかかります。

普段の開発ではブラウザのDevToolsを開き、PC幅からタブレット幅、スマートフォン幅へとウィンドウサイズを順番に切り替えながら確認します。さらに prefers-color-scheme に対応したサイトであれば、ライトモードとダークモードの切り替えも加わります。

1ページあたり6パターンの目視確認を毎回手作業で繰り返していると、確認漏れが起きやすくなります。特に「PC幅では正常なのに、スマートフォン幅のときだけ長いURLやコードブロックが横にはみ出して横スクロールが発生している」といった崩れは、手作業の切り替えでは見落としがちです。

そこで今回は、Playwright を使って「Desktop / Tablet / Mobile × Light / Dark」の6パターンを一括でスクリーンショット撮影し、1画面で一覧比較できるHTMLレポートを自動生成する検証スクリプトを紹介します。あわせて、人間の目視だけに頼らず横はみ出しを自動で検知する仕組みも組み込みました。

検証環境と前提バージョン

  • OS / ランタイム: Windows 11 Pro / Node.js v24.13.0
  • ライブラリ: playwright-core ^1.65.1
  • 使用ブラウザ: Microsoft Edge 157.0.4341.46 (channel: "msedge" でローカル既存ブラウザを利用)
  • 参考仕様: Playwright Emulation / Playwright Screenshots

生成される比較レポートと実行画面

まずは、今回作成したスクリプトを手元の環境で実際に動かした結果をお見せします。

コマンドを1回実行すると、検証用ページに対して6パターンの撮影と横はみ出し判定を行い、結果をまとめた report.html を出力します。出力されたレポートをブラウザで開いた画面がこちらです。

Playwrightで6パターンを一括撮影した比較HTMLレポート画面

上段がライトモード、下段がダークモードで、左から Desktop(1280×800)、Tablet(768×1024)、Mobile(375×812)の順に並んでいます。右上のバッジを見ると、DesktopとTabletは緑色の OK (No Overflow) になっていますが、Mobileだけは赤色の OVERFLOW +283px が表示されています。

実際にMobileのサムネイルをよく見ると、画面下部の長いAPIエンドポイント文字列が枠を突き抜けて右端にはみ出しています。このように「どの幅・どのテーマで崩れたか」を1枚の比較画面で即座に把握できます。

実行時のターミナル出力も確認してみましょう。

capture-matrix.mjsの実行結果と横はみ出し検知ログ

各パターンの出力ファイル名とあわせて、はみ出し量(overflow +283px)がコンソールにも出力されています。


手元の既存ブラウザを使う軽量セットアップ

Playwrightを通常の playwright パッケージとしてインストールすると、テスト用のChromiumバイナリ一式(数百MB)がダウンロードされます。CI環境ではブラウザのバージョンを厳密に固定できるためこの方式が適していますが、手元のローカル開発中にサッと表示確認をしたいだけのときは、playwright-core とPCにインストール済みのChromeやEdgeを組み合わせる構成が手軽です。

mkdir visual-check && cd visual-check
npm init -y
npm install -D playwright-core

playwright-core はブラウザ本体をダウンロードしないため、インストールが数秒で完了します。起動時に channel: 'msedge' や channel: 'chrome' を指定すれば、普段使っているローカルのブラウザをヘッドレスモードでそのまま呼び出せます。

Lowom 編集長 編集長
TIPS MacとWindowsでのブラウザ指定の切り替え
会社支給のMacBook Proでは channel に 'chrome' を、自宅のWindows環境では標準搭載の 'msedge' を使うように環境変数 BROWSER_CHANNEL で切り替えられるようにしておくと、OSをまたいでも同じスクリプトをそのまま動かせます。

一括撮影・自動検知・HTMLレポート生成スクリプト

今回実際に動かしたスクリプト capture-matrix.mjs の全体像です。検証用のローカルHTTPサーバーを立てる部分も含めているため、そのまま手元で試せます(実際の開発では環境変数 TARGET_URL にローカル開発サーバーのURLを渡して使います)。

import fs from 'node:fs';
import path from 'node:path';
import http from 'node:http';
import { chromium } from 'playwright-core';

const OUT_DIR = path.resolve('./visual-report');
const SHOTS_DIR = path.join(OUT_DIR, 'shots');
fs.mkdirSync(SHOTS_DIR, { recursive: true });

// 検証するビューポートとカラースキームの組み合わせ
const VIEWPORTS = [
  { name: 'desktop', label: 'Desktop (1280×800)', width: 1280, height: 800 },
  { name: 'tablet', label: 'Tablet (768×1024)', width: 768, height: 1024 },
  { name: 'mobile', label: 'Mobile (375×812)', width: 375, height: 812 },
];
const SCHEMES = ['light', 'dark'];

// 動作確認用の簡易ローカルサーバー(TARGET_URL未指定時に利用)
function startDemoServer(htmlPath) {
  const html = fs.readFileSync(htmlPath, 'utf-8');
  return new Promise((resolve) => {
    const server = http.createServer((req, res) => {
      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
      res.end(html);
    });
    server.listen(0, '127.0.0.1', () => {
      const { port } = server.address();
      resolve({ server, url: `http://127.0.0.1:${port}/` });
    });
  });
}

function buildReportHtml(results, targetUrl) {
  const cards = results.map((item) => {
    const statusClass = item.overflowPx > 0 ? 'badge-warn' : 'badge-ok';
    const statusText = item.overflowPx > 0
      ? `OVERFLOW +${item.overflowPx}px`
      : 'OK (No Overflow)';
    return `
      <article class="shot-card">
        <div class="shot-meta">
          <div>
            <strong>${item.viewportLabel}</strong>
            <span class="scheme-tag">${item.scheme.toUpperCase()}</span>
          </div>
          <span class="badge ${statusClass}">${statusText}</span>
        </div>
        <div class="shot-frame">
          <img src="shots/${item.fileName}" alt="${item.viewportLabel} ${item.scheme}" />
        </div>
      </article>
    `;
  }).join('\n');

  return `<!DOCTYPE html>
<html lang="ja">
<head>
  <meta charset="UTF-8" />
  <title>Visual Matrix Report</title>
  <style>
    body { margin: 0; padding: 24px; font-family: system-ui, sans-serif; background: #f1f5f9; color: #0f172a; }
    .report-header { display: flex; justify-content: space-between; align-items: baseline; margin-bottom: 20px; border-bottom: 2px solid #cbd5e1; padding-bottom: 12px; }
    .report-header h1 { margin: 0; font-size: 1.35rem; }
    .report-header .meta { font-size: 0.85rem; color: #475569; }
    .matrix { display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px; }
    .shot-card { background: #ffffff; border: 1px solid #cbd5e1; border-radius: 8px; overflow: hidden; display: flex; flex-direction: column; }
    .shot-meta { padding: 10px 12px; background: #f8fafc; border-bottom: 1px solid #e2e8f0; display: flex; justify-content: space-between; align-items: center; font-size: 0.82rem; }
    .scheme-tag { margin-left: 6px; padding: 2px 6px; border-radius: 4px; background: #e2e8f0; color: #334155; font-size: 0.72rem; font-weight: 600; }
    .badge { padding: 2px 8px; border-radius: 999px; font-size: 0.72rem; font-weight: 700; }
    .badge-ok { background: #dcfce7; color: #166534; }
    .badge-warn { background: #fee2e2; color: #991b1b; }
    .shot-frame { padding: 10px; background: #e2e8f0; flex: 1; display: flex; align-items: flex-start; justify-content: center; }
    .shot-frame img { max-width: 100%; max-height: 290px; width: auto; height: auto; border: 1px solid #94a3b8; border-radius: 4px; }
  </style>
</head>
<body>
  <header class="report-header">
    <h1>Responsive &amp; Color Scheme Visual Report</h1>
    <div class="meta">Target: ${targetUrl} | Patterns: ${results.length}</div>
  </header>
  <section class="matrix">
    ${cards}
  </section>
</body>
</html>`;
}

async function main() {
  const demoHtml = path.resolve('./demo-target.html');
  const demo = process.env.TARGET_URL ? null : await startDemoServer(demoHtml);
  const targetUrl = process.env.TARGET_URL || demo.url;
  const browserChannel = process.env.BROWSER_CHANNEL || 'msedge';

  let browser;
  const results = [];
  let hasOverflow = false;

  try {
    browser = await chromium.launch({
      channel: browserChannel,
      headless: true,
    });

    console.log(`Target URL : ${targetUrl}`);
    console.log(`Browser    : ${browserChannel} (${browser.version()})`);
    console.log('---');

    for (const scheme of SCHEMES) {
      for (const vp of VIEWPORTS) {
        const context = await browser.newContext({
          viewport: { width: vp.width, height: vp.height },
          colorScheme: scheme,
          reducedMotion: 'reduce',
        });

        const page = await context.newPage();
        await page.goto(targetUrl, { waitUntil: 'networkidle' });
        await page.evaluate(() => document.fonts.ready);

        // 横スクロール(はみ出し)の自動検知
        const metrics = await page.evaluate(() => ({
          scrollWidth: document.documentElement.scrollWidth,
          clientWidth: document.documentElement.clientWidth,
        }));
        const overflowPx = Math.max(0, metrics.scrollWidth - metrics.clientWidth);
        if (overflowPx > 0) hasOverflow = true;

        const fileName = `${vp.name}-${scheme}.png`;
        await page.screenshot({
          path: path.join(SHOTS_DIR, fileName),
          fullPage: true,
        });

        const status = overflowPx > 0 ? `WARN (overflow +${overflowPx}px)` : 'OK';
        console.log(`[${scheme.padEnd(5)}] ${vp.name.padEnd(7)} (${vp.width}x${vp.height}) -> ${fileName} [${status}]`);

        results.push({
          viewportLabel: vp.label,
          scheme,
          fileName,
          overflowPx,
        });

        await context.close();
      }
    }

    const reportPath = path.join(OUT_DIR, 'report.html');
    fs.writeFileSync(reportPath, buildReportHtml(results, targetUrl), 'utf-8');
    console.log('---');
    console.log('Report generated: visual-report/report.html');

    if (hasOverflow) {
      console.log('Detected horizontal overflow on 1 or more viewports.');
      if (process.env.FAIL_ON_OVERFLOW === '1') {
        process.exitCode = 1;
      }
    }
  } finally {
    if (browser) await browser.close();
    if (demo) demo.server.close();
  }
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

実装で押さえた3つのポイント

  1. コンテキストごとに colorScheme と reducedMotion を指定する browser.newContext() のオプションで colorScheme: 'dark' を渡すことで、OS設定を変更せずに @media (prefers-color-scheme: dark) のスタイルを切り替えられます。あわせて reducedMotion: 'reduce' と document.fonts.ready の待機を入れることで、フェードインアニメーションの途中やフォント読み込み前のブレを防ぎます。
  2. 目視頼みにしない横はみ出し自動検知 人間がサムネイルを眺めるだけでは、数ピクセルのはみ出しを見逃すことがあります。scrollWidth > clientWidth を毎回計測し、レポート上のバッジ表示とあわせて環境変数 FAIL_ON_OVERFLOW=1 のときは終了コード 1 で失敗させるようにしました。
  3. try ... finally での確実なリソース解放 撮影の途中でページ接続がタイムアウトしたりエラーが発生したりしても、finally ブロックで browser.close() を呼ぶことで、バックグラウンドにヘッドレスブラウザのプロセスが居残るのを防ぎます。

現場で直面しやすいエッジケースと対処法

実際に日々の開発で回してみると、いくつか引っかかりやすいポイントがあります。

1. 検証対象サーバーが起動していない場合のエラー

TARGET_URL にローカルの開発サーバーを指定したものの、サーバーを起動し忘れて実行すると、Playwrightは次のようなエラーを出して停止します。

Target URL : http://127.0.0.1:59999/
Browser    : msedge (157.0.4341.46)
---
page.goto: net::ERR_CONNECTION_REFUSED at http://127.0.0.1:59999/
Call log:
  - navigating to "http://127.0.0.1:59999/", waiting until "networkidle"

CI環境やローカルのタスクランナーから呼び出す場合は、スクリプト実行前に開発サーバーの起動待ち(wait-on や curl によるヘルスチェック)を挟むと安定します。

2. fullPage: true と 100vh / position: sticky の相性

page.screenshot({ fullPage: true }) はページ全体の縦幅に合わせてスクロールしながら撮影するため、非常に便利です。しかし、CSSで height: 100vh を指定したセクションや position: sticky の追従ヘッダーがある場合、結合時の挙動によってヘッダーがページ中段に写り込んだり、背景のグラデーションが間延びして見えたりすることがあります。

ファーストビューの見た目だけを厳密に確認したい場合は、fullPage: false にして初期表示領域だけを切り取るか、撮影用のセレクタを指定して要素単位でキャプチャするのが確実です。

3. waitUntil: 'networkidle' が終わらないケース

WebSocketで常時通信しているページや、数秒ごとにポーリングリクエストを送るダッシュボード画面では、waitUntil: 'networkidle' を指定すると通信が途切れずタイムアウトすることがあります。その場合は waitUntil: 'load' に変えた上で、描画完了の目印となる要素(await page.locator('main').waitFor({ state: 'visible' }) など)を明示的に待つ実装に切り替えます。

Lowom 編集長 編集長
CAUTION JavaScriptでテーマを切り替えるサイトの場合
今回のサンプルはCSSの @media (prefers-color-scheme: dark) で自動切り替えする前提です。Bootstrapの data-bs-theme 属性やTailwindの dark クラスをJavaScriptで付与しているサイトを撮る場合は、page.goto() のあとに page.evaluate() で属性やクラスを付与する処理を1行追加してください。

日々の開発フローへの組み込み

こうした検証スクリプトは、存在を忘れてしまうと使わなくなってしまいます。私はコマンドを毎回手打ちするのを避けるため、justによるクロスプラットフォームなタスク自動化 のレシピとして justfile に登録しています。

# ローカルサーバーに対してレスポンシブ&ダークモードの比較レポートを生成
visual-check url="http://127.0.0.1:1111/":
  TARGET_URL="{{ url }}" FAIL_ON_OVERFLOW=1 node scripts/capture-matrix.mjs

プロジェクトのポート番号に合わせて url のデフォルト値を調整しておけば、いつでも短いコマンドで比較レポートを作成できます。また、リポジトリの品質チェックの文脈では Huskyとlint-stagedによるコミット前チェック のような仕組みと役割を分け、コミット時は高速なリント、PR前やUI改修時は just visual-check で視覚確認というように使い分けるとストレスがありません。

手作業でブラウザ幅を何度もドラッグして確認する時間を減らし、崩れが起きやすい境界幅だけを機械的に並べて点検する仕組みを1つ持っておくと、CSS修正の安心感が大きく変わります。まずは手元のプロジェクトのトップページ1枚から試してみてください。

Lowom 編集長
この記事を書いた人:Lowom 編集長 現役Webエンジニア

都内IT企業に勤める業界20年のWebエンジニア。業務効率化・自動化スクリプトや快適な開発環境の構築、厳選したツール・ガジェットの活用法など、手元で実際に検証したリアルな一次情報をお届けします。