validates_presence_of :purpose : Tag jspec, everything about jspec

Writing a testsuite for the CouchDB API

Wed, 28 Apr 2010 12:07:00 +0000

CouchDB is a database that I quite like. In fact, I haven’t done much else this winter, as the programming part of my thesis involved diving into many of CouchDB’s features. I had just finished my little program and was desperately looking for an excuse not to start writing the thesis. Mercifully Jan from Couchio came along and asked if I wouldn’t like to write a testsuite for CouchDB’s Javascript HTTP API, and the documentation with it. I wanted!

What is this HTTP API?

If you have worked with CouchDB from a Javascript program before (eg Sammy.js is a good companion for a simple web application), you have probably used the methods a file named couch.js provides. With this interface you can easily access the most common CouchDB functionality without having to handle the XMLHttpRequest yourself. It allows you to create a “database object” and then perform things on this object, for example save or delete documents:

var db = new CouchDB("test_db");
db.createDb();

var doc = {"_id" : "Starbuck", "name" : "Kara Thrace"};
var saved_doc = db.save(doc);

// do something
db.deleteDoc({_id : "123", _rev : saved_doc.rev});

If you’re using JQuery, you can use the JQuery interface in jquery.couch.js. It covers basically the same things as couch.js, but it uses, you guessed it, JQuery. That means you can send your requests asynchronously and handle the response in the callback. Same example:

var db = $.couch.db('spec_db');
db.create();

var doc = {"_id" : "Starbuck", "name" : "Kara Thrace"};
db.saveDoc(doc, {
  success: function(response){
    // do something
    db.removeDoc({_id : "123", _rev : response.rev});
  }
});

The code looks a bit more complicated, but with this API you have the full power of asynchronicity in your head, where spelling the word asynchronicity is the worst part.

Writing the testsuite

I was free to choose which testing framework I wanted to use. The tests in CouchDB use a kind of home grown testing framework, which does its job, but is not really the state of the art of Unit Testing. The API tests aren’t supposed to run within the normal CouchDB testsuite anyway. That is the one you always run in Futon when you installed CouchDB. So it was possible to use something different … like JSpec. (I have also blogged and talked about it in the past.)

How to run JSpec tests? If you are familiar with JSpec tests, you know you define your tests in Javascript files, reference those from a HTML file and open that in a browser. When you want your tests to perform calls to the database, this won’t work - you get the error message “Access to restricted URI denied”. Shortly this is because AJAX only allows connections to the same resource it is called from. Therefore you have to run the tests from within the database. CouchDB has a folder share/www, which gets linked to the “/_utils/” path of your local installation. In this folder you find Futon. That’s where you have to put your tests and all the helper scripts. Then you can run the tests directly from the couch by browsing to /_utils/spec/run.html.

Writing the testsuite was pretty straightforward. Along the way I found some bugs in the code (no surprise as it was written untested). One of the problems I had to solve I’ve explained in another blogpost: How to overwrite the authentication_db so the tests don’t interfere with the CouchDB setup.

There’s one thing I’m not completely happy with: The tests do really need kind of long to run, up to 3 minutes, depends a lot on the browser and CPU load. The other CouchDB Javascript tests are a lot faster. I think the new ones are a bit more comprehensive. And I preferred a very clean setup to how it’s done in the old tests: I have a database created before every single assertion and have it dropped afterwards. So you know exactly in which state your database is during the test. I guess that’s worth the longer runtime.

So. If you want to see a lot of JSpec code in action, and want to learn more about CouchDB, have a look at the code. At the moment it’s in my fork only, the community (someone - you?) has yet to integrate it into Futon. For all the details, read my rundown and left TODOs.

Documentation

I also wrote API Docs for all the methods. It can be found here. Later you will find it nicely formatted in the CouchDB Wiki and on the Couchio website.

If you find anything is missing or you don’t understand it, feel free to drop me a line. I’m happy to clarify it as long as it’s all freshly in my brain.

PS - I consider example data in tests important, so I took all the data from the SciFi series Battlestar Galactica, currently on my playlist and I luv it. And it gave me an excuse to read in the Battlestar Wiki every now and then when I was looking for correct spelling :)

JSpec: Slides of my talk at Berlin JS Usergroup

Mon, 22 Mar 2010 12:52:00 +0000

Last thursday I gave a talk at the monthly meeting of the Berlin JS Usergroup. I was talking about JSpec, a Javascript Unit Testing framework. Thanks to all who were there to listen and ask questions!

Here are the slides. When you have a look at them, make sure to also read the notes (next to the comments), so the slides make sense to you.

To find more information about JSpec, check out the README on github, or read the blog post I wrote about it recently.

Thanks also to @gisikw and @tjholowaychuk for this talk from which I borrowed a few grammar examples :)

JSpec - JavaScript Unit testing how it should be

Mon, 04 Jan 2010 12:07:00 +0000

Selecting a unit test framework for a JavaScript-only application - not a task with an obvious answer! Coming from the Rails world, where most people work with either TestUnit or RSpec, I was a bit lost when I started researching. This table on wikipedia was quite helpful for a first overview. But: JsUnit, JSTest, jsUnitTest, jsUnity - these are actually different frameworks, and there’s even many more …

I narrowed the selection down to those being currently developed, or are in use in “big” projects. JsUnit seems to be one of the major players, but I found almost no documentation, and the code base hasn’t changed a lot in the last years. That’s not a negative thing in itself, but having an active community around is a good thing. QUnit is used for testing JQuery, it looked like you could work with it as well, but its syntax and setup didn’t make me go “wow” exactly. Same goes for JQUnit, about which I had read good stuff in several blog posts. It’s also what Sammy.js is tested with.

I like RSpec, so when I had my first look at ScrewUnit, I was delighted to find there’s BDD syntax for JavaScript too. ScrewUnit is also a part of Blue Ridge, which is sadly still only available as a Rails plugin. So, ScrewUnit looked nice.

And THEN … I found JSpec. I was thrilled! It’s a JavaScript framework, but it doesn’t look like JavaScript at all: no curly brackets, no semicolons, just plain domain language. It just looks like RSpec. Here is a random snippet from my test suite, just have a look:

describe 'NoteCollection'
  before_each
    note3 = new Note({id: "8c8", text: 'three'});
    note1 = new Note({id: "ae9", text: 'one', next_id: "107"});
    note2 = new Note({id: "107", text: 'two', next_id: "8c8"});
      
    notes = new NoteCollection([note3, note1, note2]);
  end
  
  describe 'firstNote'
    it 'should return a note'
      notes.firstNote().should.be_an_instance_of Note
    end
    
    it 'should return the first note'
      notes.firstNote().id.should.eql note1.id
    end

    it 'should throw an error if there is more than one note that could be the first note'
      note4 = new Note({id: "fff", rev: "2-420"});
      notes.notes.push(note4);
      -{notes.firstNote()}.should.throw_error 'More than one first note found'
    end  
  end
end

And that are just 3 out of over 45 core matchers. There are also matchers for JQuery, see the next example, where I put the DOM I wanted to test in a fixture called outline.html. In Rails I don’t use fixtures, but if you want to test an application where all the markup is generated out of many different sources, it makes sense to test little pieces of the DOM in isolation. In ScrewUnit you have only one file for your all your mocked DOM.

describe 'NoteElement'
  before_each
    outline = elements(fixture('outline'))
    notes = outline.find('li')
  
    parent_note = new NoteElement($(notes.get(0)))
    child_note = new NoteElement($(notes.get(1)))
  end
  
  describe 'focusNextTextarea'
    it 'should focus the first child note if there is one'
      parent_note.focusNextTextarea();
      parent_note.noteLi().should.not.have_attr("data-focus")
      child_note.noteLi().attr("data-focus").should.eql 'true'
    end
  end

  describe 'insertUpdateNotePointers'    
    it 'should call setNextPointerToNewlyInsertedNote'
      inserted_note = {id:'4', text: 'inserted!'};
      parent_note.should.receive('setNextPointerToNewlyInsertedNote').with_args(inserted_note)
      parent_note.insertUpdateNotePointers(inserted_note);
    end
  end
end

Note, if you don’t like the RSpec-like Syntax, you can also skip the JSpec DSL and just use plain Javascript syntax.

More JSpec goodness: You can either run the tests in the browser, or in the terminal, so you can include it in your CI. In the terminal you can specify the browsers it should be tested with: The browsers will be opened in the background, but you won’t see your stuff being run like in Selenium. You can mock timers to test asynchronous calls. You can stub methods, mock AJAX requests, specify shared behaviours, hook into JSpec to specify your own matchers or do whatever else, and … just see for yourself.

Installation is easy too: just add JSpec.js and JSpec.css to your application. If you need them, add the files for jquery, timers or xhr support too. In spec/index.html you include your application files and specify which tests you want to run. Then open it in the browser, wait a few milliseconds, and see the result. If you want to run JSpec tests in the terminal, just install the JSpec Ruby gem. For this you also have to install Rhino (a Java-based JavaScript interpreter) - when you are on OS X, this should get you started.

What I don’t like about JSpec … the BlueRidge browser output is much more clear and pretty. I thought really hard about more things but that’s it.

Make sure to read the documentation on the JSpec website as well as the github Readme. Both ressources look similar, but at the time of writing there were different things on the two pages.