= 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 * Highly readable * Framework / DOM independent * Rhino support * Async support * Ruby JavaScript testing server * Nested describes * Does not pollute core object prototypes * Cascading before/after/before_each/after_each hooks * Extremely simple and intuitive matcher declaration * Over 45 core matchers * Allows parens to be optional when using matchers to increase readability * Several helpful formatters (DOM, Console, Terminal, ...) * Assertion graphs displaying how many, and which assertions pass or failed * Default / customizable evaluation contexts * DOM sandbox support * Great looking default DOM theme * `jspec` command-line utility for auto-running specs, and initializing project templates * Profiling * Tiny (15 kb compressed, 1000-ish LOC) == Features Coming Soon * 'Spy' or 'Proxy' assertions. person.should.receive('addPet').with('suki').and_return(['suki']) * Grammar-less option. Dislike JSpec's grammar? well we will soon have grammar-less support, which in turn will make your specs look much like traditional JavaScript BDD frameworks: expect(this).to('be_coming', 'soon') == Example describe 'ShoppingCart' var cart before_each cart = new ShoppingCart end describe 'addProducts' it 'should add several products' cart.addProduct('cookie') cart.addProduct('icecream') cart.should.have 2, 'products' end end describe 'checkout' it 'throw an error when checking out with no products' -{ cart.clear().checkout() }.should.throw_error end end end == Installation Simply download JSpec and include JSpec.css and JSpec.js in your markup. Head over to the downloads section on Github, clone this public repo, or add JSpec as a git submodule with in your project. Alternatively JSpec is also available as a Ruby Gem (though this is not required), which also provides the `jspec` executable. To install as a gem simply: $ sudo gem install visionmedia-jspec At which point you may: $ jspec init myproject JSpec scripts should NOT be referenced via the ... You may optionally want to use sources in the /pkg directory for your project, since it includes compressed alternatives generated each release. == Options You may alter the way JSpec operates by assigning options via the JSpec.options hash, by passing string-based option values via the query string, or passing a hash to run(). For example JSpec.options.failuresOnly = true, and ?failuresOnly=1 will both work. * profile {bool} when enabled, uses console.time() in order to display performance information in your console log as specs are completed. (DOM, Console) * failuresOnly {bool} displays only failing specs, making them quick to discover and fix (DOM, Terminal) * reportToId {string} an element id to report to when using the DOM formatter (DOM) == Matchers * Core - equal, be === - be_a, be_an have constructor of x - be_an_instance_of instanceof 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 < - throw_error should throw an error, optionally supply the error string for comparison - have object should have n of property (person.should.have(2, 'pets')) - have_at_least object should have at least n of property - have_at_most object should have a maximum n of property - have_within object should have within n..n of property (person.should.have_within(1..3, 'pets') - have_length length of n - have_prop object should have property x, optionally supplying an expected value - have_property strict version of have_prop - be_within checks if n is within the range passed - include include substring, array element, or hash key - match string should match regexp x - respond_to property x should be a function - eql 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_one have exactly one tag - have_tags, have_many have more than one tag - have_child have exactly one child - have_children have more than one child - have_text have plain text - have_attr have an attribute, with optional value - have_type - have_id - have_title - have_alt - have_href - have_rel - have_rev - have_name - have_target - have_value - have_class - be_visible - be_hidden - be_enabled - be_disabled - be_selected - be_checked == 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 == Hooks Currently the following hooks are supported, and may be utilized any number of times as they are simply pushed to a stack. So for instance you may have two before_each blocks within the same scope, they will both run, but this can help keep your specs readable. * before run once before the suite is executed * after run once after the suite is executed * before_each run before each specification * after_each run after each specification == 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 to a non-polluting match() call: 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' === Closure Literal These are equivalent: -{ throw 'test' }.should.throw_error function() { throw 'test' }.should.throw_error === Inclusive Range Literal The following expands to the array of [1,2,3,4,5] n.should.be_within 1..5 === This Literal Commonly throughout using JSpec you will often need to do things like the following, while referencing 'this.cart' throughout your specs: before this.cart = new ShoppingCart end Thanks to the pre-processor we can simply use the terse alternative below: ... before .cart = new ShoppingCart end it '...' .cart.should.have 4, 'products' end ... Alternatively you may utilize literal javascript outside of the closures: ... cart = new ShoppingCart it '...' cart.should.have 4, 'products' end ... Another option is to declare a variable outside of the spec closures: var cart before cart = new ShoppingCart end it '...' cart.should.have 4, 'products' end ... == Formatters To change a formatter simply alter the options hash like below, assigning a new constructor, or pass it within the hash to run(): JSpec.options.formatter = JSpec.formatters.Console OR JSpec .exec('...') .run({ formatter : JSpec.formatters.Terminal }) .report() == Custom Matchers First lets create a simple equality matcher. In the case below JSpec is smart enough to realize this is simply a binary operator, and simply transforms this into 'actual === expected' JSpec.addMatchers({ equal : '===' }) To alias a method to keep your specs readable you may alias them like below: JSpec.addMatchers({ be : 'alias equal' }) 'foo'.should.equal 'foo' true.should.be true Matchers with string bodies implicitly return the expression value. The expanded version of the equal matcher would then be: JSpec.addMatchers({ equal : 'actual === expected' }) Large matchers or those which require several parameters may wish to utilize the hash method: JSpec.addMatchers({ equal : { match : function(actual, expected){ return actual === expected }} }) To keep JSpec tiny, JSpec will default to generating failure messages for you, how ever this can be explicitly defined: JSpec.addMatchers({ equal : { match : function(actual, expected){ return actual === expected }, message : function(actual, expected, negate) { return 'a message here' } } }) == JSpec Command-line Utility When installed as a Ruby Gem, the `jspec` executable will become available, allowing you to initialize project templates quickly, as well as auto-testing specifications when a file is altered. Initialize JSpec-driven project template in directory 'myproject': $ jspec init myproject Once within 'myproject' start testing by executing: $ jspec For additional usage execute: $ jspec help Or for specific usage: $ jspec help run == Rhino JSpec provides transparent support for Rhino, while using the Terminal formatter. Simply create a JavaScript file with contents similar to below, and then execute the command following it: load('lib/jspec.js') JSpec .exec('spec/spec.grammar.js') .exec('spec/spec.core.js') .run({ formatter : JSpec.formatters.Terminal, failuresOnly : true }) .report() Initialize project with: $ jspec init myproject --template rhino Run with: $ jspec run --rhino Or bind (automated testing): $ jspec --rhino == Server The Ruby JavaScript testing server included with JSpec simply runs the spec suites within each browser you specify, while reporting result back to the terminal. It is essentially the same as using the DOM formatter and auto-testing each browser, however results are centralized to the terminal, removing the need to manually view each browser's output. Initialize project with: $ jspec init myproject --template server Run with: $ jspec run --server == More Information * Syntax comparison with other frameworks http://gist.github.com/92283 * Get the TextMate bundle at https://github.com/visionmedia/jspec.tmbundle/tree * For more information consult the JSpec source code documentation or visit http://visionmedia.github.com/jspec == Known Issues * Opera likes to break for various reasons ... we are working on fixing these compat issues == License (The MIT License) Copyright (c) 2008 - 2009 TJ Holowaychuk 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.