TL;DR: you can get the entire code at my repository.
I recently found a way to unit test d3 code, and it has transformed my approach to writing d3 applications.
I want to share this with the d3 community because they typically don’t emphasis unit testing.
Consider the following d3 code.
This code does the following:
- append a red circle to a canvas
- change the color of the circle to green when the user clicks on it.
Most of the time, we rely on our eyeballs to verify the correctness of d3 applications.
For example, this is what the canvas looks like when we D3 renders the canvas.
and D3 will render the following when the user clicks on the circle
In this case, we can manually verify that the code works.
Unfortunately, we can’t always rely on human eyeball testing.
However, with the jsdom module, we can programmatically verify whether the browser updated the DOM properly: we can (a) set expectations for our DOM, (b) write d3 code to fulfill our expectations, and (c) automatically run the tests with gulp.
First let’s setup our project.
Create a directory for our project, and initialize it as an npm package
Create a directory for our source code and our tests
Install the necessary npm modules
Create the d3 Application
Put the following code under src/Circle.js
The Circle module takes two arguments. The first argument is the dom element that we will append the svg canvas to. The second argument is the id we will give circle. We will need this id for testing.
Testing the d3 Application
Create the file test/Circle.spec.js with the following contents
So far we have not added any tests to the test suite. This is only boilerplate code that we will need to write our tests.
The function d3UnitTest encapsulates the jsdom environment for us. We will use this function in each test to alter the dom and test the dom afterwords.
Let’s create our first test.
Append the first test to our test suite.
In this test, we simply create check if the id “circleId” exists within the DOM. We assume that if it exists then the circle exists.
Notice the done parameter in our function. We do this to trigger an asynchronous test. jsdom will run asynchronously. We have to provide a callback to it; so, we manually have to call done() to inform jasmine when we are ready for it to test.
Append the second test to our test suite.
Append the third test to our test suite
This code simulates a click on the circle. You have to know a little bit about the internals of d3 to make it work. In this case, we have to pass the circle object itself, and the datum associated with the circle to the click function.
FYI, I couldn’t find a way to get jsdom to simulate user behavior; so, you have to understand the d3 internals if you want to test user behavior. If you know how to use jsdom to simulate user behavior then please let me know how you do it because this method is very error prone.
Run the Tests
When we run gulp from the command line we should see the following
I understand that I gave a pretty simple and contrived example. However, the principles that I demonstrated apply to more sophisticated situations. I can vouch for this because I have already written tests for very complicated behaviors.
There is a downside to this approach. You have to use node.js and write your d3 code as node modules. Some people might not like to have this dependency. Personally, I don’t find it very inconvenient. In fact, it has forced me to write very module d3 code.
It is also extremely easy to deploy my d3 code using browserify with this method.
Your milage may vary with this approach. I’m sure that there are ways you can achieve the same result with browser based tools. For example, I’m pretty sure that you could do something similar with protractor.