visionmedia-jspec 1.1.3 → 1.1.4

data/History.rdoc

@@ -1,4 +1,37 @@
 
+=== 1.1.4 / 2009-04-17
+
+* Added rhino and server template files
+* Added JSpec.hasXhr()
+* Added JSpec.xhr()
+* Added Ruby javascript testing server
+* Added support for options passed to run()
+* Added failuresOnly for Terminal formatter
+* Added terminal assertion graphs
+* Addec color() utility
+* Added main.puts() since we use print() as a utility
+* Added rhino support
+* Added fail() utility function
+* Added JSpec.Assertion
+* Added normalizeMatcherMessage()
+* Added normalizeMatcherBody()
+* Added have_classes [#19]
+* Added extend() utility
+* Added be_an_instance_of matcher
+* Added constructor checking support for throw_error matcher [#72]
+* Added file support for exception messages, making them much easier to debug
+* Added catching of exceptions throw within specs [#46]
+* Changed; executable aborts when template does not exist
+* Changed; matchers now normalized upon creation, accepts function, hash, or string.
+* Changed be() matcher to be strict [#57]
+* Changed error() to conditionally show line number when available
+* Renamed Jspec.addSuite to JSpec.describe and Suite#addSpec to Suite#it
+* Refactored be_a_TYPE_input matchers so that the deprication warning is logged only when calling the method
+* Fixed JSpec.requires() now works with latest version of JSpec.error()
+* Fixed error() now displays exceptions throw that do not respond to .message
+* Fixed commenting bug [#37]
+* Removed JSpec.main, now just using local main
+
 === 1.1.3 / 2009-04-14
 
 * Removed /test used for the executable, causing gem to fail building

data/Manifest

@@ -12,15 +12,29 @@ lib/jspec.js
 Manifest
 Rakefile
 README.rdoc
+server/browsers.rb
+server/server.rb
 spec/async
 spec/jquery-1.3.1.js
+spec/server.html
 spec/spec.core.dom.js
 spec/spec.core.js
 spec/spec.grammar.js
 spec/spec.html
 spec/spec.jquery.js
+spec/spec.rhino.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
+templates/rhino/History.rdoc
+templates/rhino/lib/yourlib.core.js
+templates/rhino/README.rdoc
+templates/rhino/spec/spec.core.js
+templates/rhino/spec/spec.js
+templates/server/History.rdoc
+templates/server/lib/yourlib.core.js
+templates/server/README.rdoc
+templates/server/spec/spec.core.js
+templates/server/spec/spec.html

data/README.rdoc

@@ -8,15 +8,17 @@ and much more.
 
 == Features
 
-* Sexiest syntax of them all
+* Highly readable
 * Framework / DOM independent
+* Rhino support
+* Async support
+* Ruby JavaScript testing server
 * 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, ...)
+* Several helpful formatters (DOM, Console, Terminal, ...)
 * Assertion graphs displaying how many, and which assertions pass or failed
 * Default / customizable evaluation contexts
 * DOM sandbox support
@@ -25,6 +27,13 @@ and much more.
 * 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'
@@ -54,8 +63,8 @@ and much more.
 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, which also provides the `jspec` executable. To
-install as a gem simply:
+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:
@@ -70,7 +79,7 @@ loaded using the exec method. Below is an example:
       JSpec
       .exec('spec.core.js')
       .exec('spec.jquery.js')
-      .run()
+      .run({ failuresOnly : true })
       .report()
     }
   </script>
@@ -84,44 +93,45 @@ 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.
+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.
-* 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
+* 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_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.
+  - 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
   
@@ -294,21 +304,16 @@ Another option is to declare a variable outside of the spec closures:
 == Formatters
 
 To change a formatter simply alter the options hash like below, assigning
-a new constructor:
+a new constructor, or pass it within the hash to run():
 
   JSpec.options.formatter = JSpec.formatters.Console
 
-=== DOM
-  
-Clean attractive HTML reporting
-
-=== Console
+OR
 
-Reporting utilizing the console object (tested using Firebug and Safari 4)
-
-=== Terminal
-
-Coming soon
+	JSpec
+	.exec('...')
+	.run({ formatter : JSpec.formatters.Terminal })
+	.report()
 
 == Custom Matchers
 
@@ -376,14 +381,53 @@ For additional usage execute:
 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)

data/bin/jspec

@@ -1,32 +1,53 @@
 #!/usr/bin/env ruby
 
+JSPEC_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+$:.unshift JSPEC_ROOT
+ 
 require 'rubygems'
 require 'commander'
 require 'fileutils'
 
-JSPEC_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+RHINO = 'java org.mozilla.javascript.tools.shell.Main'
 
 program :name, 'JSpec'
-program :version, '1.1.3'
+program :version, '1.1.4'
 program :description, 'JavaScript BDD Testing Framework'
 default_command :bind
 
 command :init do |c|
   c.syntax = 'jspec init [dest]'
   c.summary = 'Initialize a JSpec project template'
-  c.description = 'Initialize a JSpec project template. Defaults to the current directory when 
-    <dest> is not specified.'
+  c.description = 'Initialize a JSpec project template. Defaults to the current directory
+    when [dest] is not specified. Currently three templates are available:
+    
+    "default" : runs specs in browser(s) using the DOM formatter.
+    "rhino"   : runs specs with Rhino using the Terminal formatter.
+    "server"  : runs specs using a Ruby server/client solution which
+                starts each browser and reports back to the terminal.'
   c.example 'Create a directory foo, initialized with a jspec template', 'jspec init foo'
+  c.example 'Initialize a rhino based project in the current directory', 'jspec init --template rhino'
+  c.example 'Initialize a server based project in foo', 'jspec init foo --template server'
+  c.option '-T', '--template name', 'Template to use. Valid choices are default, rhino, and server.'
   c.when_called do |args, options|
     dest = args.shift || '.'
+    options.default :template => 'default'
     unless Dir[dest + '/*'].empty?
       abort unless agree "'#{dest}' is not empty; continue? "
     end
+    template = File.join JSPEC_ROOT, 'templates', options.template, '.'
+    abort "template #{options.template} does not exist" unless File.exists? template
     FileUtils.mkdir_p dest
-    FileUtils.cp_r File.join(JSPEC_ROOT, 'templates', 'default', '.'), dest
-    spec = File.join dest, 'spec', 'spec.html'
-    contents = File.read(spec).gsub 'JSPEC_ROOT', JSPEC_ROOT
-    File.open(spec, 'w') { |file| file.write contents }
+    FileUtils.cp_r template, dest
+    path = case options.template
+      when 'default' ; 'spec.html'
+      when 'rhino'   ; 'spec.js'
+      else
+      end
+    if path
+      spec = File.join dest, 'spec', path
+      contents = File.read(spec).gsub 'JSPEC_ROOT', JSPEC_ROOT
+      File.open(spec, 'w') { |file| file.write contents }
+    end
     say "Template initialized at '#{dest}'"
   end
 end
@@ -36,7 +57,9 @@ command :update do |c|
   c.summary = 'Update JSpec releases'
   c.description = 'Update JSpec release in [paths], this will allow you to utilize the latest
     JSpec features. If you have suites running at a path other than the regular 
-    spec/spec.html simply pass them as arguments to this sub-command.'
+    spec/spec.html simply pass them as arguments to this sub-command.
+    
+    This is only needed when using the default, or rhino project templates.'
   c.when_called do |args, options|
     args = %w( spec/spec.html ) if args.empty?
     args.each do |path|
@@ -54,30 +77,61 @@ command :run do |c|
   c.description = 'Run specifications, defaulting [path] to spec/spec.html. You will need 
     supply [path] if your specs do not reside in this location. `run --bind` is
     the default sub-command of jspec so you may simply execute `jspec` in order
-    to bind execution of your specs when a file is altered.'
+    to bind execution of your specs when a file is altered.
+    
+    JSpec supports Rhino execution when installed. The [path] is assumed to be 
+    spec/spec.js unless specified. See examples below for using the --rhino switch.'
   c.example 'Run once in Safari', 'jspec run'
   c.example 'Run once in Safari and Firefox', 'jspec run --browsers Safari,Firefox'
   c.example 'Run custom spec file', 'jspec run foo.html'
-  c.example 'Auto-refresh browsers when a file is altered', 'jspec run --bind --browsers Safari,Firefox'
+  c.example 'Auto-run browsers when a file is altered', 'jspec run --bind --browsers Safari,Firefox'
   c.example 'Shortcut for the previous example', 'jspec --browsers Safari,Firefox'
+  c.example 'Auto-run rhino when a file is altered', 'jspec --rhino'
+  c.example 'Run Rhino specs once', 'jspec run --rhino'
   c.option '-b', '--browsers BROWSERS', Array, 'Specify browsers to test, defaults to Safari'
   c.option '-p', '--paths PATHS', Array, 'Specify paths when binding, defaults to javascript within ./lib and ./spec'
   c.option '-B', '--bind', 'Auto-run specs when source files or specs are altered'
+  c.option '-R', '--rhino', 'Run specs using Rhino'
+  c.option '-S', '--server', 'Run specs using the JSpec server'
+  c.option '-s', '--server-only', 'Start JSpec server without running browsers'
   c.when_called do |args, options|
     begin
       require 'bind'
-      spec = args.shift || 'spec/spec.html'
       options.default :browsers => %w( Safari ), :paths => ['lib/**/*.js', 'spec/**/*.js']
-      action = Bind::Actions::RefreshBrowsers.new spec, *options.browsers
+      
+      # Actions
+      if options.rhino
+        spec = args.shift || 'spec/spec.js'
+        action = lambda { rhino spec }
+      elsif options.server
+        spec = args.shift || 'spec/spec.html'
+        action = lambda { start_server options, spec }
+      else
+        spec = args.shift || 'spec/spec.html'
+        action = Bind::Actions::RefreshBrowsers.new spec, *options.browsers
+      end
+      
+      # Binding
       if options.bind
         listener = Bind::Listener.new :paths => options.paths, :interval => 1, :actions => [action], :debug => $stdout
         listener.run!
       else
-        action.call spec
+        action.call File.new(spec)
       end
+      
     rescue LoadError
       abort "jspec run requires the visionmedia-bind gem; http://visionmedia.github.com/bind/"
     end
   end
 end
 alias_command :bind, :run, '--bind'
+
+def rhino file
+  abort "#{file} not found" unless File.exists? file
+  system "#{RHINO} #{file}"
+end
+
+def start_server options, spec
+  require 'server/server'
+  JSpec::Server.start options, spec
+end

data/jspec.gemspec

@@ -2,17 +2,17 @@
 
 Gem::Specification.new do |s|
   s.name = %q{jspec}
-  s.version = "1.1.3"
+  s.version = "1.1.4"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
   s.authors = ["TJ Holowaychuk"]
-  s.date = %q{2009-04-14}
+  s.date = %q{2009-04-17}
   s.default_executable = %q{jspec}
   s.description = %q{JavaScript BDD Testing Framework}
   s.email = %q{tj@vision-media.ca}
   s.executables = ["jspec"]
   s.extra_rdoc_files = ["bin/jspec", "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", "README.rdoc"]
-  s.files = ["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"]
+  s.files = ["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", "server/browsers.rb", "server/server.rb", "spec/async", "spec/jquery-1.3.1.js", "spec/server.html", "spec/spec.core.dom.js", "spec/spec.core.js", "spec/spec.grammar.js", "spec/spec.html", "spec/spec.jquery.js", "spec/spec.rhino.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", "templates/rhino/History.rdoc", "templates/rhino/lib/yourlib.core.js", "templates/rhino/README.rdoc", "templates/rhino/spec/spec.core.js", "templates/rhino/spec/spec.js", "templates/server/History.rdoc", "templates/server/lib/yourlib.core.js", "templates/server/README.rdoc", "templates/server/spec/spec.core.js", "templates/server/spec/spec.html"]
   s.has_rdoc = true
   s.homepage = %q{http://visionmedia.github.com/jspec}
   s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Jspec", "--main", "README.rdoc"]

data/lib/jspec.jquery.js

@@ -1,68 +1,74 @@
 
 // JSpec - jQuery - Copyright TJ Holowaychuk <tj@vision-media.ca> (MIT Licensed)
 
-(function($, $$){
+(function(){
 
   // --- Dependencies
 
-  $$.requires('jQuery', 'when using jspec.jquery.js')
+  JSpec.requires('jQuery', 'when using jspec.jquery.js')
   
   // --- Async Support
 
-  $.ajaxSetup({ async : false })
+  jQuery.ajaxSetup({ async : false })
 
   // --- Helpers
 
-  $$.defaultContext.element = $
-  $$.defaultContext.elements = $
-  $$.defaultContext.defaultSandbox = $$.defaultContext.sandbox
-  $$.defaultContext.sandbox = function() { return $($$.defaultContext.defaultSandbox()) }
+  JSpec.defaultContext.element = jQuery
+  JSpec.defaultContext.elements = jQuery
+  JSpec.defaultContext.defaultSandbox = JSpec.defaultContext.sandbox
+  JSpec.defaultContext.sandbox = function() { return jQuery(JSpec.defaultContext.defaultSandbox()) }
 
   // --- Matchers
 
-  $$.addMatchers({
+  JSpec.addMatchers({
     have_tag      : "jQuery(expected, actual).length == 1",
     have_one      : "alias have_tag",
     have_tags     : "jQuery(expected, actual).length > 1",
     have_many     : "alias have_tags",
     have_child    : "jQuery(actual).children(expected).length == 1",
     have_children : "jQuery(actual).children(expected).length > 1",
-    have_class    : "jQuery(actual).hasClass(expected)",
     have_text     : "jQuery(actual).text() == expected",
     have_value    : "jQuery(actual).val() == expected",
     be_visible    : "!jQuery(actual).is(':hidden')",
     be_hidden     : "jQuery(actual).is(':hidden')",
     be_enabled    : "!jQuery(actual).attr('disabled')",
+    have_class    : "jQuery(actual).hasClass(expected)",
     
-    have_attr : { match : function(actual, attr, value) {
-        if (value) return $(actual).attr(attr) == value
-        else return $(actual).attr(attr)
-      }
+    have_classes : function(actual) {
+      for (i = 1; i < arguments.length; i++)
+        if (!jQuery(actual).hasClass(arguments[i])) return false
+      return true
+    },
+    
+    have_attr : function(actual, attr, value) {
+      return value ? jQuery(actual).attr(attr) == value:
+                     jQuery(actual).attr(attr)
     }
   })
   
   // --- be_BOOLATTR
   
-  $$.each('disabled selected checked', function(attr){
-    $$.matchers['be_' + attr] = "jQuery(actual).attr('" + attr + "')"
+  JSpec.each('disabled selected checked', function(attr){
+    JSpec.addMatcher('be_' + attr, "jQuery(actual).attr('" + attr + "')")
   })
   
   // --- have_ATTR
   
-  $$.each('type id title alt href src rel rev name target', function(attr){
-    $$.matchers['have_' + attr] = { match : function(actual, value) {
-        return $$.matchers.have_attr.match(actual, attr, value)
-      }
-    }
+  JSpec.each('type id title alt href src rel rev name target', function(attr){
+    JSpec.addMatcher('have_' + attr, function(actual, value) {
+      return JSpec.matchers.have_attr.match(actual, attr, value)
+    })
   })
   
   // --- be_a_TYPE_input (deprecated)
   
-  $$.each('checkbox radio file password submit image text reset button', function(type){
-    console.warn("be_a_" + type + "_input is deprected; use have_type('" + type + "')");
-    JSpec.matchers['be_a_' + type + '_input'] = "jQuery(actual).get(0).type == '" + type + "'"
+  JSpec.each('checkbox radio file password submit image text reset button', function(type){
+    JSpec.addMatcher('be_a_' + type + '_input', function(actual, expected) {
+      console.warn("be_a_" + type + "_input is deprected; use have_type('" + type + "')");
+      return jQuery(actual).get(0).type == type
+    })
   })
   
-})(jQuery, JSpec)
+})()