In this short article you will learn what you need to install in order to prepare a test environment for canvas operations with jest. After finishing the article, you will be ready for some canvas testing action!

In the past few months, my kid and I been building HTML5 games. I’d might actually get you permission to sign an NDA to see the outcome of these sessions. Until then, I can share some of my experience from meddling in the world of Context2D…

Since my son and I are both keen on testing, we struggled with testing canvas operations using Jest. Jest is using JSDom, which doesn’t implement EVERYTHING available in the browser. In addition, we had some issues using ES6 imports.

How did we solve all this? In one word. Google. In many words…

How to build a test environment for canvas with Jest

Building something with HTML5 canvas is fun. Testing with Jest is a pleasure. Let’s give it a try!

If you want to code along, feel free to fork/clone the repository and checkout the steps tags (step-1 to step-6).

Installing Jest

We will start with an HTML and JS file in our repository: https://github.com/YonatanKra/testing-canvas-with-jest/tree/step-1

Our next step would be to install the dependencies needed to start testing. Let’s install Jest:

1. Run npm init in order to generate a package.json file.
2. Now we can install jest: npm install jest -D

Our package.json should now look like this:

You can get to this stage by checking out the tag step-2 in the repository.

Now we should be able to start testing.

Writing our first test and code

What we’d like to do is create a function that draws a castle with windows and a gate on our canvas. It will look like this:

The html and js code will look like this:

Note the type=module on the script tag which allows us to use ES6 imports natively in the browser.

We will now create a test file and try to run jest. Here’s the file:

This file just tries to require our draw function and does nothing more. You can view this phase by checking out step-3 (or just look here).

Running jest (or npm run test) will result in the following error: Jest encountered an unexpected token. It will then show us that the export in our code is unexpected (line 4 in our .js file).

{
  "env": {
    "test": {
      "plugins": ["@babel/plugin-transform-modules-commonjs"]
    }
  }
}

Now when we run the tests (npm run test or just jest) the test will succeed in importing but we will get a different error: ReferenceError: Path2D is not defined

How to solve ReferenceError: Path2D is not defined

This error happens because Jest runs on JSDom and not in a real browser. Luckily, some good people thought about us and wrote two useful libraries: canvas and jest-canvas-mock. In order to solve this last issue, do the following:

1. npm i -D canvas jest-canvas-mock
2. Add a setup file to jest config (in my case it will be in package.json but you can add it to an external config file if you have one):

"jest": {

    "setupFiles": ["jest-canvas-mock"]
}

and… HOORAY!

You can view these changes by checking out step-4 or view it on github.

How to test canvas operations with Jest?

Let’s write simple tests for our code:

The code above verifies two things:

1. That draw returns a Path2D
2. That draw ran certain commands on our 2DContext.

The ctx.__getEvents method used in the code above is given to us via jest-canvas-mock. It spies on the context’s methods calls and logs them for us. We then create a snapshot of it and make sure that as long as we follow the same API call, we still have the same canvas procedure.

Jest has a built-in snapshot feature. It generates stringified snapshots and saves them into a file. These snapshots are hashed according to the tests’ describe and it descriptions. It’s kind of like Visual Regression, only for JavaScript data Objects (JSON, Arrays or strings).

Here’s the snapshot taken:

We can, of course, do more complex verifications. For instance, we can parse the __getEvents output to verify certain things (which will be more TDD-like).

You can find the working code by checking out step-5 or view it on github.

How to test DOMMatrix operations with Jest

Now that our function is working, we’d like to add some parameters like sizing. We resize Path2D paths using a DOMMatrix which helps us translate and scale our paths.

Let’s add the code that does that and try to run our test:

Note the creation of DOMMatrix in line 6, the translation and scale setup in line 7 and the usage in lines 19 when setting the transform to the drawn shape.

Now running jest or npm run test will result in an error: TypeError: MATRIX.translate is not a function

Note that if we did not use jest-canvas-mock our error would have been: ReferenceError: DOMMatrix is not defined. For the same reason Path2D was undefined.

Solving TypeError: MATRIX.translate is not a function

This can be easily solved by mocking the DOMMatrix class. DOMMatrix is, unfortunately, not implemented by JSDom (and probably not going to be). It is implemented by jest-canvas-mock, but it is missing the translate and scale methods and from this PR it also supports the translate method.

All the tests are now passing. We can now also write tests for our new API and close this section:

    it(`should draw a house on the canvas using the default scaleX and scaleY`, function() {
        const path = draw(ctx);
        const events = ctx.__getEvents();

        expect(events).toMatchSnapshot();
    });

    it(`should draw a house with given position, scaleX and scaleY`, function() {
        const path = draw(ctx, { position: { x: 10, y: 10 }, scaleX: .5, scaleY: 0 });
        const events = ctx.__getEvents();

        expect(events).toMatchSnapshot();
    });

These tests also pass.

You can view the full code in step-6 or view it on github

Summary

Wow! What a ride! Now I hope we know better how to test canvas using Jest.

Testing canvas with Jest might seem ominous at first. With some trial, error and google, everything is solvable.

From solving a simple import problem through mocking the 2d context and Path2D to extending the DOMMatrix mock itself – you are now ready to lunch your next canvas based app with the security of testing with Jest.

In our example, you can test your new canvas testing skills to add more API’s and test them. One example could be adding color and stroke to the configuration…

If you are looking for serverside mocking techniques, I’ve just read a really cool tip on how to mock a database. I hope you will enjoy it like I did.

Since this is my first actual research of testing Canvas operations, I’d love to read your feedback and experience in the field. Feel free to use the comments below to share your opinion or just holler me over FB/Twitter/Linkedin.

Thanks a lot for Shai Reznik from hirez.io and Miki Ezra Stanger for a very kind and helpful review!