E2E OCR Rules

Use this skill when asserting text that is not in the DOM, such as PDF content drawn only to <canvas>. Keep OCR in test infrastructure, not product code.

Tesseract Setup

• Use tesseract.js, a root devDependency, for canvas-only assertions via cy.task.
• Register a Node task in e2e_test/config/common.ts.
• The task should call tesseract.js createWorker and recognize on image bytes, such as base64 PNG without the data:image/png;base64, prefix.
• Example task name: ocrCanvasImage.

Language Data

• Commit e2e_test/tesseract/eng.traineddata uncompressed.
• Pass langPath and cachePath to that directory when creating the worker.
• This prevents Tesseract from writing eng.traineddata to the repo root. Root-level traineddata files are gitignored as a fallback.

Page Object Pattern

• Wait until the canvas has real ink before OCR. Sampling getImageData for dark pixels is better than checking only non-zero alpha, because an empty white fill can still have alpha.
• Export with toDataURL("image/png").
• Strip the data URL prefix.
• Use cy.task(..., { timeout: ... }) for slow OCR.
• Assert the returned string contains the expected substring with a clear message.
• Reference: e2e_test/start/pageObjects/bookReadingPage.ts, from expectPdfBeginningVisible through expectCurrentPage(1).expectVisibleOCRContains.