Developer Documentation

npm install --save-dev @freetextfromimage/rendercheck

import { test } from '@playwright/test';
import { expect } from '@freetextfromimage/rendercheck/playwright';

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)
  });
});

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

interface AssertionOptions {
  region?: { x: number; y: number; width: number; height: number }; // screenshot pixels
  minConfidence?: number;     // 0-100, default 80
  minContrastRatio?: number;  // WCAG, e.g. 4.5 (normal text) or 3 (large text). Off unless set
  exact?: boolean;            // text must equal the expected text, not just contain it
  ignoreCase?: boolean;       // default false
  dom?: boolean;              // with a Locator, also compare with innerText. Default true
  timeout?: number;           // Playwright retry window in ms. Default 5000
  interval?: number;          // Playwright pause between attempts in ms. Default 250
  fullPage?: boolean;         // Playwright: capture the whole scrollable page
  lang?: string;              // Tesseract language code. Default 'eng'
  langPath?: string;          // folder with <lang>.traineddata.gz for other languages
}

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

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

// report.failure: 'NOT_FOUND' | 'LOW_CONFIDENCE' | 'INSUFFICIENT_CONTRAST' | 'DOM_MISMATCH'
// report.read, report.confidence (0-100), report.similarity (0-1), report.minContrast

import { test } from '@playwright/test';
import { expect } from '@freetextfromimage/rendercheck/playwright';

test('order confirmation displays the order number', async ({ page }) => {
  await page.goto('/order-confirmation');

  // One element: also compared with its DOM text.
  await expect(page.locator('#order-number')).toShowText('Order #ABC123456');

  // Only part of the screenshot.
  await expect(page).toShowText('Pay now', { region: { x: 120, y: 340, width: 200, height: 40 } });

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

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

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

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

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