shot-kit

Playwright ベースのスクリーンショット自動撮影ライブラリ。PC / Mobile の Retina 撮影、認証済みセッション共有、タイムスタンプ付き履歴管理に対応。

Installation

npm install shot-kit

前提条件: shot-kit はシステムにインストール済みの Google Chrome を使用します。playwright install によるブラウザのダウンロードは不要です。Chrome が未インストールの場合は google.com/chrome からインストールしてください。

Quick Start

1. 設定ファイルのひな形を生成する

npx shot-kit init

shot-kit/ ディレクトリに以下のファイルが生成されます。

shot-kit/
├── config.ts              # プロジェクト設定
├── auth.ts                # 認証ロジック
└── scenarios/
    └── index.ts           # 撮影シナリオ一覧

2. 設定を編集する

// shot-kit/config.ts
import type { ShotKitProjectConfig } from 'shot-kit';

const config: ShotKitProjectConfig = {
  projectName: 'my-app',
  baseUrl: 'http://localhost:3000',
};

export default config;

// shot-kit/scenarios/index.ts
import type { Scenario } from 'shot-kit';

const scenarios: Scenario[] = [
  { name: 'home-pc',     path: '/',          device: 'pc' },
  { name: 'home-mobile', path: '/',          device: 'mobile' },
  { name: 'dashboard',   path: '/dashboard', device: 'pc' },
];

export default scenarios;

3. 撮影する

npx shot-kit

WSL2 / Docker 環境での注意

launchOptions: { args: ['--no-sandbox'] } が必要な場合があります。config.ts に以下を追加してください。

launchOptions: { args: ['--no-sandbox'] },

CLI

shot-kit [command] [options]

Commands:
  run    (default)  shot-kit/ の設定を読み込んで撮影を実行
  init              shot-kit/ ディレクトリをひな形で初期化

Options:
  --dir, -d <path>  設定ディレクトリのパス (default: shot-kit, or $SHOT_KIT_DIR)
  --force, -f       init 時に既存ファイルを上書き

Authentication

認証が必要なアプリでは shot-kit/auth.ts にログイン処理を実装します。

import type { AuthHandler } from 'shot-kit';

const authHandler: AuthHandler = async (page, config) => {
  await page.goto(`${config.baseUrl}/login`);
  await page.fill('[name="email"]',    process.env['EMAIL'] ?? '');
  await page.fill('[name="password"]', process.env['PASSWORD'] ?? '');
  await page.click('[type="submit"]');
  await page.waitForURL(`${config.baseUrl}/dashboard`);
};

export default authHandler;

認証セッションはデバイスごとに 1 回共有され、全シナリオで再利用されます。認証不要なシナリオは requiresAuth: false を指定します。

auth.ts が存在しない場合、すべてのシナリオが requiresAuth: false であれば正常に動作します。requiresAuth: false を指定していないシナリオ（デフォルトは認証必須扱い）が含まれる場合は実行時エラーになります。

Output Structure

実行ごとにタイムスタンプ付きディレクトリが生成されるため、過去の成果物は上書きされません。

output/
└── my-app/
    └── 20260427-153042/
        ├── pc/
        │   └── dashboard.png
        └── mobile/
            └── home-mobile.png

{outputDir}/{projectName}/{YYYYMMDD-HHmmss}/{device}/{name}.png

Configuration Reference

ShotKitProjectConfig (config.ts)

| Field | Type | Default | |---------------------|----------------------|-------------| | projectName | string | required | | baseUrl | string | required | | outputDir | string | "output" | | viewports | Partial<Viewports> | see below | | deviceScaleFactor | number | 2 (@2x) | | navigationTimeout | number (ms) | 30000 | | launchOptions | LaunchOptions | — |

WSL2 / Docker 環境での設定は WSL2 / Docker 環境での注意 を参照してください。

Default Viewports

| Device | Width | Height | |--------|-------|--------| | pc | 1280 | 800 | | mobile | 390 | 844 |

Scenario

| Field | Type | Default | |----------------|---------------------------------|----------| | name | string | required | | path | string (starts with /) | required | | device | 'pc' \| 'mobile' | required | | requiresAuth | boolean | true | | action | (page: Page) => Promise<void> | — |

action を使うとページ到達後・撮影前にインタラクションを差し込めます（モーダルを開く、タブを切り替えるなど）。

{
  name: 'dashboard-modal',
  path: '/dashboard',
  device: 'pc',
  action: async (page) => {
    await page.click('[data-testid="open-modal"]');
    await page.waitForSelector('[role="dialog"]');
  },
},

Programmatic API

CLI を使わずコードから直接呼び出すこともできます。runRunner の引数は ScreenshotConfig 型です（ShotKitProjectConfig のすべてのフィールドに加え、scenarios と authHandler を含む完全な設定オブジェクト）。

import { runRunner } from 'shot-kit';
import type { ScreenshotConfig } from 'shot-kit';

const config: ScreenshotConfig = {
  projectName: 'my-app',
  baseUrl: 'http://localhost:3000',
  scenarios: [{ name: 'home', path: '/', device: 'pc' }],
};

await runRunner(config);

License

MIT