test: drive the real nativeImage FFI with a generated PNG fixture asserting exact scalar getSize on macOS and Linux

Author: ipfizz

tests/fixtures/tiny-png.ts

@@ -0,0 +1,88 @@
+import { rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { deflateSync } from 'node:zlib';
+
+/**
+ * A deterministic tiny-PNG fixture for the `nativeImage` integration tests.
+ *
+ * The bytes are GENERATED in code (a minimal 8-bit RGBA PNG encoder) rather than
+ * embedded, so the asserted width/height are guaranteed to match the file the
+ * native decoder reads — proving the scalar `getSize` path returns the EXACT
+ * known dimensions, not a coincidence of some opaque blob.
+ */
+
+/** The fixture's known dimensions, asserted exactly by the integration tests. */
+export const TINY_PNG_WIDTH = 3;
+export const TINY_PNG_HEIGHT = 2;
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n += 1) {
+    let c = n;
+    for (let k = 0; k < 8; k += 1) {
+      c = (c & 1) === 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    }
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+const crc32 = (buffer: Uint8Array): number => {
+  let crc = 0xffffffff;
+  for (let i = 0; i < buffer.length; i += 1) {
+    const byte = buffer[i] ?? 0;
+    crc = (CRC_TABLE[(crc ^ byte) & 0xff] ?? 0) ^ (crc >>> 8);
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+};
+
+const chunk = (type: string, data: Uint8Array): Buffer => {
+  const length = Buffer.alloc(4);
+  length.writeUInt32BE(data.length, 0);
+  const body = Buffer.concat([Buffer.from(type, 'ascii'), Buffer.from(data)]);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(body), 0);
+  return Buffer.concat([length, body, crc]);
+};
+
+/** Build the fixture's PNG bytes (a {@link TINY_PNG_WIDTH}×{@link TINY_PNG_HEIGHT} opaque-red image). */
+export const makeTinyPng = (): Uint8Array => {
+  const signature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(TINY_PNG_WIDTH, 0);
+  ihdr.writeUInt32BE(TINY_PNG_HEIGHT, 4);
+  ihdr[8] = 8; // bit depth
+  ihdr[9] = 6; // color type: RGBA
+  const stride = 1 + TINY_PNG_WIDTH * 4;
+  const raw = Buffer.alloc(TINY_PNG_HEIGHT * stride);
+  for (let y = 0; y < TINY_PNG_HEIGHT; y += 1) {
+    const row = y * stride;
+    raw[row] = 0; // filter: none
+    for (let x = 0; x < TINY_PNG_WIDTH; x += 1) {
+      const p = row + 1 + x * 4;
+      raw[p] = 255; // R
+      raw[p + 3] = 255; // A
+    }
+  }
+  return new Uint8Array(
+    Buffer.concat([
+      signature,
+      chunk('IHDR', ihdr),
+      chunk('IDAT', deflateSync(raw)),
+      chunk('IEND', Buffer.alloc(0)),
+    ]),
+  );
+};
+
+/** Write the fixture PNG to a unique temp file and return its absolute path. */
+export const writeTinyPngFile = (): string => {
+  const path = join(tmpdir(), `sambar-native-image-${process.pid}-${Date.now()}.png`);
+  writeFileSync(path, makeTinyPng());
+  return path;
+};
+
+/** Delete a fixture file written by {@link writeTinyPngFile} (best-effort). */
+export const removeTinyPngFile = (path: string): void => {
+  rmSync(path, { force: true });
+};

tests/integration/linux/gdk-native-image.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, test } from 'bun:test';
+import { currentPlatform } from '../../../src/common/platform';
+import { nativeImage, setNativeImageBackendForTesting } from '../../../src/main/api/native-image';
+import { loadGdkPixbufFFI } from '../../../src/main/platform/linux/gdk-pixbuf-ffi';
+import {
+  removeTinyPngFile,
+  TINY_PNG_HEIGHT,
+  TINY_PNG_WIDTH,
+  makeTinyPng,
+  writeTinyPngFile,
+} from '../../fixtures/tiny-png';
+
+/**
+ * Real `nativeImage` on a Linux host, driving the live GdkPixbuf FFI. Mirrors
+ * the macOS integration suite: `getSize()` must return the EXACT known fixture
+ * dimensions via the scalar `gdk_pixbuf_get_width`/`get_height` getters, and
+ * `toPNG()` must carry the PNG signature.
+ *
+ * GdkPixbuf does NOT require `gtk_init_check`, but the loader must resolve the
+ * library first; if `libgdk_pixbuf-2.0.so.0` is absent the load throws and the
+ * test fails loudly (rather than silently passing), which is the honest signal
+ * that the CI runner needs the package installed.
+ */
+if (currentPlatform() === 'linux') {
+  describe('gdk-native-image on Linux', () => {
+    test('gdk-pixbuf-ffi resolves the load/query/encode symbols', () => {
+      const pixbuf = loadGdkPixbufFFI();
+      for (const name of [
+        'gdk_pixbuf_new_from_file',
+        'gdk_pixbuf_new_from_stream',
+        'gdk_pixbuf_get_width',
+        'gdk_pixbuf_get_height',
+        'gdk_pixbuf_save_to_bufferv',
+      ] as const) {
+        expect(typeof pixbuf.symbols[name]).toBe('function');
+      }
+    });
+
+    test('createFromPath getSize returns the EXACT known fixture dimensions via the scalar path', () => {
+      setNativeImageBackendForTesting(undefined);
+      const fixture = writeTinyPngFile();
+      try {
+        const image = nativeImage.createFromPath(fixture);
+        expect(image.isEmpty()).toBe(false);
+        const size = image.getSize();
+        expect(size.width).toBe(TINY_PNG_WIDTH);
+        expect(size.height).toBe(TINY_PNG_HEIGHT);
+      } finally {
+        removeTinyPngFile(fixture);
+      }
+    });
+
+    test('createFromBuffer decodes PNG bytes to the same exact dimensions', () => {
+      setNativeImageBackendForTesting(undefined);
+      const image = nativeImage.createFromBuffer(makeTinyPng());
+      expect(image.isEmpty()).toBe(false);
+      expect(image.getSize().width).toBe(TINY_PNG_WIDTH);
+      expect(image.getSize().height).toBe(TINY_PNG_HEIGHT);
+    });
+
+    test('toPNG returns non-empty bytes starting with the PNG signature', () => {
+      setNativeImageBackendForTesting(undefined);
+      const fixture = writeTinyPngFile();
+      try {
+        const png = nativeImage.createFromPath(fixture).toPNG();
+        expect(png.length > 0).toBe(true);
+        expect(png[0]).toBe(0x89);
+        expect(png[1]).toBe(0x50);
+        expect(png[2]).toBe(0x4e);
+        expect(png[3]).toBe(0x47);
+      } finally {
+        removeTinyPngFile(fixture);
+      }
+    });
+
+    test('a bad path decodes to an empty image (no crash)', () => {
+      setNativeImageBackendForTesting(undefined);
+      const image = nativeImage.createFromPath('/no/such/sambar/image.png');
+      expect(image.isEmpty()).toBe(true);
+      expect(image.getSize()).toEqual({ width: 0, height: 0 });
+      expect(image.toPNG().length).toBe(0);
+    });
+  });
+}

tests/integration/macos/cocoa-native-image.test.ts

@@ -0,0 +1,75 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { currentPlatform } from '../../../src/common/platform';
+import { nativeImage, setNativeImageBackendForTesting } from '../../../src/main/api/native-image';
+import {
+  removeTinyPngFile,
+  TINY_PNG_HEIGHT,
+  TINY_PNG_WIDTH,
+  makeTinyPng,
+  writeTinyPngFile,
+} from '../../fixtures/tiny-png';
+
+/**
+ * Real `nativeImage` on a macOS host, driving the live `NSBitmapImageRep`/`NSData`
+ * FFI. The headline assertion is that `getSize()` returns the EXACT known
+ * dimensions of the generated fixture via the SCALAR `pixelsWide`/`pixelsHigh`
+ * path — proving the struct-free workaround for the un-returnable `NSImage.size`
+ * `NSSize` struct.
+ *
+ * No NSApplication / window server is needed: `NSBitmapImageRep` decoding is
+ * pure Foundation/AppKit image work, not UI.
+ */
+if (currentPlatform() === 'macos') {
+  describe('cocoa-native-image', () => {
+    let fixture: string;
+
+    beforeAll(() => {
+      // Use the real macOS backend (clear any fake a unit test may have left set).
+      setNativeImageBackendForTesting(undefined);
+      fixture = writeTinyPngFile();
+    });
+
+    afterAll(() => {
+      removeTinyPngFile(fixture);
+    });
+
+    test('createFromPath getSize returns the EXACT known fixture dimensions via the scalar path', () => {
+      const image = nativeImage.createFromPath(fixture);
+      expect(image.isEmpty()).toBe(false);
+      const size = image.getSize();
+      expect(size.width).toBe(TINY_PNG_WIDTH);
+      expect(size.height).toBe(TINY_PNG_HEIGHT);
+    });
+
+    test('createFromBuffer decodes PNG bytes to the same exact dimensions', () => {
+      const image = nativeImage.createFromBuffer(makeTinyPng());
+      expect(image.isEmpty()).toBe(false);
+      expect(image.getSize().width).toBe(TINY_PNG_WIDTH);
+      expect(image.getSize().height).toBe(TINY_PNG_HEIGHT);
+    });
+
+    test('toPNG returns non-empty bytes starting with the PNG signature', () => {
+      const png = nativeImage.createFromPath(fixture).toPNG();
+      expect(png.length > 0).toBe(true);
+      // 0x89 'P' 'N' 'G'
+      expect(png[0]).toBe(0x89);
+      expect(png[1]).toBe(0x50);
+      expect(png[2]).toBe(0x4e);
+      expect(png[3]).toBe(0x47);
+    });
+
+    test('toDataURL starts with the PNG data-URL prefix and carries a payload', () => {
+      const url = nativeImage.createFromPath(fixture).toDataURL();
+      expect(url.startsWith('data:image/png;base64,')).toBe(true);
+      expect(url.length > 'data:image/png;base64,'.length).toBe(true);
+    });
+
+    test('a bad path decodes to an empty image (no crash)', () => {
+      const image = nativeImage.createFromPath('/no/such/sambar/image.png');
+      expect(image.isEmpty()).toBe(true);
+      expect(image.getSize()).toEqual({ width: 0, height: 0 });
+      expect(image.toPNG().length).toBe(0);
+      expect(image.toDataURL()).toBe('data:image/png;base64,');
+    });
+  });
+}