import sharp from "sharp"; import { beforeAll, describe, expect, it } from "vitest"; import { processImage } from "../src/engine.js"; import { detectFormat } from "../src/formats/detect.js"; import { colorBlindness } from "../src/operations/color-blindness.js"; import { convert } from "../src/operations/convert.js"; import type { ColorBlindnessType } from "../src/types.js"; /** * Build a fixed-length Buffer from an array of byte values, zero-padded to `len`. * Used to hand-craft magic-byte headers that Sharp cannot decode, forcing * detectFormat to fall through to its magic-byte detector. */ function bytes(values: number[], len?: number): Buffer { const buf = Buffer.alloc(len ?? values.length, 0); for (let i = 0; i < values.length; i++) { buf[i] = values[i]; } return buf; } /** Mean value per channel (rounded) of a decoded buffer. */ async function channelMeans(buffer: Buffer): Promise { const stats = await sharp(buffer).stats(); return stats.channels.map((c) => Math.round(c.mean)); } let redPng: Buffer; beforeAll(async () => { redPng = await sharp({ create: { width: 32, height: 32, channels: 3, background: { r: 255, g: 0, b: 0 }, }, }) .png() .toBuffer(); }); describe("detectFormat via Sharp metadata", () => { // Real encodes: Sharp decodes these directly and returns metadata.format, // exercising the sharp-metadata branch (never reaching magic bytes). const realEncodeCases: Array<{ name: string; make: () => Promise; expected: string }> = [ { name: "png", make: () => sharp({ create: base() }).png().toBuffer(), expected: "png", }, { name: "jpeg", make: () => sharp({ create: base() }).jpeg().toBuffer(), expected: "jpeg", }, { name: "webp", make: () => sharp({ create: base() }).webp().toBuffer(), expected: "webp", }, { name: "gif", make: () => sharp({ create: base() }).gif().toBuffer(), expected: "gif", }, { name: "tiff", make: () => sharp({ create: base() }).tiff().toBuffer(), expected: "tiff", }, ]; for (const { name, make, expected } of realEncodeCases) { it(`detects a real ${name} encode as ${expected}`, async () => { const buf = await make(); expect(await detectFormat(buf)).toBe(expected); }); } function base() { return { width: 8, height: 8, channels: 3 as const, background: { r: 10, g: 120, b: 200 }, }; } }); describe("detectFormat via magic bytes", () => { // Every format the magic-byte table recognizes, with hand-built headers that // Sharp cannot decode. Each asserts the EXACT format string, killing the // per-entry string-literal mutants. const magicCases: Array<{ name: string; buf: Buffer; expected: string }> = [ { name: "png magic", buf: bytes([0x89, 0x50, 0x4e, 0x47], 16), expected: "png" }, { name: "jpeg magic", buf: bytes([0xff, 0xd8, 0xff], 16), expected: "jpeg" }, { name: "gif (GIF8)", buf: bytes([0x47, 0x49, 0x46, 0x38, 0x39, 0x61], 16), expected: "gif" }, { name: "tiff little-endian", buf: bytes([0x49, 0x49, 0x2a, 0x00], 16), expected: "tiff" }, { name: "tiff big-endian", buf: bytes([0x4d, 0x4d, 0x00, 0x2a], 16), expected: "tiff" }, { name: "bmp (BM)", buf: bytes([0x42, 0x4d], 16), expected: "bmp" }, { name: "avif ftyp+avif brand", buf: bytes([0, 0, 0, 0x20, 0x66, 0x74, 0x79, 0x70, 0x61, 0x76, 0x69, 0x66], 16), expected: "avif", }, { name: "avif ftyp+avis brand", buf: bytes([0, 0, 0, 0x20, 0x66, 0x74, 0x79, 0x70, 0x61, 0x76, 0x69, 0x73], 16), expected: "avif", }, { name: "jxl ISOBMFF container", buf: bytes([0x00, 0x00, 0x00, 0x0c, 0x4a, 0x58, 0x4c, 0x20], 16), expected: "jxl", }, { name: "jxl raw codestream", buf: bytes([0xff, 0x0a], 16), expected: "jxl" }, { name: "ico", buf: bytes([0x00, 0x00, 0x01, 0x00], 16), expected: "ico" }, { name: "psd (8BPS)", buf: bytes([0x38, 0x42, 0x50, 0x53], 16), expected: "psd" }, { name: "exr", buf: bytes([0x76, 0x2f, 0x31, 0x01], 16), expected: "exr" }, { name: "cr3 ftyp+crx brand", buf: bytes([0, 0, 0, 0x20, 0x66, 0x74, 0x79, 0x70, 0x63, 0x72, 0x78, 0x20], 16), expected: "cr3", }, { name: "raf (FUJIFILMCCD-RAW)", buf: bytes( [0x46, 0x55, 0x4a, 0x49, 0x46, 0x49, 0x4c, 0x4d, 0x43, 0x43, 0x44, 0x2d, 0x52, 0x41, 0x57], 24, ), expected: "raf", }, { name: "x3f (FOVb)", buf: bytes([0x46, 0x4f, 0x56, 0x62], 16), expected: "x3f" }, { name: "mrw (\\x00MRM)", buf: bytes([0x00, 0x4d, 0x52, 0x4d], 16), expected: "mrw" }, { name: "jp2 box signature", buf: bytes([0x00, 0x00, 0x00, 0x0c, 0x6a, 0x50, 0x20, 0x20, 0x0d, 0x0a, 0x87, 0x0a], 16), expected: "jp2", }, { name: "j2k raw codestream", buf: bytes([0xff, 0x4f, 0xff, 0x51], 16), expected: "jp2" }, { name: "dds", buf: bytes([0x44, 0x44, 0x53, 0x20], 16), expected: "dds" }, { name: "cur", buf: bytes([0x00, 0x00, 0x02, 0x00], 16), expected: "cur" }, { name: "dpx forward (SDPX)", buf: bytes([0x53, 0x44, 0x50, 0x58], 16), expected: "dpx" }, { name: "dpx reverse (XPDS)", buf: bytes([0x58, 0x50, 0x44, 0x53], 16), expected: "dpx" }, { name: "cineon", buf: bytes([0x80, 0x2a, 0x5f, 0xd7], 16), expected: "cin" }, { name: "fits (SIMPLE)", buf: bytes([0x53, 0x49, 0x4d, 0x50, 0x4c, 0x45], 16), expected: "fits", }, { name: "eps ASCII (%!PS-Adobe)", buf: bytes([0x25, 0x21, 0x50, 0x53, 0x2d, 0x41, 0x64, 0x6f, 0x62, 0x65], 16), expected: "eps", }, { name: "eps binary (DOS)", buf: bytes([0xc5, 0xd0, 0xd3, 0xc6], 16), expected: "eps" }, { name: "ppm P3", buf: bytes([0x50, 0x33, 0x0a], 16), expected: "ppm" }, { name: "ppm P6", buf: bytes([0x50, 0x36, 0x0a], 16), expected: "ppm" }, { name: "qoi (qoif)", buf: bytes([0x71, 0x6f, 0x69, 0x66], 16), expected: "qoi" }, ]; for (const { name, buf, expected } of magicCases) { it(`detects ${name} as ${expected}`, async () => { expect(await detectFormat(buf)).toBe(expected); }); } describe("webp RIFF secondary verification", () => { it("detects RIFF...WEBP as webp (length 12, correct signature)", async () => { const buf = bytes([0x52, 0x49, 0x46, 0x46, 0, 0, 0, 0, 0x57, 0x45, 0x42, 0x50], 12); expect(await detectFormat(buf)).toBe("webp"); }); it("returns unknown for RIFF with a non-WEBP signature at length 12", async () => { // RIFF matches, buffer >= 12, but bytes 8..12 are "AVI " not "WEBP". const buf = bytes([0x52, 0x49, 0x46, 0x46, 0, 0, 0, 0, 0x41, 0x56, 0x49, 0x20], 16); expect(await detectFormat(buf)).toBe("unknown"); }); it("returns unknown when WEBP signature is one byte off (WEBX)", async () => { const buf = bytes([0x52, 0x49, 0x46, 0x46, 0, 0, 0, 0, 0x57, 0x45, 0x42, 0x58], 12); expect(await detectFormat(buf)).toBe("unknown"); }); it("returns unknown for a RIFF header too short to carry the WEBP signature", async () => { expect(await detectFormat(bytes([0x52, 0x49, 0x46, 0x46], 11))).toBe("unknown"); expect(await detectFormat(bytes([0x52, 0x49, 0x46, 0x46], 4))).toBe("unknown"); }); }); describe("avif ftyp brand verification", () => { it("returns unknown for ftyp box with a non-AVIF brand (mp42)", async () => { const buf = bytes([0, 0, 0, 0x20, 0x66, 0x74, 0x79, 0x70, 0x6d, 0x70, 0x34, 0x32], 16); expect(await detectFormat(buf)).toBe("unknown"); }); it("returns unknown for ftyp box shorter than 12 bytes", async () => { // ftyp present at offset 4 but only 11 bytes: the `< 12` guard hits `continue`. const buf = bytes([0, 0, 0, 0x20, 0x66, 0x74, 0x79, 0x70, 0x61, 0x76, 0x69], 11); expect(await detectFormat(buf)).toBe("unknown"); }); it("detects avif at exactly 12 bytes", async () => { const buf = bytes([0, 0, 0, 0x20, 0x66, 0x74, 0x79, 0x70, 0x61, 0x76, 0x69, 0x66], 12); expect(await detectFormat(buf)).toBe("avif"); }); }); describe("cr3 ftyp brand verification", () => { it("returns unknown for ftyp box with a crx-like-but-wrong brand", async () => { // "crx!" instead of "crx " (trailing space): avif brand check fails, cr3 // brand check also fails, so the ftyp entries fall through to unknown. const buf = bytes([0, 0, 0, 0x20, 0x66, 0x74, 0x79, 0x70, 0x63, 0x72, 0x78, 0x21], 16); expect(await detectFormat(buf)).toBe("unknown"); }); }); describe("single-byte mismatches are not detected", () => { // Feed a header matching every byte but one; assert it is NOT the format. // Kills the per-byte `===`/`!==` comparison and the `offset + i` index mutants. const mismatchCases: Array<{ name: string; buf: Buffer }> = [ { name: "png with wrong 4th byte", buf: bytes([0x89, 0x50, 0x4e, 0x48], 16) }, { name: "jpeg with wrong 2nd byte", buf: bytes([0xff, 0xd7, 0xff], 16) }, { name: "gif with wrong 4th byte", buf: bytes([0x47, 0x49, 0x46, 0x37], 16) }, { name: "tiff LE with wrong 3rd byte", buf: bytes([0x49, 0x49, 0x2b, 0x00], 16) }, { name: "qoi with wrong 1st byte", buf: bytes([0x70, 0x6f, 0x69, 0x66], 16) }, { name: "bmp with wrong 2nd byte", buf: bytes([0x42, 0x4e], 16) }, { name: "psd with wrong last byte", buf: bytes([0x38, 0x42, 0x50, 0x54], 16) }, ]; for (const { name, buf } of mismatchCases) { it(`returns unknown for ${name}`, async () => { expect(await detectFormat(buf)).toBe("unknown"); }); } }); describe("length guard boundaries", () => { it("detects bmp at exactly 2 bytes (offset 0 + 2 magic bytes)", async () => { expect(await detectFormat(bytes([0x42, 0x4d], 2))).toBe("bmp"); }); it("returns unknown for a 1-byte buffer (one short of bmp's 2)", async () => { expect(await detectFormat(bytes([0x42], 1))).toBe("unknown"); }); it("detects gif at exactly 4 bytes (length == offset + magic length)", async () => { expect(await detectFormat(bytes([0x47, 0x49, 0x46, 0x38], 4))).toBe("gif"); }); it("returns unknown for a 3-byte GIF header (one short of 4)", async () => { expect(await detectFormat(bytes([0x47, 0x49, 0x46], 3))).toBe("unknown"); }); it("returns unknown for a 7-byte ftyp buffer (one short of offset 4 + 4)", async () => { expect(await detectFormat(bytes([0, 0, 0, 0x20, 0x66, 0x74, 0x79], 7))).toBe("unknown"); }); }); describe("fallback / negative cases", () => { it("returns unknown for an empty buffer", async () => { expect(await detectFormat(Buffer.alloc(0))).toBe("unknown"); }); it("returns unknown for a 2-byte truncated PNG header", async () => { expect(await detectFormat(bytes([0x89, 0x50], 2))).toBe("unknown"); }); it("returns unknown for random unrecognized bytes", async () => { expect(await detectFormat(bytes([0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88], 16))).toBe( "unknown", ); }); }); }); describe("convert output format and quality", () => { it("maps the jpg alias to a jpeg encode", async () => { const out = await (await convert(sharp(redPng), { format: "jpg" })).toBuffer(); expect((await sharp(out).metadata()).format).toBe("jpeg"); }); it("encodes png without quality changes", async () => { const out = await (await convert(sharp(redPng), { format: "png" })).toBuffer(); expect((await sharp(out).metadata()).format).toBe("png"); }); it("encodes webp, avif, tiff, and gif to their exact formats", async () => { const webp = await (await convert(sharp(redPng), { format: "webp" })).toBuffer(); expect((await sharp(webp).metadata()).format).toBe("webp"); const avif = await (await convert(sharp(redPng), { format: "avif" })).toBuffer(); // Sharp reports avif-encoded data as "heif". expect((await sharp(avif).metadata()).format).toBe("heif"); const tiff = await (await convert(sharp(redPng), { format: "tiff" })).toBuffer(); expect((await sharp(tiff).metadata()).format).toBe("tiff"); const gif = await (await convert(sharp(redPng), { format: "gif" })).toBuffer(); expect((await sharp(gif).metadata()).format).toBe("gif"); }); it("applies quality: lower quality yields a smaller (or equal) jpeg than higher", async () => { const q10 = await (await convert(sharp(redPng), { format: "jpg", quality: 10 })).toBuffer(); const q95 = await (await convert(sharp(redPng), { format: "jpg", quality: 95 })).toBuffer(); expect(q10.length).toBeLessThan(q95.length); }); it("omitting quality does not throw and still produces the target format", async () => { const out = await (await convert(sharp(redPng), { format: "jpg" })).toBuffer(); expect((await sharp(out).metadata()).format).toBe("jpeg"); }); it("accepts the inclusive quality bounds 1 and 100", async () => { await expect( (await convert(sharp(redPng), { format: "jpg", quality: 1 })).toBuffer(), ).resolves.toBeInstanceOf(Buffer); await expect( (await convert(sharp(redPng), { format: "jpg", quality: 100 })).toBuffer(), ).resolves.toBeInstanceOf(Buffer); }); it("rejects quality below 1", async () => { await expect(convert(sharp(redPng), { format: "jpg", quality: 0 })).rejects.toThrow( "Quality must be between 1 and 100", ); }); it("rejects quality above 100", async () => { await expect(convert(sharp(redPng), { format: "jpg", quality: 101 })).rejects.toThrow( "Quality must be between 1 and 100", ); }); it("throws on an unsupported output format", async () => { await expect(convert(sharp(redPng), { format: "bmp" as unknown as "png" })).rejects.toThrow( "Unsupported output format: bmp", ); }); }); describe("colorBlindness simulation matrix", () => { it("applies achromatopsia (grayscale) so red drops and green/blue rise to equal luminance", async () => { const out = await (await colorBlindness(sharp(redPng), { type: "achromatopsia" })) .png() .toBuffer(); const [r, g, b] = await channelMeans(out); // Input is pure red (255, 0, 0). Luminance of red = 0.2126 * 255 ~= 54. expect(r).toBeLessThan(255); expect(g).toBeGreaterThan(0); expect(b).toBeGreaterThan(0); // All three channels collapse to the same luminance value. expect(r).toBe(g); expect(g).toBe(b); expect(r).toBeGreaterThanOrEqual(50); expect(r).toBeLessThanOrEqual(58); }); it("selects the matrix by type: protanopia differs from achromatopsia", async () => { const achroma = await channelMeans( await (await colorBlindness(sharp(redPng), { type: "achromatopsia" })).png().toBuffer(), ); const protan = await channelMeans( await (await colorBlindness(sharp(redPng), { type: "protanopia" })).png().toBuffer(), ); // Distinct matrices must yield distinct channel means for the same input. expect(protan).not.toEqual(achroma); // Protanopia on pure red keeps R > G > B (0.152/0.114/-0.003 * 255). expect(protan[0]).toBeGreaterThan(protan[1]); expect(protan[1]).toBeGreaterThanOrEqual(protan[2]); }); it("runs every color-blindness type without error", async () => { const types: ColorBlindnessType[] = [ "protanopia", "deuteranopia", "tritanopia", "protanomaly", "deuteranomaly", "tritanomaly", "achromatopsia", "blueConeMonochromacy", ]; for (const type of types) { const out = await (await colorBlindness(sharp(redPng), { type })).png().toBuffer(); expect(out).toBeInstanceOf(Buffer); expect(out.length).toBeGreaterThan(0); } }); }); describe("processImage pipeline dispatch", () => { it("throws with the operation name on an unknown operation type", async () => { await expect(processImage(redPng, [{ type: "nonexistent-op", options: {} }])).rejects.toThrow( "Unknown operation: nonexistent-op", ); }); it("passes the input format through when no operations and no outputFormat are given", async () => { const result = await processImage(redPng, []); expect(result.info.format).toBe("png"); }); it("converts to the requested outputFormat", async () => { const result = await processImage(redPng, [], "webp"); expect(result.info.format).toBe("webp"); }); it("maps the heif outputFormat alias through FORMAT_MAP to an avif encode", async () => { const result = await processImage(redPng, [], "heif"); // FORMAT_MAP.heif -> "avif"; Sharp reports avif data as "heif". expect(result.info.format).toBe("heif"); }); it("throws on an unsupported outputFormat", async () => { await expect(processImage(redPng, [], "notaformat" as unknown as "png")).rejects.toThrow( "Unsupported output format: notaformat", ); }); it("applies a registered operation in sequence", async () => { // grayscale collapses pure red to a single mid-gray value across channels. const result = await processImage(redPng, [{ type: "grayscale", options: {} }]); const [r, g, b] = await channelMeans(result.buffer); expect(r).toBe(g); expect(g).toBe(b); expect(r).toBeGreaterThan(0); expect(r).toBeLessThan(255); }); });