@flighthq/bitmap 0.5.0-next.1944.cd6b6e7 → 0.5.1-edge.638.d4dbd4e

package/src/explainBitmapReadback.test.ts

@@ -1,6 +1,13 @@
+import type { BitmapReadbackBackend, BitmapReadbackBackendReason } from '@flighthq/types/contract';
 import { describe, expect, it, vi } from 'vitest';
 
+import { createBitmap } from './bitmap';
 import { createBitmapFromImageSource } from './bitmapFrom';
+import {
+  installBitmapReadbackHostBackend,
+  resetBitmapReadbackBackendForTest,
+  setBitmapReadbackBackend,
+} from './bitmapReadbackBackend';
 import { explainBitmapReadback } from './explainBitmapReadback';
 
 function makeCanvas(width = 8, height = 4): HTMLCanvasElement {
@@ -10,75 +17,88 @@ function makeCanvas(width = 8, height = 4): HTMLCanvasElement {
   return canvas;
 }
 
+afterEach(() => {
+  resetBitmapReadbackBackendForTest();
+});
+
 describe('explainBitmapReadback', () => {
-  it('reports a readable source as ok', () => {
-    expect(explainBitmapReadback(makeCanvas(), 8, 4)).toEqual({ readable: true, reason: 'ok' });
-  });
+  it('reports empty-size before selecting or touching a backend', () => {
+    const readBitmap = vi.fn(() => ({ bitmap: null, reason: 'tainted-source' as const }));
+    setBitmapReadbackBackend({ readBitmap });
 
-  it('reports an empty capture without touching the source', () => {
     expect(explainBitmapReadback(makeCanvas(), 0, 4)).toEqual({ readable: false, reason: 'empty-size' });
     expect(explainBitmapReadback(makeCanvas(), 8, 0)).toEqual({ readable: false, reason: 'empty-size' });
     expect(explainBitmapReadback(makeCanvas(), -1, 4)).toEqual({ readable: false, reason: 'empty-size' });
+    expect(createBitmapFromImageSource(makeCanvas(), 8, -1)).toBeNull();
+    expect(readBitmap).not.toHaveBeenCalled();
   });
 
-  it('reports a tainted source', () => {
-    const spy = vi.spyOn(CanvasRenderingContext2D.prototype, 'getImageData').mockImplementation(() => {
-      throw new DOMException('Tainted canvases may not be exported.', 'SecurityError');
-    });
-    try {
-      expect(explainBitmapReadback(makeCanvas(), 8, 4)).toEqual({ readable: false, reason: 'tainted-source' });
-    } finally {
-      spy.mockRestore();
-    }
-  });
+  it('distinguishes an absent backend from a host with no canvas', () => {
+    const source = makeCanvas();
 
-  it('prefers the reason knowable without drawing — an empty capture outranks a tainted source', () => {
-    const spy = vi.spyOn(CanvasRenderingContext2D.prototype, 'getImageData').mockImplementation(() => {
-      throw new DOMException('Tainted canvases may not be exported.', 'SecurityError');
+    expect(explainBitmapReadback(source, 8, 4)).toEqual({
+      readable: false,
+      reason: 'backend-not-installed',
     });
-    try {
-      expect(explainBitmapReadback(makeCanvas(), 0, 4).reason).toBe('empty-size');
-    } finally {
-      spy.mockRestore();
-    }
+    expect(createBitmapFromImageSource(source, 8, 4)).toBeNull();
   });
 
-  it('agrees with what createBitmapFromImageSource actually does', () => {
-    // The pull query duplicates the constructor's failure conditions by design, so the pairing is the
-    // thing worth pinning: readable exactly when a bitmap comes back.
-    const canvas = makeCanvas();
-    expect(explainBitmapReadback(canvas, 8, 4).readable).toBe(createBitmapFromImageSource(canvas, 8, 4) !== null);
-    expect(explainBitmapReadback(canvas, 0, 4).readable).toBe(createBitmapFromImageSource(canvas, 0, 4) !== null);
+  it('treats custom selection as terminal when a hidden host would succeed', () => {
+    const hostBitmap = createBitmap(8, 4);
+    const hostRead = vi.fn<BitmapReadbackBackend['readBitmap']>((_source, _width, _height, mode) => ({
+      bitmap: mode === 'bitmap' ? hostBitmap : null,
+      reason: 'ok' as const,
+    }));
+    const customRead = vi.fn(() => ({ bitmap: null, reason: 'no-canvas' as const }));
+    installBitmapReadbackHostBackend({ readBitmap: hostRead });
+    setBitmapReadbackBackend({ readBitmap: customRead });
+    const source = makeCanvas();
 
-    const spy = vi.spyOn(CanvasRenderingContext2D.prototype, 'getImageData').mockImplementation(() => {
-      throw new DOMException('Tainted canvases may not be exported.', 'SecurityError');
-    });
-    try {
-      expect(explainBitmapReadback(canvas, 8, 4).readable).toBe(createBitmapFromImageSource(canvas, 8, 4) !== null);
-    } finally {
-      spy.mockRestore();
-    }
+    expect(createBitmapFromImageSource(source, 8, 4)).toBeNull();
+    expect(explainBitmapReadback(source, 8, 4)).toEqual({ readable: false, reason: 'no-canvas' });
+    expect(customRead).toHaveBeenCalledTimes(2);
+    expect(hostRead).not.toHaveBeenCalled();
   });
 
-  it('never throws, whatever the source does', () => {
-    const spy = vi.spyOn(CanvasRenderingContext2D.prototype, 'drawImage').mockImplementation(() => {
-      throw new TypeError('unsupported source');
-    });
-    try {
-      expect(() => explainBitmapReadback(makeCanvas(), 8, 4)).not.toThrow();
-      expect(explainBitmapReadback(makeCanvas(), 8, 4).readable).toBe(false);
-    } finally {
-      spy.mockRestore();
-    }
+  it('returns the exact success outcome and keeps constructor/explainer parity', () => {
+    const bitmap = createBitmap(8, 4);
+    const readBitmap: BitmapReadbackBackend['readBitmap'] = vi.fn((_source, _width, _height, mode) => ({
+      bitmap: mode === 'bitmap' ? bitmap : null,
+      reason: 'ok' as const,
+    }));
+    setBitmapReadbackBackend({ readBitmap });
+    const source = makeCanvas();
+
+    expect(createBitmapFromImageSource(source, 8, 4)).toBe(bitmap);
+    expect(explainBitmapReadback(source, 8, 4)).toEqual({ readable: true, reason: 'ok' });
+    expect(readBitmap).toHaveBeenNthCalledWith(1, source, 8, 4, 'bitmap');
+    expect(readBitmap).toHaveBeenNthCalledWith(2, source, 8, 4, 'probe');
   });
 
-  it('allocates no bitmap — it reads one pixel, not the whole capture', () => {
-    const spy = vi.spyOn(CanvasRenderingContext2D.prototype, 'getImageData');
-    try {
-      explainBitmapReadback(makeCanvas(1024, 1024), 1024, 1024);
-      expect(spy).toHaveBeenCalledWith(0, 0, 1, 1);
-    } finally {
-      spy.mockRestore();
-    }
+  it.each(['no-canvas', 'tainted-source'] satisfies readonly BitmapReadbackBackendReason[])(
+    'preserves the exact expected-failure reason %s',
+    (reason) => {
+      const backend: BitmapReadbackBackend = { readBitmap: () => ({ bitmap: null, reason }) };
+      setBitmapReadbackBackend(backend);
+      const source = makeCanvas();
+
+      expect(createBitmapFromImageSource(source, 8, 4)).toBeNull();
+      expect(explainBitmapReadback(source, 8, 4)).toEqual({ readable: false, reason });
+    },
+  );
+
+  it('does not predict a full-read allocation fault from a successful probe', () => {
+    const fault = new RangeError('full bitmap allocation failed');
+    const backend: BitmapReadbackBackend = {
+      readBitmap(_source, _width, _height, mode) {
+        if (mode === 'bitmap') throw fault;
+        return { bitmap: null, reason: 'ok' };
+      },
+    };
+    setBitmapReadbackBackend(backend);
+    const source = makeCanvas();
+
+    expect(explainBitmapReadback(source, 8, 4)).toEqual({ readable: true, reason: 'ok' });
+    expect(() => createBitmapFromImageSource(source, 8, 4)).toThrow(fault);
   });
 });