rendercheck

RenderCheck

DOM の内容だけでなく、ユーザーが実際に目にするものを検証します。RenderCheck はスクリーンショットを撮影し、お使いのマシン上で OCR を実行します。レンダリングされたテキストが間違っている、薄すぎて読めない、またはまったく表示されていない場合は、明確なメッセージを表示して Playwright または Cypress のテストを失敗させます。

名称変更。 0.4.1 までは、このパッケージは @freetextfromimage/rendercheck として公開されていました。0.5.0 からは @rendercheck/sdk です。API に変更はありません。移行手順については CHANGELOG をご覧ください。

• ローカルのみ。 OCR はプロセス内で実行されます（Tesseract.js、WebAssembly）。API キーもアップロードもネットワーク呼び出しも不要です。英語の言語データはパッケージに含まれています。
• DOM テストでは検出できない問題を検出： $ であるべき箇所に € が表示される、別の要素にテキストが覆われている、コントラストが低いテキスト、DOM にはあるのに画面には表示されないテキストなど。
• CI と相性良好。 ネイティブモジュールは不要（PNG／JPEG のデコードは純粋な JavaScript で実行）で、ブラウザー側のコードもありません。

Expected to find text "[Total: $14.00]" but OCR read "[Total: €14.00]" (Confidence: 96%)
  Diff: Total: [$]14.00  →  Total: [€]14.00

インストール

npm install --save-dev @rendercheck/sdk

Node 18 以降、および @playwright/test（≥ 1.40）または cypress（≥ 12）が必要です。

Playwright

import { test } from '@playwright/test';
import { expect } from '@rendercheck/sdk/playwright'; // Playwright's expect + toShowText

test('checkout shows the right total', async ({ page }) => {
  await page.goto('/checkout');

  await expect(page).toShowText('Total: $14.00', {
    minConfidence: 85,      // OCR confidence of the matched words (default 80)
    minContrastRatio: 4.5,  // WCAG contrast of the matched words (off unless set)
  });

  // One element: also compared with its DOM text (innerText).
  await expect(page.locator('#total')).toShowText('Total: $14.00');

  // Only part of the screenshot (CSS pixels from its top-left corner).
  await expect(page).toShowText('Pay now', { region: { x: 120, y: 340, width: 200, height: 40 } });

  await expect(page).not.toShowText('Total: €14.00');
});

Playwright 独自のアサーションと同様に、toShowText は成功するか、timeout（デフォルトは 5000 ms）に達するまで再試行します。 すでに expect.extend を使用していますか？ 同じパスから toShowText をインポートし、ご自身で追加してください。

正しいロケールでの価格と日付

await expect(page).toShowCurrency(1234.5, { currency: 'EUR', locale: 'de-DE' }); // expects "1.234,50 €"
await expect(page).toShowDate('2026-03-04', { locale: 'en-GB' });               // expects "04/03/2026"
await expect(page).toShowDate('2026-03-04', { locale: 'en-GB', format: { day: 'numeric', month: 'long', year: 'numeric' } });

期待されるテキストは Intl から取得されるため、各ロケールの区切り記号、通貨記号の位置、日付の順序が自動的に適用されます。画面に別の内容が表示される場合は、失敗メッセージにその内容が示されます。 The screen shows USD ($14.00), not GBP (£14.00). または The date is formatted for en-US (03/04/2026), but en-GB should show 04/03/2026. のように表示されます。 dateTimeZone を渡さない場合、日付には UTC が使用されるため、どの CI マシンでも同じ結果になります。

Cypress でも同じチェックを利用できます：cy.matchCurrency(1234.5, { currency: 'EUR', locale: 'de-DE' }) および cy.matchDate('2026-03-04', { locale: 'en-GB' })。ほかのツールでは、（パッケージのルートからインポートする）expectedCurrency と expectedDate を使うと、toShowText に渡すテキストを取得できます。

右から左に書く言語など。 すべての比較で方向マークとノーブレークスペースは無視されるため、Intl の出力と DOM のテキストは OCR の読み取り結果と一致します。パッケージに含まれる OCR データは英語のみです。アラビア語、ヘブライ語、日本語などを使う場合は、.traineddata ファイルをダウンロードして langPath を設定してください。言語はロケールから選択されます（ar-EG では ara が使用されます）。または、lang をご自身で設定してください。アラビア語のロケールではアラビア・インド数字が使われるため、١٤٫٠٠ と表示されるべき箇所に 14.00 が表示されるページは失敗します。通常はこれが望ましい動作です。

Cypress

// cypress.config.ts
import { defineConfig } from 'cypress';
import { registerRenderCheck } from '@rendercheck/sdk/cypress/plugin';

export default defineConfig({
  e2e: { setupNodeEvents(on) { registerRenderCheck(on); } },
});

// cypress/support/e2e.ts
import '@rendercheck/sdk/cypress';

// in a test
cy.visit('/checkout');
cy.matchText('Total: $14.00', { minConfidence: 85, minContrastRatio: 4.5 });
cy.get('#total').matchText('Total: $14.00');

実際の Cypress（13.17、Electron、Linux）でテスト済みです：examples/cypress は、失敗するケースを含め、モックのチェックアウトページに対して 5 つの spec を実行します。ほかの Cypress バージョンやブラウザーではテストされていません。 npm run build && npx cypress@13 run --project examples/cypress で実行してください（--browser electron を追加します）。

コマンドラインと AI エージェント

ターミナル、スクリプト、または AI コーディングエージェントからスクリーンショットをチェックできます。ローカルでオフラインの OCR を同じように利用できます。

npx @rendercheck/sdk verify screenshot.png --expect "Total: $14.00" --min-contrast 4.5
npx @rendercheck/sdk read screenshot.png --json

終了コード 0 は成功、1 はアサーションの失敗、2 はエラーを意味します。--json は { pass, failure, read, confidence, box, message } を出力します。

MCP サーバー

rendercheck mcp は、標準入出力を介して動作する Model Context Protocol サーバーで、2 つのツールを提供します： verify_text（このテキストは本当に表示され、判読可能で、読める状態ですか？）と read_text（ユーザーには何が見えていますか？）。

{
  "mcpServers": {
    "rendercheck": { "command": "npx", "args": ["-y", "@rendercheck/sdk", "mcp"] }
  }
}

Claude Code：claude mcp add rendercheck -- npx -y @rendercheck/sdk mcp。

リポジトリ内のすべてのエージェントを、1 つの手順でセットアップできます：

npx @rendercheck/sdk init            # Claude Code, Codex/AGENTS.md, Cursor, Copilot
npx @rendercheck/sdk init --agents claude,cursor --dry-run

短い指示（「UI を変更した後は、verify_text でピクセルを検証する」）と MCP サーバーのエントリーを追加します。再実行しても安全です。マークされた RenderCheck ブロックのみが更新されます。

実行回数はお使いのマシン上の ~/.rendercheck/usage.jsonl に記録されるため、rendercheck stats で確認できます。 スクリーンショットのテキストは記録されず、情報が外部に送信されることもありません。無効にするには RENDERCHECK_NO_USAGE_LOG=1 を設定してください。

コア

import { verifyText } from '@rendercheck/sdk/core';

const report = await verifyText({
  image: fs.readFileSync('screenshot.png'), // PNG or JPEG
  expected: 'Total: $14.00',
  options: { minContrastRatio: 4.5 },
});
if (!report.pass) console.error(report.message);

recognize(image, { region }) は生の OCR 結果（words、lines、画像ピクセル単位のボックス）を返し、 analyzeWordContrast は WCAG のコントラスト計算を行います。独自のアサーションを作成する場合に使用できます。

オプション

オプション	デフォルト
region	スクリーンショット全体	スクリーンショットのピクセル単位での { x, y, width, height }
minConfidence	80	一致した単語に必要な OCR の最低信頼度（0～100）
minContrastRatio	オフ	WCAG コントラスト比の最小値。例：通常のテキストは 4.5、大きなテキストは 3
exact	false	領域内のテキストが期待するテキストを含むだけでなく、完全に一致する必要があるかどうか
ignoreCase	false	指定しない場合、PAY NOW は Pay now と一致しません
dom	true	Locator を指定した場合、要素の DOM テキストとも比較します
timeout / interval	5000 / 250	Playwright：再試行時間と試行間の待機時間（ミリ秒）
fullPage	false	Playwright：スクロール可能なページ全体をキャプチャします
lang / langPath	eng / 同梱	その他の Tesseract 言語：langPath に <lang>.traineddata.gz があるフォルダーを指定します

プルリクエストへの注釈（GitHub Actions）

アサーションが失敗すると、RenderCheck は CI 用の記録を残せます。記録は JSON ファイルと、失敗したテキストを赤枠で囲んだスクリーンショットのコピーです。action/ の GitHub Action はこれらを、失敗したテスト行へのプルリクエスト注釈（「Total: $14.00 を期待しましたが、OCR は Total: €14.00 と読み取りました。失敗した領域：x=140、y=244、219×24 px」）、ジョブのサマリーテーブル、枠で囲んだスクリーンショットを含むダウンロード可能なレポートに変換します。

env:
  RENDERCHECK_REPORT_DIR: rendercheck-report      # on GitHub Actions this is already the default
steps:
  - run: npx playwright test                       # or cypress run
  - uses: ParthibanRajasekaran/text-from-image/packages/rendercheck/action@<ref>
    if: always()

GitHub Actions の外部では、RENDERCHECK_REPORT_DIR を設定しない限り記録はオフです（そこでオフにするには、空文字列を設定します）。失敗は最後の再試行後に一度だけ記録され、再試行が成功すると記録は削除されます。GitHub の注釈は画面上の座標ではなくソース行に付くため、領域はメッセージに記載され、スクリーンショット上にも描画されます。すべてワークフロー内で完結します。サービス、トークン、ネットワークリクエストは不要です。

できることとできないこと

• OCR は完璧ではありません。 l／I／1 や O／0 を誤読したり、テキストを読み飛ばしたりすることがあります。背景が色付きでページが煩雑な場合、薄い色のテキストは見落とされることがよくあります。アサーションの対象を要素（page.locator('#pay')）または region に絞ってください。コントラストチェックの対象となる非常に薄いテキストは、まったく読み取れないことがあります。その場合もアサーションは失敗し、「DOM 内にはあるものの、レンダリングされたピクセル上では見えない」と報告されます。
• コントラストはピクセル上で測定されます（テキストの色と周囲の色を k-means で比較）。CSS から測定するわけではありません。 グラデーション、テキストの背後にある画像、アンチエイリアスのため、測定値は推定値になります。
• 表示されているテキストを検証します。レイアウト、間隔、コントラスト以外の色は確認しません。ビジュアルリグレッションツールと併用してください。置き換えとして使うものではありません。
• 初期状態では英語のみ対応しています。

ネットワーク

このパッケージのコードはネットワークリクエストを行いません。Tesseract 自身のキャッシュも無効になっているため、プロジェクトに何かが書き込まれることもありません。（失敗の記録は唯一の例外で、有効にした場合に限ります。上記を参照してください。）Linux で確認するには、npm run test:offline を実行します。テストはネットワークのない名前空間（unshare -rn）で実行されます。

例

examples/playwright/ は、モックのチェックアウトページ（ローカル HTML ファイル）を対象とする Playwright スイートです。通貨の誤り、コントラスト不足、別の要素によるテキストの遮蔽など、失敗するケースも含まれています。

npx playwright install chromium   # once
npm run test:example

examples/github-actions.yml では、CI での使用例を確認できます。

ライセンス

MIT

リンク

• ドキュメント：https://getrendercheck.com/developers
• ローカル環境で動作する仕組み（アーキテクチャと脅威モデル）：https://getrendercheck.com/security
• 問題と機能リクエスト：https://github.com/ParthibanRajasekaran/text-from-image/issues
• セキュリティレポート：SECURITY.md を参照