Skip to main content

Cypress OCR testing

Assert the text users actually see on screen, not just what is in the DOM, with cy.matchText.

A DOM assertion reads the page's markup. It cannot tell you what a user sees. A € that should be a $, text covered by another element, or text so faint nobody can read it all pass a DOM check. RenderCheck screenshots the page, reads it with OCR on your machine, and fails the test when the rendered text is wrong. Nothing is uploaded and no API key is needed.

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

Install and set up

Terminalbash
npm install --save-dev @freetextfromimage/rendercheck

Requires Node 18+. The English OCR data ships in the package.

Register the plugin

The plugin takes the screenshot and runs OCR in the Node process.

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

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

Load the commands

Import once in your support file.

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

Assertions

Check text on a page or an element

Chain from cy or from a selected element.

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

Prices and dates in the right locale

The expected text comes from Intl, so each locale's separators and date order are applied.

locale.cy.tstypescript
cy.matchCurrency(1234.5, { currency: 'EUR', locale: 'de-DE' });
cy.matchDate('2026-03-04', { locale: 'en-GB' });

Full option list: developer reference.

Things to know

  • Tested in Cypress 13.17 (Electron, Linux). Other Cypress versions and browsers are untested.
  • Requires cypress 12 or newer and Node 18+.
  • Only English OCR data ships in the package. For other scripts, download the .traineddata file and set langPath.
  • OCR is probabilistic. Set minConfidence to a level that suits your fonts.
  • The SDK is in developer beta and has no public adoption numbers yet.

FAQ

Does Cypress OCR testing send screenshots anywhere?

No. OCR runs locally in the Cypress Node process. There is no API key and no network call.

How is cy.matchText different from cy.contains?

cy.contains reads the DOM. cy.matchText reads the rendered pixels, so it fails when text is hidden, covered, the wrong symbol, or too faint to read.

Which Cypress versions are supported?

It targets Cypress 12 and newer and has been run in a real Cypress 13.17 on Electron and Linux. Other versions and browsers are untested.