visionmedia / jspec

Click here to lend your support to: jspec and make a donation at www.pledgie.com !

JavaScript BDD Framework. DOM independent, async support, 50+ matchers, non-polluting, tiny, highly readable, core jQuery support

This URL has Read+Write access

jspec /
name age
history
message
file History.txt Loading commit data...
file README.rdoc
file Rakefile
directory lib/
directory pkg/
directory spec/
README.rdoc

JSpec

JSpec is a minimalistic JavaScript behavior driven development framework, providing simple installation, extremely low learning curve, absolutely no pollution to core prototypes, async request support, and incredibly sexy syntax, tons of matchers and much more.

Features

  • Sexiest syntax of them all
  • Does not pollute core object prototypes
  • Async support (jQuery only at the moment)
  • Evalute any number of suites (or cherry pick specific suites loaded)
  • Evaluation contexts for providing helper methods and properties
  • Allows parens to be optional when using matchers (‘foobar’.should_include ‘foo’)
  • Extremely simple matcher declaration
  • Several helpful formatters
  • Custom formatters

Examples

  describe 'Shopping cart'

    before_each
      this.cart = new ShoppingCart
    end

    it 'should add products'
      this.cart.addProduct('cookie')
      this.cart.products.should_include('cookie')
      this.cart.should_not_be_empty
    end

  end

Installation

Simply download JSpec and include JSpec.css and JSpec.js in your markup ( head to the downloads section on Github, or clone this public repo). A div with the id of #jspec should be present for displaying when using the default DOM formatter, or you may pass options to report() to alter these default settings (view source code documentation for options).

JSpec scripts should NOT be referenced via the <script> tag, they should be loaded using the exec method. Below is an example: 

  ...
  <script>
    function runSuites() {
      JSpec
      .exec('spec.core.js')
      .exec('spec.jquery.js')
      .run()
      .report()
    }
  </script>
  <body onLoad="runSuites()">
  ...

To run specific suites we first load and evaluate a JSpec script, using the exec() method, then run specific suite(s), and report. 

  ...
  function runSuites() {
    JSpec
    .exec('spec.core.js')
    .runSuite('Matchers')
    .report()
  }
  ...

You may optionally want to use sources in the /pkg directory for your project, since it includes compressed alternatives.

Matchers

  * Core

  - equal            ===
  - be_a, be_an      have constructor of x
  - be_at_least      >=
  - be_at_most       <=
  - be_null          == null
  - be_empty         length of 0
  - be_true          == true
  - be_false         == false
  - be_type          be type of x
  - be_greater_than  >
  - be_less_than     <
  - have_length      length of x
  - include          include substring, array element, or hash key
  - match            string should match regexp x
  - respond_to       property x should be a function
  - eql, be          matches simple literals (strings, numbers) with == .
                     However composites like arrays or 'hashes' are recursively matched,
                     meaning that [1, 2, [3]].should_eql([1, 2, [3]]) will be true.

  * jQuery

  - have_tag         have exactly one tag
  - have_tags        have more than one tag
  - have_child       have exactly one child
  - have_children    have more than one child
  - have_text        have plain text
  - have_value
  - have_class
  - be_visible
  - be_hidden

Helpers

  * Core

  - sandbox     used to generate new DOM sandbox

  * jQuery

  - sandbox     used to generate new DOM sandbox, using jQuery object
  - element     same as invoking jQuery, just reads better and no need to worry about $ collisions
  - elements    alias of element

Custom Contexts

Custom contexts can be applied to supply helper methods or properties to all subsequent bodies (other hooks, or specs).

In most cases the default context will suffice, in combination with the ‘this’ keyword. Keep in mind that when replacing the default context you will loose functionality provided by it, unless you manually merge it into your custom context.

To reset the context simply assign null to obtain the original context. 

  ...
  before
    JSpec.context = { foo : 'bar' }
  end

  after
    JSpec.context = null
  end

  it 'will work ;)'
    this.foo.should_equal 'bar'
  end
  ...

Async Support

Currently only jspec.jquery.js supports async requests. JSpec uses jQuery.ajaxSetup and sets all requests to sync, which preserves execution order, and reports correctly. 

  it 'should load mah cookies (textfile)'
    $.post('async', function(text){
      text.should_eql 'cookies!'
    })
  end

Pre-processor

The pre-processing capability of JSpec is extremely powerful. Your JavaScript code is not necessarily what it seems. For example when you seemingly invoke a object’s prototype like below: 

  'foobar'.should_include 'bar'

First parens are added: 

  'foobar'.should_include('bar')

Secondly the matcher invocation is converted: 

  JSpec.match('foobar', 'should', 'include', 'bar')

This also means instead of: 

  var object = { foo : 'bar' }
  object.should_include 'foo'

We can do: 

  { foo : 'bar' }.should_include 'foo'

There is also an alternative closure literal so these are equivalent: 

  -{ throw 'test' }.should_throw_error
  function() { throw 'test' }.should_throw_error

Misc

  • Place the __END__ token in your document to prevent interpretation of the below it code. Useful for quickly debugging or speeding up suites.
  • For more information consult the JSpec source code documentation.
  • Get the TextMate bundle at github.com/visionmedia/jspec.tmbundle/tree

Todo

  • have include() match object hashes as well? so [1,2,[1]].should_include [1] => true
  • always pass matcher args as array (update docs)
  • better printing of objects .. recursive for array, html tag escaped, truncating of final string, etc
  • allow chaining of matchers within grammar
  • add formatter hooks to display spinner etc
  • finish terminal formatter / usage / github.com/jeresig/env-js/tree/master ?
  • nesting / nested display
  • firebug formatter

License

(The MIT License)

Copyright © 2008 - 2009 TJ Holowaychuk <tj@vision-media.ca>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.