mdmark

描いた図を確かめる

置いた部品を Playwright で動かし、スクリーンショットを撮って見る手順

文書に図や操作できる部品を置いた後、動きと見た目を確かめるときに実行する。置いただけで終えず、動かして、撮って、見るところまでを 1 回の作業にする。

前提

図を描くか操作できる部品を作るで部品を置いた文書を、ページで描ける
Node 24 以降
Playwright と Chromium が入っている

npm install --save-dev playwright
npx playwright install chromium

手順

動かす

部品を操作する Playwright のスクリプトを書く

import { chromium } from "playwright";

const browser = await chromium.launch();
const context = await browser.newContext({
  viewport: { width: 1280, height: 800 },
  permissions: ["clipboard-read", "clipboard-write"],
});
const page = await context.newPage();
await page.goto("http://127.0.0.1:8080/index.html");

const flow = page.locator('figure.mdmark-diagram[data-diagram="flow"]');
console.log("開いたとき", await flow.getByLabel("倍率").textContent());

await flow.getByRole("button", { name: "拡大" }).click();
console.log("拡大", await flow.getByLabel("倍率").textContent());

await flow.getByRole("button", { name: "全体が収まる倍率に戻す" }).click();
console.log("戻す", await flow.getByLabel("倍率").textContent());

const slider = page.locator('.mdmark-param input[type="range"]');
await slider.fill("8");
await page.getByRole("button", { name: /写す/ }).click();
console.log("写した JSON", await page.evaluate(() => navigator.clipboard.readText()));

await browser.close();

ページの URL は、文書を描くページに合わせる。ボタンは読み上げの名前で探す。図のボタンの名前は 縮小・拡大・倍率 {今の倍率}。全体が収まる倍率に戻す・全画面で開く・全画面を閉じる・左へ動かす・上へ動かす・下へ動かす・右へ動かす。戻すのボタンは倍率のボタンにまとめてあり、getByLabel("倍率") と getByRole の name: "全体が収まる倍率に戻す" のどちらも、部分一致で見つかる。倍率のボタンの文字は 125% の形で、倍率が変わるたびに読み上げの名前も書き換わる。

通す操作

次の操作を、置いた部品に当たるものについて通す。

部品	操作	期待
図	開く	全体が収まる倍率で、縮小が押せない（倍率のボタンは押せるが、何も変わらない）
図	拡大のボタン・`+`	倍率が 1.25 倍ずつ上がり、300% で拡大が押せなくなる
図	縮小のボタン・`-`	倍率が 1.25 倍ずつ下がり、開いたときの倍率で縮小が押せなくなる
図	倍率のボタン・`0`	開いたときの倍率と位置に戻る
図	拡大した後に矢印キー	押した向きの先が見えるように動く
図	拡大した後に余白をドラッグ	ドラッグした分だけ動き、文字は選ばれない
図	箱の文字の上でドラッグ	文字が選ばれ、図は動かない
図	ホイール	倍率が変わらず、文書がスクロールする
図	矢印のラベルと、`io` か `hint` を持つ箱の右上の印にフォーカス	ツールチップが出て、Esc で消える。箱の上では開かない
図	全画面のボタン	モーダルが開き、Esc か閉じるボタンで閉じてフォーカスが戻る
操作できる部品	スライダーを動かす	今の値とグラフが追従する
操作できる部品	今の値を写すボタン	クリップボードの JSON が画面の値と一致する

撮る

状態ごとにスクリーンショットを撮る

await page.screenshot({ path: "shots/doc-1280.png", fullPage: true });
await flow.screenshot({ path: "shots/flow-fit.png" });

await flow.getByRole("button", { name: "拡大" }).click();
await flow.screenshot({ path: "shots/flow-zoomed.png" });

await page.emulateMedia({ colorScheme: "dark" });
await flow.screenshot({ path: "shots/flow-dark.png" });

await page.setViewportSize({ width: 390, height: 844 });
await flow.screenshot({ path: "shots/flow-390.png" });

撮る状態は、開いたとき・拡大したとき・ダーク・狭い幅（390px）。ツールチップやモーダルを置いたときは、開いた状態でも撮る。部品を変えたときは、部品のストーリーと見本のページも撮る。

見る

撮った画像を開いて見る

撮るだけで終えず、画像を開いて目で見る。画像を見られない環境（AI 含む）では、画像を読み込める手段で開く。

見るところ。

箱の文字が箱からはみ出していない。長い名前は箱の中で折り返している
線が箱や文字を横切っていない。交差は横の線が縦の線を飛び越えている
凡例に、図にある色・形・線・矢じりが全て載っている
ダークでも文字と線が読める
狭い幅でも、全体が収まる倍率で開いている

崩れがあれば定義の座標や文言を直し、動かして、撮って、見るのをやり直す。決まりは構成図の決まりとフローチャートの決まり。

反映

なし。スクリプトとスクリーンショットは確かめるためのもので、文書にも配布物にも入らない。

確認

通した操作が全て期待どおり

スクリプトの出力が、上の表の期待と合う。スクリーンショットに崩れが無い。

元に戻す

スクリプトとスクリーンショットを消す。