visionmedia-jspec 1.1.1

data/History.rdoc

@@ -0,0 +1,232 @@
+
+=== 1.1.1 / 2009-04-12
+
+* Added gemspec
+
+=== 1.1.0 / 2009-04-12
+
+* jspec executable fully functional
+
+=== 1.0.4 / 2009-04-09
+
+* Added `jspec bind`
+* Added `jspec run`
+* Added `jspec init`
+* Added `jspec` executable
+* Added gemspec and manifest
+* Added command-line usage docs
+* Added custom matchers documentation
+* Removed double negation
+
+=== 1.0.3 / 2009-04-08
+
+* Added have_prop matcher, have_property is now strict [#56]
+
+=== 1.0.2 / 2009-04-08
+
+* Added be_selected, be_checked matchers
+* Added string support to each() each('some foo bar', ...)
+* Added have_ATTR matchers [#51]
+* Deprected be_a_TYPE_input matchers [#50]
+
+=== 1.0.1 / 2009-04-07
+
+* Added have_property matcher [#53]
+
+=== 1.0.0 / 2009-04-06
+
+* Added option() which gives the query string option precedence [#39]
+* Changed; Using JSpec.options.formatter not JSpec.formatter [#44]
+* Fixed Console formatter, now displays nested suites
+* Check out http://visionmedia.github.com/jspec for additional documentation!
+
+=== 0.9.6 / 2009-04-03
+
+* Added nesting support
+* Added printing of nested specs
+* Added assertion graphs to DOM formatter
+* Refactored preprocess()
+* Refactored most of the specs
+* Renamed preProcess() to preprocess()
+* Removed running of a single suite via ?suite= for now
+
+=== 0.9.5 / 2009-04-02
+
+* Added support for printing of function bodies and regexps [#27]
+* Added support for strings / regexp with should_throw_error [#26]
+* Added have_within matcher
+* Added have_at_most matcher
+* Added have_at_least matcher
+* Added have matcher [#24]
+
+=== 0.9.4 / 2009-04-02
+
+* Added be_a_TYPE_input matchers (be_a_checkbox_input, be_a_text_input, etc)
+* Added be_disabled matcher [#21]
+* Added be_enabled matcher [#20]
+* Refactored be_visible and be_hidden with $(elem).is()
+
+=== 0.9.2 / 2009-04-02
+
+* Added support for multi-arg failure messages [#2]
+* Better printing of jQuery objects [#15]
+
+=== 0.9.1 / 2009-04-02
+
+* Added support for dotted negation of assertions (foo.should.not.equal bar)
+* Added support for dot-style assertions [#17] (foo.should_not.equal bar)
+
+=== 0.9.0 / 2009-04-01
+
+* Added spec for strip()
+* Added strip()
+* Added any() util
+* Added new improved include matcher
+* Added have_many and have_one matchers
+* Added have_attr matcher [#14]
+* Added map() util
+* Added inject() util
+* Added escape() util
+* Added recursive array and object printing
+* Added DOM formatter option failuresOnly
+* Added support for running of a single squite via ?suite=...
+* Added query() util
+* Added last() util
+* Added be_within matcher, accepts a range literal
+* Added inclusive range literal n..n
+* Added row hover
+* Refactored range()
+* Refactored setMessage()
+* Refactored hash()
+* Changed; preprocessor passing array of args (multi-arg matcher support)
+* Changed jQuery to $ for internal usage
+
+=== 0.8.0 / 2009-02-27
+
+* Added a new style for the DOM formatter (not finished yet)
+
+=== 0.7.0 / 2009-02-27
+
+* Added Console formatter (anything implementing the console object. Firebug, Safari 4, etc)
+* Added JSpec.options.profile for optional profiling of specs
+* Added this. literal alternative (view readme)
+* Moved formatters into JSpec.formatters 
+* Added error() util
+* Added savings raketask
+* Fixed parse error bug in Safari 4
+
+=== 0.6.3 / 2009-02-26
+
+* Added minification for jspec.jquery.js when packaging before release
+* Added compression of css when packaging before release
+
+=== 0.6.2 / 2009-02-26
+
+* Changed; using $ in jspec.jquery.js for JSpec, take that jQuery ;)
+* Added addMatchers, print, hash, and each as 'utility functions' this allows 
+  JSpec to do each(...) internally instead of JSpec.each(...), while still preventing
+  pollution of the global scope.
+
+=== 0.6.1 / 2009-02-26
+
+* Added closrue literal -{ (view README)
+* Added option to DOM formatter, now allows you to specify which element id to output to
+
+=== 0.6.0 / 2009-02-24
+
+* Added JSpec.hash 
+* Added be_null matcher
+* Allow recursive composite matching using should_eql and should_not_eql
+  For example [1, 2, [3]].should_eql([1, 2, [3]]) is true, works with object
+  'hashes' as well.
+
+=== 0.5.1 / 2009-02-24
+
+* Damn auto-release messed up
+
+=== 0.5.0 / 2009-02-24
+
+* Added async support for jQuery
+* Added JSpec.requires for dependencies
+* Added JSpec.throw
+* Added JSpec.runSpec
+* Refactored jspec.jquery.js
+* Fixed evalBody exceptions, previously was not showing exception message
+* Fixed bug of JSpec interpreting // in a string such as http:// to be a comment.
+
+=== 0.4.1 / 2009-02-22
+
+* Added elements() alias of element()
+* Added support for string passed to runSuite; runSuite('Matchers') is the same as
+  runSuite(JSpec.suites['Matchers']).
+* Fixed some documentation
+
+=== 0.4.0 / 2009-02-20
+
+* Added comment literal (//)
+* Added pre-processor for convering matchers.
+  For example 'test'.should_be_true becomes JSpec.match('test', 'should_be', 'true'),
+  preventing pollution of core prototypes.
+
+=== 0.3.2 / 2009-02-19
+
+* Added TM bundle (go checkout my jspec.tmbundle repo on github)
+* Renamed have_length_of to have_length
+
+=== 0.3.1 / 2009-02-19
+
+* Added jquery js to package
+
+=== 0.3.0 / 2009-02-19
+
+* Added JSpec.match
+* Added options to report() which are passed to formatter
+* Added sandbox helpers (reg / jquery)
+* Added have_child and have_children
+* Added have_tag and have_tags
+* Changed exec to only load / eval file
+* Fixed parser token issue, was previously matching things like end() as literal end
+
+=== 0.2.3 / 2009-02-18
+
+* Changed test dir to spec
+* Changed test.js to core.spec.js
+
+=== 0.2.2 / 2009-02-18
+
+* Added contexts
+
+=== 0.2.0 / 2009-02-18
+
+* Added release rake task
+* Added package with minified alternative
+
+=== 0.1.0 / 2009-02-18
+
+* Added new sexy syntax (warning: you will have to re-write your specs)
+* Added pre-processor for optional matcher parens 
+* Added several new matchers 
+* Added matcher aliasing 
+* Added simple matcher declarations 
+* Added __END__ 
+* Added yet-to-be-implemented specs 
+* Added loading of suites via JSpec.load
+
+=== 0.0.4 / 2008-11-03
+
+* Added ability to pass only a description to it(), meaning not yet implemented
+
+=== 0.0.3 / 2008-10-28
+
+* Added should_fail
+* Added should_match
+* Added should_not_match
+* Added should_be and should_not_be
+
+=== 0.0.2 / 2008-10-28
+
+* Fixed typo in documentation for pointing to the master repo
+
+=== 0.0.1 / 2008-10-28
+
+* Initial release

data/Manifest

@@ -0,0 +1,26 @@
+bin/jspec
+History.rdoc
+jspec.gemspec
+lib/images/bg.png
+lib/images/hr.png
+lib/images/sprites.bg.png
+lib/images/sprites.png
+lib/images/vr.png
+lib/jspec.css
+lib/jspec.jquery.js
+lib/jspec.js
+Manifest
+Rakefile
+README.rdoc
+spec/async
+spec/jquery-1.3.1.js
+spec/spec.core.dom.js
+spec/spec.core.js
+spec/spec.grammar.js
+spec/spec.html
+spec/spec.jquery.js
+templates/default/History.rdoc
+templates/default/lib/yourlib.core.js
+templates/default/README.rdoc
+templates/default/spec/spec.core.js
+templates/default/spec/spec.html

data/README.rdoc

@@ -0,0 +1,406 @@
+
+= 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
+* Framework / DOM independent
+* Nested describes
+* Does not pollute core object prototypes
+* Async support
+* 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)
+
+== 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.
+
+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()">
+  ...
+
+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, or by passing string-based option values via the 
+query string. 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.
+* failuresOnly {bool} displays only failing specs, making them quick to discover and fix
+* reportToId {string} an element id to report to when using the DOM formatter
+  
+== 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     <
+  - 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, 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_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:
+
+  JSpec.options.formatter = JSpec.formatters.Console
+
+=== DOM
+  
+Clean attractive HTML reporting
+
+=== Console
+
+Reporting utilizing the console object (tested using Firebug and Safari 4)
+
+=== Terminal
+
+Coming soon
+
+== 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
+
+== 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
+
+== License 
+
+(The MIT License)
+
+Copyright (c) 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.
+
+