jest-webgl-canvas-mock
Mock canvas
and WebGL
when running unit test cases with jest.
Disclaimer
This project is a simple merge of jest-canvas-mock with webgl-mock so that both 2d and webgl contexts can be tested in jest. As such, the only tests provided are those from the original projects.
The current goal of this project is simply to make any tests using pixi.js
work in jest.
Please feel free to contribute and add any additional functionality required.
Install
This should only be installed as a development dependency (devDependencies
) as it is only designed for testing.
npm i --save-dev jest-webgl-canvas-mock
Setup
In your package.json
under the jest
, create a setupFiles
array and add jest-webgl-canvas-mock
to the array.
{
"jest": {
"setupFiles": ["jest-webgl-canvas-mock"]
}
}
If you already have a setupFiles
attribute you can also append jest-webgl-canvas-mock
to the array.
{
"jest": {
"setupFiles": ["./__setups__/other.js", "jest-webgl-canvas-mock"]
}
}
More about in configuration section.
Setup file
Alternatively you can create a new setup file which then requires this module or
add the require
statement to an existing setup file.
__setups__/canvas.js
import 'jest-webgl-canvas-mock';
require('jest-webgl-canvas-mock');
Add that file to your setupFiles
array:
"jest": {
"setupFiles": [
"./__setups__/canvas.js"
]
}
Mock Strategy
This mock strategy implements all the canvas functions and actually verifies the parameters. If a
known condition would cause the browser to throw a TypeError
or a DOMException
, it emulates the
error. For instance, the CanvasRenderingContext2D#arc
function will throw a TypeError
if the
radius is negative, or if it was not provided with enough parameters.
expect(() => ctx.arc(1, 2, 3, 4)).toThrow(TypeError);
expect(() => ctx.arc(0, 0, -10, 0, Math.PI * 2)).toThrow(DOMException);
The function will do Number
type coercion and verify the inputs exactly like the browser does. So
this is valid input.
expect(() => ctx.arc("10", "10", "20", "0", "6.14")).not.toThrow();
Another part of the strategy is to validate input types. When using the
CanvasRenderingContext2D#fill
function, if you pass it an invalid fillRule
it will throw a
TypeError
just like the browser does.
expect(() => ctx.fill("invalid!")).toThrow(TypeError);
expect(() => ctx.fill(new Path2D(), "invalid!")).toThrow(TypeError);
We try to follow the ECMAScript specification as closely as possible.
Snapshots
There are multiple ways to validate canvas state. There are currently three static
methods attached
to the CanvasRenderingContext2D
class. The first way to use this feature is by using the __getEvents
method.
const events = ctx.__getEvents();
expect(events).toMatchSnapshot();
The second way is to inspect the current path associated with the context.
ctx.beginPath();
ctx.arc(1, 2, 3, 4, 5);
ctx.moveTo(6, 7);
ctx.rect(6, 7, 8, 9);
ctx.closePath();
const path = ctx.__getPath();
expect(path).toMatchSnapshot();
The third way is to inspect all of the success draw calls submitted to the context.
ctx.drawImage(img, 0, 0);
const calls = ctx.__getDrawCalls();
expect(calls).toMatchSnapshot();
Override default mock return value
You can override the default mock return value in your test to suit your need. For example, to override return value of toDataURL
:
canvas.toDataURL.mockReturnValueOnce(
'data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=='
);
License
MIT