validates_presence_of :purpose :

Ta-da! Here is my thesis.

Wed, 27 Oct 2010 14:02:00 +0000

I’m happy to announce the immediate availability of my thesis! It was handed in in July 2010 as my diplom thesis in the academic program of Media Informatics at Beuth Hochschule für Technik Berlin (University of Applied Sciences). A German Diplom is comparable to a combined bachelor’s and master’s degree. Originally it has been written in German, so I’m very happy it’s also available for English speaking readers now: thanks a lot to the awesome Sander Van de Moortel for translating it into English, and to CouchOne for sponsoring the translation. Read also my thank you notes for more gratefulness.

I hope the thesis is an interesting read and useful for your research or development!

The title is “Implementation of a distributed application using the document-oriented database CouchDB — An outliner as a replicable distributed system” (originally “Umsetzung einer verteilten Anwendung mit der dokumentenorientierten Datenbank — CouchDB Ein Gliederungseditor als replizierbares Verteiltes System”).

What is it about? I wrote a couple of words about that for the Upstream blog. Here is also the abstract — all the contents in ten sentences:

Modern web browsers and mobile devices are capable of running complex applications that allow collaboration and data exchange between their users. Laptops and mobile phones, however, cannot be expected to keep their internet connections alive at all times. This problem can be sidestepped using data replication, which means that data are regularly synchronised and kept consistent. This thesis describes the drafting and prototypical development of a JavaScript application that uses the document-oriented database CouchDB to form distributed outliner software. Outliners can be used to record thoughts or concepts in a hierarchically structured manner. Apart from categorising the system to be developed and analysing possible approaches, the thesis will also examine the technologies used. Special focus lies on CouchDB with its built-in master-master replication and its ability to implement complex applications without the use of middleware. The final application runs locally in the browser and is therefore also usable when off-line. Conflicts are resolved when the system is synchronised, sometimes steered by user input. The thesis also evaluates the applicability of CouchDB in distributed applications with particular regard to the use case at hand.

Download

Read the English version and the German version online,
check out the English LaTeX sources or the German LaTeX sources on github, or
download the pdf in English or in German.

BibTeX

In case you want to quote me in your paper/thesis/homework, here’s the BibTeX entry:

@mastersthesis{herrmann:couchdb,
  author = {Lena Herrmann},
  title = {Realisation of a Distributed Application Using the Document-Oriented Database CouchDB - An Outliner as a Replicable Distributed System},
  school = {University of Applied Sciences Berlin},
  year = {2010},
  month = {July}
}

@mastersthesis{herrmann:couchdb,
  author = {Lena Herrmann},
  title = {Umsetzung einer verteilten Anwendung mit der dokumentenorientierten Datenbank CouchDB - Ein Gliederungseditor als replizierbares Verteiltes System},
  school = {Beuth Hochschule für Technik Berlin},
  year = {2010},
  month = {Juli}
}

The Application

The hands-on part is an outliner that allows people to collaborate on documents even when they don’t have continuous internet access. If you want to read/clone/try out/improve/take apart/whatever the source code, it’s here on github. The github README contains installation and usage instructions, for more details read chapter 9, “Application”, in the thesis.

You can also try out the outliner online. Though, in order to enjoy the replication and conflict resolution features, you have to (also) install it locally. But it’s a couchapp - when you have CouchDB running you’re almost there already.

I hope you all like it!

Pretty URLs for you couchapp, the howto

Mon, 11 Oct 2010 15:34:00 +0000

If you have a couchapp and want to have nice URLS, go read this blogpost. If you still don’t get it, here is how to do it. It doesn’t work with my outliner app, because it is so entangled with old couchapp and jquery.couch.js versions and I’m not up to upgrade hell right now. But I’ll write it down for my next project and for you, yay.

Let’s say you have an app running at http://account.couchone.com/mydb/_design/doingnotes/index.html and want to add the additional URL http://account.couchone.com/index.html. First you have to set up a virtual host. (Want to know why? Go back read the blogpost). If you are using a hosted CouchDB instance and don’t have access to the local.ini file, you can also do this remotely:

curl -X PUT http://username:password@account.couchone.com/_config/vhosts/account.couchone.com -d '"/mydb/_design/doingnotes/_rewrite"'

Check at the bottom of http://account.couchone.com/_utils/config.html if there is a key value pair “account.couchone.com” => “/mydb/_design/doingnotes/_rewrite”.

Now it won’t work yet, because you still have to add the rewrite(s) to your design document. Do this by adding a file “rewrites.json” in your project folder. I has to contain an array of json objects with a “from” and a “to” attribute each. They work down in the path starting with the design document (the “doingnotes” in the URL). You can use wildcards. “from” specifies where it should map from, “to” which file it should map to. This is how rewrites.json looks for my application:

[{
  "from": "",
  "to": "index.html"
},
{
  "from": "vendor/*",
  "to": "vendor/*"
},
{
  "from": "app/*",
  "to": "app/*"
},
{
  "from": "config/*",
  "to": "config/*"
},
{
  "from": "_view/*",
  "to": "_view/*"
}]

If you just put the first from/to pair in, you can already call the application, but it won’t work because the code in the design document needs access to all the folders that are stored in the application’s root level (that is not in the “_attachments” folder). The wildcards map everything down from that path. If you have code in other locations as well, you have to add rewrites for those folders too. That’s it.

Thesis is done - thanks for your support!

Thu, 05 Aug 2010 10:41:00 +0000

I’m done!! Three weeks ago I handed in my diplom thesis. The practical part was the design and implementation of a distributed, replicatable outliner with the NoSQL database CouchDB. As theoretical work I evaluated Distributed Systems, CouchDB, various web technologies and programming strategies. I still have to pass the oral exam, but my degree is finally very close - soon I can call myself a graduated computer scientist. Yay!

As soon as academic procedures allow it, I’ll publish the text and the source code of the thesis here. Until then I’d like to say thank you to a few people. As the foreword of thesis won’t get as much attention as this blog, I’ll do it here.

First first first of all, my appreciation goes to my boys at home and my parents for backing me up by spending loads of time with my child. Not only my professional life is based upon their support. THANKS.

Further thanks go to:

Upstream for generously sponsoring a part of the time I spent researching - especially Alex Lang for his support and coming up with the initial idea. Without them I probably would have done some usability study for the drawer, or I would have had lots of fun in some enterprisey Java company. Also I felt I wanted to strive hard to write good code in my thesis to match Upstream’s high standards for code quality and test coverage - not a bad thing.

Allround guru Jan Lehnardt - he not only knew and happily provided the answers to all questions I had about CouchDB, databases in general, JavaScript, LaTeX, typography and virtually everything else; he was also constantly encouraging and guiding me to contribute to open source projects, trusting in my skills and doing awesome things. One day I’ll also submit a talk to one of your conferences, word :-)

Jan Lehnardt, myself and Alex Lang on the couch with thesis.

My professor Stefan Edlich for doing a great job in mentoring me. He is also the university professor with the most phenomenal email response times I have ever heard of.

Urs, Andy and Ischa advised me on the structuring and helped to make the result look quite scientific. They patiently explained to me how to go about writing such a long academic text. Ischa also is one of the very few people who actually read the whole thing in one piece.

Several lovely people who helped at certain points during the research or the programming, listened with interest and/or assisted figuring out specific problems: Pat Allan (getting started was the hardest part); Urs again (many small and big issues all along the way); Frank Prößdorf and Lukas Rieder (figuring out with me what a Couchapp actually is); Till Klampäckel (skilled advice about Lounge and EC2); Kristina Schneider (tricky CSS shit); Thilo Utke and Sven Fuchs (die HTMLUnit bug, die); Ian White (this one bug in the code you had no idea what it was for but figured it out anyway); and various people from the Ruby and Javascript communities who helped me to shape my ideas by asking basic or challenging questions.

Some more people who wrote great open source programs, did great support and were always open to ideas: my thanks go to a good part of the CouchDB community here, and also to Aaron Quint and TJ Holowaychuk.

Finally my army of proofreaders! I split the text up in very small parts so that also people with a limited time budget had no excuse - I can really recommend this approach ;-). The list includes almost everyone mentioned above, and also: Adrian, Anne, Birgit, Bumi, Diana, Eike, Flo, Grushi, Helge, Jan S., Micha, Neels, Ole and Patrick.

The very last one goes to my sweetheart for brightening my life in those last stressful months.

Thank you everyone! I’m glad to know you all!!

JavaScript syntax highlighting in the LaTeX listings package

Thu, 20 May 2010 11:20:00 +0000

I’m currently writing my thesis, using LaTeX. As the programming part of my thesis was mostly done in Javascript, I have to include some bits of Javascript source code in the LaTeX document. For this I’m using the listings package. With this package you can “include the source code of any programming language within your document”. Unfortunately Javascript is not in the list of supported programming languages. (In return, the list contains languages like Oberon-2, Promela or RSL, which are probably being used way more often than Javascript … er.)

Luckily @awendt pointed me to these links: Javascript Quelltexte in LaTeX and a thread on a mailinglist. I changed those examples only a bit, I’m posting my result here mainly in the hope it will produce a Google hit for “javascript latex source code” :-)

Put this at the beginning of your document. It will define support for the Javascript language. I included the keywords that show up in my code most frequently.

\usepackage{listings}
\usepackage{color}
\definecolor{lightgray}{rgb}{.9,.9,.9}
\definecolor{darkgray}{rgb}{.4,.4,.4}
\definecolor{purple}{rgb}{0.65, 0.12, 0.82}

\lstdefinelanguage{JavaScript}{
  keywords={typeof, new, true, false, catch, function, return, null, catch, switch, var, if, in, while, do, else, case, break},
  keywordstyle=\color{blue}\bfseries,
  ndkeywords={class, export, boolean, throw, implements, import, this},
  ndkeywordstyle=\color{darkgray}\bfseries,
  identifierstyle=\color{black},
  sensitive=false,
  comment=[l]{//},
  morecomment=[s]{/*}{*/},
  commentstyle=\color{purple}\ttfamily,
  stringstyle=\color{red}\ttfamily,
  morestring=[b]',
  morestring=[b]"
}

Here you define the style for the newly defined language. This also belongs in the preamble of your LaTeX file.

\lstset{
   language=JavaScript,
   backgroundcolor=\color{lightgray},
   extendedchars=true,
   basicstyle=\footnotesize\ttfamily,
   showstringspaces=false,
   showspaces=false,
   numbers=left,
   numberstyle=\footnotesize,
   numbersep=9pt,
   tabsize=2,
   breaklines=true,
   showtabs=false,
   captionpos=b
}

The colours are just an example, read how to define more colours in the wikibook.

Now you can insert code like this. The example is nonsense, I tried to include as many keywords as possible. The medskip command before the listing inserts a linebreak, a not very nice way to have some distance between the text and the listing.

\medskip
\begin{lstlisting}[caption=My Javascript Example]
Name.prototype = {
  methodName: function(params){
    var doubleQuoteString = "some text";
    var singleQuoteString = 'some more text';
    // this is a comment
    if(this.confirmed != null && typeof(this.confirmed) == Boolean && this.confirmed == true){
      document.createElement('h3');
      $('#system').append("This looks great");
      return false;
    } else {
      throw new Error;
    }
  }
}
\end{lstlisting}

The result looks like this:

Update: @perkee pointed out you can also use the minted package for syntax highlighting.

Security in CouchDB: changing the authentication db

Thu, 29 Apr 2010 10:40:00 +0000

I recently wrote a testsuite for CouchDB’s Javascript HTTP API. Among the things I tested were the security methods. That’s those that deal with authentication - like signup, login, logout and so on. The challenge was to make sure my tests wouldn’t interfere with the CouchDB setup of the person running the tests.

Background

CouchDB stores the information about the database users in a special database, the authentication_db. The default authentication_db is called “_users”. So this is where your user data is saved when you sign up without taking care about the details, e.g. when you use the signup method provided by the JQuery HTTP API. Read more about the ways to interact with the authentication_db in the HTTP API documentation (JQuery methods), and read more about general CouchDB security in the CouchDB Wiki or in The Definitive Guide.

How to set the authentication_db

When you e.g. create database users from within your tests, how can you make sure they don’t mess up the actual authentication_db, the one the unsuspecting user might use in production? Of course you have to create a custom authentication_db for storing the user information, and make CouchDB use that one. And after your tests are finished, you want CouchDB to use the original authentication_db again, so that only your testsuite uses the custom users database.

So there is one function you call right at the beginning of the part of the testsuite that’s concerned with security features:

function useTestUserDb(){
  test_users_db = new CouchDB("test_users_db");
  var xhr = CouchDB.request("PUT", "/_config/couch_httpd_auth/authentication_db", {
    body: JSON.stringify("test_users_db")
  });
  if(typeof(old_auth_db) == 'undefined'){
    old_auth_db = xhr.responseText.replace(/\n/,'').replace(/"/g,'');
  }
}

We create a custom authentication_db (“test_users_db”) and write its name into the CouchDB configuration. If we don’t have the name of the old authentication_db stored yet (the one that’s called “_users” per default, but might be called differently), we strip this name from special characters and store it in a variable, so we can restore it later. This is the function we call at the very end of the testsuite:

function useOldUserDb(){
  CouchDB.request("PUT", "/_config/couch_httpd_auth/authentication_db", {
    body: JSON.stringify(old_auth_db)
  });
  test_users_db.deleteDb();
}

In the last line, we delete our custom authentication_db. Everything is back to normal, there is no trace of our tests left. You can have a look at how it looks like in production.

How to work with the authentication_db

You can create a new user like this:

var userDoc = CouchDB.prepareUserDoc({name: "Gaius Baltar", roles: ["president"]}, "secretpassword");
test_users_db.save(userDoc);

Then you are logged in and can do whatever you want. About working with users and roles, read the chapter in The Definitive Guide. When you’re done, delete the userDoc from the authentication_db, as the authentication_db has to be empty before it can be deleted:

test_users_db.deleteDoc({_id : userDoc.id, _rev : userDoc.rev})

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

Refactoring asynchronous code

Mon, 15 Feb 2010 16:17:00 +0000

How to refactor a long chunk of asynchronous code is one thing I learned during my Javascript & CouchDB project. It’s not a difficult thing, but I thought it was before I figured out how to do it, so I guess it might be interesting for Javascript newbies.

Asynchronous code

In the first couple of weeks I struggled with this new style of coding before I got the hang of it. If you’re fairly new to Javascript, you’re probably used to just assign a variable in one line and use it in the next line. In the asynchronous world you query for a value and do stuff with it in the callback function of the query.

To illustrate - “normal” code looks like this:

var result = db.query("select * from T");
// use result

Although writing web applications just screams for doing it like this instead:


db.query("select..", function (result) {
// use result
});

(Examples stolen from Ryan Dahl’s Presentation about Node.js.)

The Problem

I have a method that checks if I have to display a notification message. For this it makes a lot of requests to the database, the received data has to be compared with other data, there’s lots of if/else clauses to consider all kinds of conditions and edge cases. It started simple, but then more and more conditions came in, unless I had the much feared diagonal closing bracket line on my screen.

You don’t need to know the details, just look at the picture and you’ll get the impression.

Refactoring

By way of illustration I made up a much shorter example:


checkForConflicts: function(){
  //set arguments
  openDoc(id, function(result){
    // do stuff with arguments
    if(result.bar == whatever){
      // do more stuff with result
      openAnotherDoc(id2, function(result2){
        if(result2.baz == true){
          // show notification message with result2
        }
      });
    }
  });
}

It is time to refactor after you are sure this actually is the way to go and the code basically works (“make it work, then make it pretty”). First you group the code into methods: You split the lines by what they do, and then you name each section. I think around 8 LOC is a good length for a method.

If this was synchronous code, you could just call these methods after each other. But this doesn’t work here, because result and result2 are not available outside the function that retrieves them.

My first approach was to call the functions from within each other. This works - but to see what checkForConflicts does at its very heart, you have to scroll down through all the methods - not much gained:

checkForConflicts: function(){
  //set arguments
  doSomething(arguments);
}

doSomething(arguments){
  openDoc(id, function(result){
    // do stuff with arguments
    if(result.bar = whatever){
      doSomethingElse(result);
    }
  });
}

doSomethingElse(result){
  // do more stuff with result
  openAnotherDoc(id2, function(result2){
    if(result2.baz == true){
      showMessage(result2);
    }
  });
}

showMessage = function(result2){
  // show notification message with result2
}

The way to do it is to use callbacks. Each method gets an anonymous function as (additional) argument: in the method declaration this function has the name callback. This callback is called if all the conditions within the method are met. The callback gets its arguments from within the method that calls it. You have to specify these arguments again in checkForConflicts to have a valid function definition.

checkForConflicts: function(){
  //set arguments
  doSomething(arguments, function(result){
    doSomethingElse(result, function(result2){
      showMessage(result2); 
    });
  });
}

doSomething(arguments, callback){
  openDoc(id, function(result){
    // do stuff with arguments
    if(result.bar = whatever){
      callback(result);
    }
  });
}

doSomethingElse(result, callback){
  // do more stuff with result
  openAnotherDoc(id2, function(result2){
    if(result2.baz == true){
      callback(result2);
    }
  });
}

showMessage = function(result2){
  // show notification message with result2
}

When you look at checkForConflicts, you now immediately see what it does, without being bothered by the details. As a side effect, deciding which code needs access to which arguments helps you to understand your code better. In my case I was able to optimize the use of passed variables a lot.

You might argue that the code is much longer now. First, longer is not worse if it is more readable. Second, this is only an example - if there was code instead of //do stuff the few extra lines wouldn’t carry weight.

Finally here is a screenshot of my refactored code. All the methods don’t fit on one screen, but you can see what checkForConflicts does very quickly.

Testing PUT requests with Culerity

Sun, 31 Jan 2010 21:22:00 +0000

One major pain at testing with culerity so far was a HtmlUnit bug that causes a ScriptException with PUT AJAX requests in jQuery. When you tried to test an update you got a “java.lang.IllegalArgumentException: The content cannot be null”. Fortunately, this bug is fixed now. With latest HtmlUnit build culerity should run fine, and I tell you how.

I assume you have culerity installed already. If not, follow these instructions for testing Rails apps or these for testing Couchapps.

1. Make sure you have up-to-date versions of celerity and culerity:
$ jruby -S gem install celerity #(gives you celerity-0.7.8)
$ gem install culerity –source http://gemcutter.org #(gives you culerity-0.2.7)

2. Get the latest HtmlUnit nightly build:
$ wget http://build.canoo.com/htmlunit/artifacts/htmlunit-2.7-SNAPSHOT-with-dependencies.zip
$ unzip htmlunit-2.7-SNAPSHOT-with-dependencies.zip
$ cd htmlunit-2.7-SNAPSHOT-with-dependencies/lib
These are the jar files you need to copy into your celerity gem.

3. Find your celerity gem and copy the files:
$ jruby -S gem which celerity
$ cp * PATH_OF_JRUBY_INSTALLATION/lib/ruby/gems/1.8/gems/celerity-0.7.7/lib/celerity/htmlunit

4. The new HtmlUnit needs JQuery 1.4, so you need to upgrade if you haven’t done already. There’s a backwards compatibility plugin for 1.3 if this gives you trouble.

Have fun!

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.