TyrealGray
Canvest
Writing a unit test for your HTML5 Canvas component without mocking any DOM element
Using browser to render and execute your component's unit test logic directly, outputting image snapshot to compare in pixel-level
Support TypeScript and zero config needed in most cases for JavaScript project, using API like it and describe with a few unique API for canvas snapshot
Install
Run npm cmd to install on your project
$ npm i @canvest/canvest-cli --save-devCreate a script in your package.json
"scripts": {
...
"test": "canvest",
...
},Usage example
If you just want to test a canvas, create helloworld.canvest.js under ./canvest folder
describe('Test my canvas', () => {
it('should render hello world text in canvas', async () => {
let canvas = document.createElement('canvas');
canvas.width = 800;
canvas.height = 600;
const a = await snapshot(canvas);
const context = canvas.getContext('2d');
context.fillStyle = '#ff0';
context.fillRect(0, 0, 800, 600);
const text = 'Hello, World!';
context.font = 'bold 70pt Menlo';
context.textAlign = 'center';
context.fillStyle = '#fff';
context.fillText(text, 200, 200);
const b = await snapshot(canvas);
a.notEqual(b);// this should pass
await autoShot('test', canvas); // this create a snapshot in local that will check canvas image to test if it is still the same
});
});Or test the class you create, for example for pixi.js
export class MyClass
{
...
updateRotation(rotation){
this._sprite.rotation = rotation;
}
...
}Create MyClass.canvest.js under ./canvest folder
import * as PIXI from 'pixi.js';
import { MyClass } from './MyClass';
describe('Test my class', () => {
it('should update rotation as expect', async () => {
const app = new PIXI.Application({
width: XXX, height: YYY,
preserveDrawingBuffer: true //<--- important for Canvest to take snapshot, false might lead to a blank image
});
const myClass = new MyClass();
app.stage.addChild(myClass._sprite);
myClass.updateRotation(1.5);
/**
* the second time this autoShot function run,
* it will check the current Canvas's image with the local cached 'rotation_that_expected.png' file,
* if this one is not the same with the cached image,
* the test will fail
**/
await autoShot('rotation_that_expected', app.view);
const rotation15Snapshot = await snapshot(app.view); // 1.5 rotation snapshot
myClass.updateRotation(1.6); // rotate sprite to 1.6 rotation
const rotation16Snapshot = await snapshot(app.view);
rotation16Snapshot.notEqual(rotation15Snapshot); // should pass
/**
* if the number of different pixels between rotation16Snapshot and rotation15Snapshot is below 20%,
* isMatch function will make the test as passed
**/
rotation16Snapshot.isMatch(rotation15Snapshot, 0.2);
});
});Then using npm cmd
$ npm testOnce you ran npm test, Canvest-cli will start running unit test that under canvest folder if files name is after *.canvest.(js|ts) pattern.
Canvest-cli will start two node servers, to config the port you could change npm script by
"scripts": {
...
"test": "canvest --cachePort XXX --pagePort XXX",
...
},cachePort: this is the port that canvest-cli using to start the node server to cache your snapshot, default is45670.pagePort: this is the port that canvest-cli using to start the web page to run your unit test withMocha, runningwebapck-dev-serverunder the hood.
Result
If some test case failed, you will see diff comparison under bottom showing in highlight red color.
One thing should notice is the diff for cached snapshot won't show up if cached snapshot has different size with current one.
API
Canvest framework is using Mocha with Chai under the hood, every API Mocha had in browser, Canvest should have as well by accessing mocha variable but this is not recommended.
You could create file canvest.init.js(or canvest.init.ts when using --ts) under ./canvest folder and doing all the setup in there.
autoShot(name, canvas): Promise<void>
take a snapshot of current canvas and cached in local, if local snapshot already exists, compare current snapshot with local one automatically
name: a unique name for snapshot to save under./canvest/autoShot/(the-name-you-given).pngcanvas: HTML5 canvas dom elementas long as your local snapshot doesn't get removed,
autoShotwill do the comparison instead of caching it and pass test
snapshot(canvas): Promise<snapshot Object>
take a snapshot of current canvas
canvas: HTML5 canvas dom elementsnapshot Object: return a Canvest snapshot that has 4 APIs in belowisEqual( otherSnapshot ): snapshot should completely equal tootherSnapshotnotEqual( otherSnapshot ): snapshot should not equal tootherSnapshotisMatch( otherSnapshot, tolerance ): snapshot could equal tootherSnapshotif test ignores number of tolerance percentage of pixelsnotMatch( otherSnapshot, tolerance ): snapshot could not equal tootherSnapshoteven after test ignores number of tolerance percentage of pixels
setThreshold(number): void
set global threshold for snapshot comparision, if you just want one snapshot comparision to be more tolerant, use isMatch or notMatch function with tolerance parameter
numberthreshold, a number that can be set to maximum1.0. Default is0.05, higher number will ignore more differences between snapshot comparision
Test Coverage
Canvest will create test coverage after all test is done, you could find the coverage.json and/or open index.html under ./coverage folder
TypeScript
To support TypeScript, you will need run npm i @canvest/canvest-ts --save-dev to install canvest-ts plugin
Then using canvest --ts ./path-to-your-tsconfig.json to start testing
Integrate with CI
If you want to run with headless browser in CI, you could use --ci option. This will make Canvest exit when all tests are done, and add a div inside web page <body> with className test_end or test_end_with_failed.
For example, canvest --ci ./canvest will create a canvest-test-result folder under ./canvest folder, any failed test will create a diff image in result folder.
If diff is a cached snapshot and it is not valid because new snapshot size is different, it will still create an empty file failed-Name.diff.failed.
Link
Canvest example for pixi.js with TypeScript https://github.com/TyrealGray/canvest-pixi.js-example
Canvest example for three.js https://github.com/TyrealGray/canvest-three.js-example
License
AFL-3.0