chai-image

Extends Chai with assertions about images

expect(bufImage).to.matchImage(bufExpectedImage);

Expected	Actual

Diff (LEFT_TOP Aligned)	Diff (CENTER Aligned)

In this case, matchImage assertion will fail.

Usage

Install chai-image to get up and running.

$ npm install chai-image --save-dev

Then:

import * as chai from "chai";
import { chaiImage } from "chai-image";

chai.use(chaiImage);

// Then either:
const expect = chai.expect;
// or:
const assert = chai.assert;
// or:
chai.should();
// according to your preference of assertion style

Assertions

matchImage(expected: Buffer, options?: MatchImageOptions)

NOTE: Currently it only supports PNG image format.

Example

// Simple Example
import * as fs from "fs";

const bufActual = fs.readFileSync("actual.png");
const bufExpected = fs.readFileSync("expected.png");

expect(bufActual).to.matchImage(bufExpected);

// Real-world Example
import * as sharp from "sharp";

class ImageService {
  public async transform(buf: Buffer): Promise<Buffer> {
    return await sharp(buf).resize().max(320, 320).png().toBuffer();
  }
}

const service = new ImageService();

describe("ImageService", () => {
  describe("#transform", () => {
    it("should transform image", async () => {
      const input = fs.readFileSync("fixtures/input.png");
      const output = fs.readFileSync("fixtures/output.png");
      
      expect(await service.transform(input)).to.matchImage(output);
    });
  });
});

Tests image matches to given image or not.

Image comparision is proceeded by pixelmatch library. If output config is provided, chai-image will create some files to show diff results.

enum Align {
  LEFT_TOP = "leftTop",
  CENTER = "center",
}

interface MatchImageOptions {
  // Custom diff config passed to pixelmatch
  diff?: DiffOptions;
  
  // Image aligning config for aligning different size image (default: Align.LEFT_TOP)
  align?: Align;
  
  // Output config
  // if specified, chai-image will create output files to visualize diff 
  output?: OutputOptions;
}

interface DiffOptions {
  threshold?: number;
  includeAA?: boolean;
  alpha?: number;
  aaColor?: [number, number, number];
  /* The color of differing pixels in the diff output. [255, 0, 0] by default. */
  diffColor?: [number, number, number];
}

interface OutputOptions {
  // Currently name is used to generate filename
  name: string;
  // Path of output directory (default: WORKDING_DIR/outputs)
  dir?: string;
  
  // Output creation conditions
  // Controls when to create output files (default: failure)
  on?: "failure" | "always";
  
  // Controls output file types (default: false)
  diffOnly?: boolean;
}

Changelog

See CHANGELOG.

Testing

$ npm run test

Build

$ npm run build

License

MIT

See full license on mooyoul.mit-license.org