validates_presence_of :purpose

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 :)