Automated Test Suite

[clarkf]

Hey All,

I'm opening this PR as the foundation for a test suite. I've added mocha as the test runner, and chai for assertions.

To run the test suite

1. At the root directory, run jekyll serve --watch (you're probably already doing this)
2. Navigate to http://localhost:4000/test/

You'll notice that weird stuff happens now (Squirt starts reading the output of the test runner, or, sometimes, just gives up). This is because Squirt doesn't reveal its API, so it's pretty difficult to unit test anything, or event prevent Squirt from running upon being loaded.

We need to add some sort of point-of-entry to Squirt -- perhaps we can make a subset of the API 'public' (i.e. accessible from outside of the main closure), and change the bookmarklet to invoke the 'start' method? In pseudocode:

bookmarklet.js:

document.body.appendChild(/* <script> tag */);
window.squirt.run(document.body);

squirt.js:

(function (root) {
    var Squirt = root.squirt = {};
    Squirt.version = '0.0.1a';
    Squirt.run = function (element) { /* ... */};
    Squirt.findContentNodes = function (parentElement) { /* ... */ };
    Squirt.tokenize = function (nodes) { /* ... */ };
    // etc
})(window);

I don't think this would impose any major security concerns, and it undesirably creates a global variable (window.Squirt), but it'd make testing these pieces of functionality substantially easier:

var Squirt = window.squirt;
describe('Squirt', function () {
    describe('#tokenize', function () {
        it('should handle hyphens', function () {
            var result = Squirt.tokenize(someNodeSet);
            // assertSomething
        });
    });
});

@cameron, what do you think? Is there some way we can test the units without rewriting the entire script?

[j6k4m8]

:thumbsup: to opening the API up, since it'll allow page authors to add their own custom hooks (and make testing / development a bajillion times easier).

[cameron]

:-1: to opening up the API, for now.

Until the code stops moving so fast[1], I want integration tests instead of unit tests. CasperJS is probably more appropriate than mocha/chai. Thoughts?

[1] I realize it hasn't been moving fast the past few days—apologies, I'm trying to figure out what's appropriate w/r/t a license, etc.

[clarkf]

I'm going to have to heartily disagree -- it is going to make the tests run in real time. Sure you can crank it up to 950 WPM, but for reading any substantial amount of text, it'll take some time. Also, having some element 'watching' the DOM for updates and comparing that against 'expected values' seems super brittle.

The whole cross-browser compatibility thing also rears its head: Casper runs headless Webkit under the hood, which is similar (but not equal) to current Chrome/Safari. Wouldn't there be benefit to testing in different browsers/versions?

Perhaps using Casper (or Phantom for that matter) as a test-runner would be great, but having the test suite exist in that weird niche is pretty undesirable.

Also it makes the barrier of contribution much higher, which is absolutely something that's up to you, but do we really want to discourage frontend devs who don't love the command line from contributing? :wink:

[cameron]

Oops! In separating the squirt.io source from the bookmarklet source, I deleted the gh-pages branch, which seems to have killed your PR. Feel free to resubmit your PR against master, or I may do some git foo to fix things up this weekend.

Back to the topic at hand, I appreciate your perspective on testing, and look forward to circling back on it this weekend!

Thanks, Cameron