Some of you are going to be new to all of the tools I’m describing here, and for you, I wanted to show how I think I’ve made authoring automated tests somewhat painless. For those of you who are already familiar with the whole React/Redux stack, feel free to make suggestions on making things better in the comments;)
As part of my big push to finally release Storyteller 3.0, I recently upgraded all of its JavaScript client dependencies (React.js/Babel/Webpack/etc. I might write a full on rant-y blog post about that later). As part of that effort, I’ve known for some time that I wanted to convert the client’s homegrown Flux-lite architecture based around Postal.js to Redux before I started to add any new features to it before making the final 3.0 release. After finishing that conversion to Redux, I can’t say that I’m really thrilled with how much work it took to make that transition, but I’m happy with the final results. In particular, I really like how easy the usage of react-redux has made the Karma specs for many of my React.js components.
Step 1 was to effectively shatter all of my existing karma specs. Step 2 was to figure out how to most easily connect my components under test to the new Redux architecture. I had an existing testing harness that had been somewhat helpful I used to first sketch out what a new Karma harness should do:
- For various reasons, I’m insisting on using a real browser when using Karma on my React.js components instead of something like jsdom, so I wanted the new harness to make it as quick as possible to render a React.js component in the browser
- I wanted the harness to take care of spinning up a new Redux store with the correct reducer function
- Despite my preference for “self-contained” tests and dislike of shared testing data sets, I opted to have the new harness start up with an existing JSON state of the client recorded from the server output to a JS file.
- Give me quick access to the mounted React.js component instance or the actual DOM element.
- I do still use Postal.js to broadcast requests from my React.js components to the rest of the application, so for the sake of testing I wanted some testing spy‘s to listen for messages to Postal.js to verify some of the event handlers of my components.
Those requirements led to a harness class I quite creatively called “ComponentHarness.” Looking at the interesting parts of the constructor function for ComponentHarness, you can see how I set up an isolated test state and element for a React.js component:
// Make sure you aren't failing because of faulty
// Postal listeners left behind by previous tests
Postal.reset();
// Sets up a new Redux store with the correct
// Reducer function.
this.store = createStore(Reducer);
// Establish an initial data set based on
// server side data from the .Net tests
this.store.dispatch(initialization);
// Create a brand new container div for the
// React.js component being tested and add that
// to the current document
this.div = document.createElement('div');
document.documentElement.appendChild(this.div);
// Sets up some test spy's for Postal.js channels
// that just listen for messages being received
// during a spec run
this.engineMessages = new Listener('engine-request');
this.editorMessages = new Listener('editor');
this.explorerMessages = new Listener('explorer');
Now, to put this into usage, I have a small React component called “QueueCount” that sits in the header bar of the Storyteller client and displays a Bootstrap “badge” element showing how many specifications are currently queued up for execution and links to another page showing the active queue. In the system’s initial state, there are no specifications queued and this badge element should be completely hidden.
At the top of my specification code for this component, I start up a new ComponentHarness and render the QueueCount component that I want to test against:
describe('QueueCount', function(){
var component, harness;
before(function(){
component = (<QueueCount />);
harness = new ComponentHarness();
harness.render(component);
});
Inside of ComponentHarness, the render(component) method renders the component you pass into it in the DOM, but nested within the <Provider /> component from react-redux that does the work of wiring the Redux state to a React.js component:
render(component){
ReactDOM.render(
(
// The Provider component here is from
// react-redux and acts to "wire up"
// the given redux store to all the elements
// nested inside of it
<Provider store={this.store}>
{component}
</Provider>
)
, this.div);
}
Since the ComponentHarness is starting the store at a known state with no specifications currently queued for execution, the QueueCount component should be rendered as an empty <span /> element, and the first specification states this:
it('is just a blank span with no specs queued', function(){
// element() gives me access to the root DOM element
// for the rendered React component
var element = harness.element();
expect(element.nodeName).to.equal('SPAN');
expect(element.innerText).to.equal('');
});
Next, I needed to specify that the QueueCount component would render the proper count when there are specifications queued for execution. When running the full application, this information flows in as JSON messages from the .Net server via web sockets — and can update so quickly that it’s very difficult to really verify visually or with automated tests against the whole stack. Fortunately, this “how many specs are queued up” state is very easily to set up in tests by just dispatching the JSON messages to the Redux store and verifying the expected state of the component afterward as shown in the following Karma spec:
it('displays the updated counts after some specs are queued', function(){
// Dispatch an 'action' to the underlying
// Redux store to mutate the state
harness.store.dispatch({
type: 'queue-state',
queued: ['embeds', 'sentence1', 'sentence3']
})
// Check out the DOM element again to see the
// actual state
var element = harness.element();
expect(element.nodeName).to.equal('BUTTON');
expect(element.firstChild.innerText).to.equal('3');
});
Digging into the DOM
Call me completely uncool, but I do still use jQuery, especially for reading and querying the DOM during these kinds of tests. For ComponentHarness, I added a couple helper methods to it that allow you to quickly query the DOM from the mounted React component with jQuery:
// jQuery expression within the mounted component
// DOM elements
$(match){
return $(match, this.div);
}
// Find either the root element of the
// mounted component or search via css
// selectors within the DOM
element(css){
if (!css){
return this.div.firstChild;
}
return $(css, this.div).get(0);
}
These have been nice just because you’re constantly adding components to new <div /> ‘s dynamically added to the running browser page. In usage, these methods are used like this (from a different Karma testing file):
it('does not render when there are no results', () => {
// this is just a convenience method to mount a particular
// React.js component that shows up in dozens of tests
harness.openEditor('embeds');
var isRendered = harness.$('#spec-result-header').length > 0;
expect(isRendered).to.be.false;
});
Postal Test Spy’s
Another usage for me has been to test event handlers to either prove that they’re successfully updating the state of the Redux store by dispatching actions (I hate the Redux/Flux parlance of ‘actions’ when they really mean messages, but when in Rome…) or to verify that an expected message has been sent to the server by listening in on what messages are broadcast via Postal. In the unit test below, I’m doing just this by looking to see that the “Cancel All Specifications” button in part of the client sends a message to the server to remove all the queued specifications and stop anything that might already be running:
it('can cancel all the specs', function(){
// click tries to find the matched element
// inside the rendered component and click it
harness.click('#cancel-all-specs');
var message = harness
.engineMessages
.findPublishedMessage('cancel-all-specs');
expect(message).to.not.be.null;
});
Summary
The ComponentHarness class has been a pretty big win in my opinion. For one thing, it’s made it relatively quick to mount React.js components connected to all the proper state in tests. Maybe more importantly, it’s made it pretty simple to get the system into the proper state to exercise React.js components by just dispatching little JSON actions into the mounted Redux store.
I’m not a fan of pre-canned test data sets, but in this particular case it’s been a huge time saver. The downsides are that many unit tests will likely break if I ever have to update that data set in the future, and sometimes it’s harder to understand a unit test without peering through the big JSON data of initial data.
In the longer term, as more of our clients at work are transitioned to React.js with Redux (that’s an ongoing process), I think I’m voting to move quite a bit of the testing we do today with Webdriver and fully integrated tests to using something like the Karma/Redux approach I’m using here. While there are some kinds of integration problems you’ll never be able to flush out with purely Karma tests and faked data being pushed into the Redux stores, at least we could probably make the Karma tests be much faster and far more reliable than the equivalent Webdriver tests are today. Food for thought, and we’ll see how that goes.
The Shade Tree Developer 