A Week of Javascript TDD Day 2: Visionmedia’s jspec

Today I’m going to take a look at visionmedia’s jspec. I came across jspec randomly on github when someone else I followed forked it, definitely a testament to the importance of the social media aspect of github.

The Dirty Details

jspec is another BDD javascript framework. Nothing else to say about that.

License
It’s distributed under the MIT license.

Last Updated
Continuously. Last update was 5 days ago.

Support
No mailing list listed, however there is a lighthouse tracker for reporting bugs. You can also contact the authors on github.

Okay… Let’s Dive In!

The cool thing about jspec is it is also available as a gem… so I’m going to be doing the first example using the rubygem way. Afterwards I may try the non gem way, but we’ll see.


sudo gem install visionmedia-jspec

From here it’s commandline commando mode, which is pretty comfortable if you’re like me and use to writing specs in rspec. I create a new directory for this example, cd to it, and run jspec init to setup a template. This creates a lib folder and spec folder… the spec folder contains an example to get you started, spec.html and spec.core.js (which gives a small example of a spec using the parenthesis-less grammer). Open up spec.html in a browser and you should see the spec results. Cool! Well… lets get started writing our first spec describing the placeholder attribute behavior.

Let’s go ahead and rename the spec.core.js file to html5.placeholder.spec.js (you don’t have to have the word spec in the filename, I just decided to do that). We also need to update spec.html to call .exec('html5.placeholder.spec.js') (of course). Remember, specs must be included through .exec and not with a script tag if you want it ran. Finally, lets rename ../lib/yourlib.core.js to ../lib/html5.placeholder.js.

Also… since we’re going to be doing a little DOM manipulation we’ll want to include jquery. So in spec.html copy and paste the script tag for jspec.js and change it to jspec.jquery.js (this is the library that adds some handy jquery based utilities). Since this requires jquery, you’ll also need to include jquery, either a local copy or you can do like me and just use the one hosted at google.

One thing I like about jspec is that it tries to be as pure as possible… since you can run the tests even in rhino, it discourages you from just adding html for your needs … instead if you are using jspec.jquery.js you can call the sandbox method to create the elements you need, and pass the jquery context from it to your objects as a dependency. I’m sure there’s other techniques, but it’s what I did. Okay, enough jibbering, let’s get started!

describe 'Html5 Emulator'
  describe 'placeholder attribute behavior'
    it 'should set value to the same text as placeholder'
      input = sandbox()
      input.append("")
      
      field_with_placeholder = $('#first_name', input)
      
      emulator = new carrcraft.Html5Emulator()
      emulator.emulateInputs(input)      
      
      field_with_placeholder.should.have_value 'Enter your name'
    end
  end
end

Are you sure that’s javascript? ;)

Yep… it’s the custom grammer of jspec at work. And despite what I originally thought this doesn’t have to run from ruby nor does it require rubygems… it can be interpreted from both a client side browser or rhino because the grammer is just parsed by jspec’s core library.

I won’t spend too much more time on the coding aspect… you can look at the results of trying out jspec on github under my js-testing-frameworks project.

What I liked

Wow… where do I start? I have to say that although I didn’t get to illustrate it in this example, I LOVE the fact that it has built in support for spies and stubs. Additionally, it also has a handy wait method for testing setTimeouts/setIntervals as well as async support via jquery.

Other things I liked:

  • commandline runner
  • built in rhino support
  • Project template creation
  • autospec like behavior
  • matchers built on top of jquery
  • specs don’t require an html file
  • sexy syntax ;)
  • ability to opt out of custom syntax and use plain javascript
  • nested describes are supported
  • TextMate bundle
  • Rails Integration

Dislikes

None really… I really really liked this BDD framework and believe it is vastly superior to jsspec. I think the syntax might confuse newbies a little bit since it’s not pure javascript, but I found it pretty easy to follow and pick up and like I mentioned earlier it can be turned off.

Closing Thoughts

Wow. I think I might scrap my jsspec-ant project and just use jspec’s commandline runner from hudson… at this point I don’t need to really write much to get it working from CI. Pretty sweet. If it must absolutely run from ant, one could just write a thin task using jruby to run specs and report results.

I forgot to mention how to set jspec up the non-rubygems way… it’s actually quite simple. Just go to the visionmedia jspec github page, download the zip, and extract jspec.css, jspec.js, and jspec.jquery.js (optional) to a directory of your choice, include them in an html file and add your spec.js files in exec methods (like below):

function runSuites() {
        JSpec
        .exec('html5.placeholder.spec.js')
        .exec('customer_order.spec.js')
        .run()
        .report()
      }

And crack it open in a browser. But the rubygems way is just so much nicer ;)