rspec 0.1.7 → 0.2.0

data/CHANGES

@@ -13,6 +13,15 @@
 * Make sure the PKG_VERSION constant in Rakefile.rb is
   consistent with the latest version in this document.
 
+== Version 0.2.0
+
+This release provides a tutorial for new users wishing to get started with
+RSpec, and many improvements.
+
+* improved reporting in the spec runner output
+* update the examples to the new mock api
+* added TUTORIAL, a getting started document for new users of RSpec
+
 == Version 0.1.7
 
 This release improves installation and documentation, mock integration and error reporting.

data/Rakefile.rb

@@ -19,7 +19,7 @@ PKG_NAME = "rspec"
 # (This is subject to change - AH)
 #
 # REMEMBER TO KEEP PKG_VERSION IN SYNC WITH CHANGELOG
-PKG_VERSION = "0.1.7"
+PKG_VERSION = "0.2.0"
 PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
 PKG_FILES = FileList[
   '[A-Z]*',
@@ -29,9 +29,7 @@ PKG_FILES = FileList[
   'doc/**/*'
 ]
 
-task :default => [:test, :test_craps_collector, :test_movie_collector,
-	:test_rspec_craps, :test_rspec_movie, :test_rspec_craps_and_movie,
-	:test_text_runner]
+task :default => [:test, :test_text_runner]
 
 Rake::TestTask.new do |t|
   t.libs << "test"
@@ -40,45 +38,6 @@ Rake::TestTask.new do |t|
   t.verbose = true
 end
 
-# collector tests need to run individually
-
-Rake::TestTask.new(:test_craps_collector) do |t|
-	t.libs << "test"
-	t.libs << "examples"
-	t.test_files = FileList['test/craps_collector_test.rb']
-	t.verbose = true
-end
-
-Rake::TestTask.new(:test_movie_collector) do |t|
-	t.libs << "test"
-	t.libs << "examples"
-	t.test_files = FileList['test/movie_collector_test.rb']
-	t.verbose = true
-end
-
-# rspec tests need to run individually
-
-Rake::TestTask.new(:test_rspec_craps) do |t|
-	t.libs << "test"
-	t.libs << "examples"
-	t.test_files = FileList['test/rspec_craps_test.rb']
-	t.verbose = true
-end
-
-Rake::TestTask.new(:test_rspec_movie) do |t|
-	t.libs << "test"
-	t.libs << "examples"
-	t.test_files = FileList['test/rspec_movie_test.rb']
-	t.verbose = true
-end
-
-Rake::TestTask.new(:test_rspec_craps_and_movie) do |t|
-	t.libs << "test"
-	t.libs << "examples"
-	t.test_files = FileList['test/rspec_craps_and_movie_test.rb']
-	t.verbose = true
-end
-
 # text runner tests need to run individually
 
 Rake::TestTask.new(:test_text_runner) do |t|

data/TUTORIAL

@@ -0,0 +1,259 @@
+= Getting Started with RSpec
+
+RSpec is a behaviour specification framework for the Ruby Programming
+Language. More information on the Ruby Programming Language can be found at
+http://www.ruby-lang.org/. For more information on Behaviour Driven
+Development, please see _A New Look at Test Driven Development_ which can be
+found at http://www.daveastels.com/index.php?p=5.
+
+This document is intended to help those interested in getting started with
+Behaviour Driven Development using the RSpec behaviour specification
+framework. Please send comments and/or corrections to me via email: srbaker at
+pobox dot com.
+
+== Installation
+
+The first thing you need to do to start specifying your software is to install
+RSpec. Thanks to the work on the Gem packaging of RSpec by Aslak Hellesoy, you
+can install RSpec via RubyGems by issuing the following command:
+
+    $ gem install rspec
+
+If you do not have RubyGems installed, see http://docs.rubygems.org/ for
+information about RubyGems including how to install it.
+
+== Usage
+
+Once you have RSpec installed, ensure that it is correctly installed by
+running the spec command from the command line without arguments. You should
+get something like the following output:
+
+    Finished in 0.002726 seconds
+    
+    0 specifications, 0 expectations, 0 failures
+
+If you get this output, you can be sure that RSpec has been installed and is
+ready for use!
+
+= Specification Anatomy
+
+== Expectations
+
+The simplest part of your set of specifications will be an expectation. An
+expectation tells RSpec what the expected result of a piece code is. Your set of
+specifications is simply a collection of expectations about how your code should
+behave.
+
+In RSpec, the expectations are methods that are available on every object in the
+system. If I want to set an expectation that the value of 1 is 1, I would write:
+
+    1.should_equal 1
+
+And to set the expectation that 1 + 1 should be equal to 2, I would write the
+following code:
+
+    (1 + 1).should_equal 2
+
+There are many available expectation methods, and they can be found by looking
+in the API documentation for RSpec. For most, if not all, of the expections
+the negation is also provided. Thus, to ensure that subtracting 1 from 2 does
+not equal 2, write the following:
+
+    (2 - 1).should_not_equal 2
+
+These examples are extremely simple, but they accurately convey the simplicity
+with which expectations can be written. When specifying your software, you are
+simply writing expectations that specify how your software will behave. The rest
+of the constructs in RSpec exist entirely to help you organize your
+expectations, and to provide accurate and helpful reporting when these
+expectations are not met.
+
+Eventually, writing expectations for addition and subtraction of numbers will
+get boring. When that happens, you can start writing expectations for your own
+code. Let's try a slightly more involved example.
+
+We have been asked to write a robot which will start at a given X, Y coordinate,
+and will move in for directions a given number of units. If no starting
+coordinate is given, the robot will start at 0,0. When the robot is moved, a
+two-element array should be returned with the x and y coordinates. Some
+expectations you might write for this robot might be the following:
+
+    rob = Robot.new
+
+    rob.should_not_be_nil
+    rob.should_be_kind_of Robot
+    rob.x_coordinate.should_equal 0
+    rob.y_coordinate.should_equal 0
+    rob.location.should_equal [0,0]
+    
+    rob.move_north(1).should_equal [0, 1]
+    rob.move_south(5).should_equal [0, -4]
+    rob.move_east(10).should_equal [10, -4]
+    rob.move_west(5).should_equal [5, -4]
+
+The code example above isn't intended to demonstrate good design, but has been
+created explicitly to demonstrate the use of the expectation methods.
+
+Also note that these expectations would be written iteratively, but the purpose
+of this document is to serve as an introduction to the RSpec framework, not to
+Behaviour Driven Development itself.
+
+As you can see, writing expectations can be rather verbose, even for a simple
+project like the example above. For clarity, your expectations will be grouped
+into specifications, which are described in the next section.
+
+== Specifications
+
+Your software will be specified by writing expectations, which were explained in
+the previous section. Your expectations will be grouped into specifications for
+clarity. A specification is simply a method that contains expectations. The name
+of your specification will be used by the Spec Runner (see Running and
+Reporting) to inform you of unmet expectations, so choose your names wisely.
+
+Consider the robot example from the previous example, but divided into
+specification methods:
+
+    def initialization_without_coordinates
+      rob = Robot.new
+      rob.x_coordinate.should_equal 0
+      rob.y_coordinate.should_equal 0
+      rob.location.should_equal [0,0]
+    end
+
+    def initialization_with_coordinates
+      rob = Robot.new(10, 15)
+      rob.x_coordinate.should_equal 10
+      rob.y_coordinate.should_equal 15
+      rob.location.should_equal [10, 15]
+    end
+
+    def north_movement
+      rob = Robot.new
+      rob.move_north(1).should_equal [0, 1]
+    end
+
+    def west_movement
+      rob = Robot.new(10, 5)
+      rob.move_west(15).should_equal [-5, 5]
+    end
+
+By dividing expectations into specification methods, our specifications for the
+behaviour of our software are far easier to read and clearly express the intent.
+Even those who are unfamiliar with Ruby specifically (and perhaps even some who
+are relatively unfamiliar with software development in general) can easily read
+our specifications.
+
+== Fixtures
+
+As you can see, there is some duplicated code in the example from the last
+section in the creation of the Robot objects. You will find that the
+initialization of objects will often be duplicated when writing specifications.
+RSpec provides you with a way of setting up this data ahead of time, by
+providing two methods: setup and teardown.
+
+The setup method is called before invoking each specification to allow you to
+set up resources which are required for each specification, and the teardown
+method is called after invoking each specification, to allow you to
+appropriately deallocate or close resources wich were required for the
+specifications.
+
+The example in the next section include a demonstration of the usage of fixtures
+in Contexts.
+
+== Contexts
+
+The specifications described in the Specifications example are absolutely
+useless if they're not placed in a context. Because you will be writing a large
+number of specifications for your software, you will want a way to divide them
+into logical groups. Specification methods are grouped within subclasses of
+Context. You can define as many contexts as you wish, and you are encouraged to
+divide your software into many well-defined contexts.
+
+The following Context is a complete specification for the movement of the robot,
+and if it were run, would produce useful output.
+
+    require 'spec'
+    class RobotMovement < Spec::Context
+      def setup
+        @rob = Robot.new
+        @rob1 = Robot.new(10, 15)
+      end
+
+      def movement
+        @rob.move_north(1).should_equal [0, 1]
+        @rob1.move_west(15).should_equal [-5, 5]
+      end
+
+      def teardown
+        @rob.die
+        @rob1.die
+      end
+    end
+
+=== Specification Naming
+
+RSpec does not require the use of a specific naming scheme for specifications.
+When a context is run, all of the public methods which you define in the context
+will be executed. The only exceptions are currently methods which are used
+internally by RSpec. The forbidden names are initialize, mock, violated, and
+run. Because of Ruby's dynamic nature, you will not see a warning if you
+override any of these methods, and unexpected behaviour may ensue.
+
+In addition to the four aforementioned forbidden specification method names,
+methods named with a leading underscore will also not be run as specifications.
+This allows you a way to define methods for your own use within the Context and
+not have them run as specifications.
+
+== Running and Reporting
+
+There currently exists a command-line runner for RSpec, called 'spec'. If you
+write specifications and pass them to the runner on the command line, your
+specifications will run and tell you where you have errors. You are encouraged
+to try out the command line runner, first with the provided examples, and then
+by writing your own specifications.
+
+As an example of the output, if you run the movie_spec.rb file from the RSpec
+examples, you will get the following output:
+
+    $ spec movie_spec.rb
+    ....
+    Finished in 0.016 seconds.
+    
+    4 specifications, 4 expectations, 0 failures.
+
+The spec runner counts the specification as it executes them by printing a
+single dot (.) to the screen. It indicates a failure with an X. For every
+failure, the specification runner will provide a backtrace indicating where the
+failure occured. A failure is basically a raised exception. Either an exception
+raised by the software you're specifying, by Ruby itself (such as SyntaxError or
+RuntimeError), or it will be an unmet expectation (ExpectationNotMet).
+
+For instance, if you expect "Space Balls" to be in OneMovieList which actually
+includes "Star Wars", you will get the following error:
+
+    $ spec movie_spec.rb
+    X...
+
+    1)
+    <#<MovieList:0x284c1e0 @movies={"Star Wars"=>#<Movie:0x284c180 @name="Star Wars"
+    >}>> should include <"Space Balls"> (Spec::Exceptions::ExpectationNotMetError)
+    ./movie_spec.rb:34:in `should_include_space_balls'
+    ../bin/spec:10
+
+    Finished in 0.016 seconds
+
+    4 specifications, 4 expectations, 1 failures
+
+This informs you that the MovieList object should include "Space Balls", but got
+an ExpectationNotMet error. The backtrace also informs you that the unmet
+expectation can be found in the file 'movie_spec.rb' on line 34, in the
+`should_include_space_balls' method.
+
+== Conclusion
+
+This document was by no means intended to provide an exhaustive overview of
+Behaviour Driven Development in general, or RSpec specifically. It is intended
+as a tutorial to get you started with specifying the behaviour of your software
+with RSpec. More information can be found in the API documentation of RSpec
+itself. Further documentation on BDD, and RSpec is on the way.
+

data/examples/craps_spec.rb

@@ -1,5 +1,5 @@
 require 'spec'
-require 'craps'
+require File.dirname(__FILE__) + '/craps'
 
 class CrapsSpecification < Spec::Context
 
@@ -94,7 +94,7 @@ class CrapsSpecification < Spec::Context
   end
   
   def _load_die(die, rolls)
-    rolls.each {| each | die.__expects(:roll).once.with_no_args.returns(each) }
+    rolls.each { |roll| die.should_receive(:roll).once.with_no_args.and_return(roll) }
   end
   
 end

data/lib/spec/text_runner.rb

@@ -56,7 +56,7 @@ module Spec
     end
 
     def dump_backtrace(trace)
-      lines = trace.reject {|line| line.include? "lib/spec"}
+      lines = trace.reject {|line| line.include? "lib/spec"}.reject {|line | line.include? "./spec:"}
       @output << lines.join("\n")
       @output << "\n\n"
     end

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.8.11
+rubygems_version: 0.8.10
 specification_version: 1
 name: rspec
 version: !ruby/object:Gem::Version 
-  version: 0.1.7
-date: 2005-08-30 00:00:00 -04:00
+  version: 0.2.0
+date: 2005-09-27
 summary: Behaviour Specification Framework for Ruby
 require_paths: 
   - lib
@@ -27,8 +27,6 @@ required_ruby_version: !ruby/object:Gem::Version::Requirement
         version: 0.0.0
   version: 
 platform: ruby
-signing_key: 
-cert_chain: 
 authors: 
   - Steven Baker
 files: 
@@ -37,6 +35,7 @@ files:
   - Rakefile.rb
   - README
   - TODO
+  - TUTORIAL
   - lib/spec.rb
   - lib/spec/collector.rb
   - lib/spec/context.rb
@@ -46,18 +45,12 @@ files:
   - lib/spec/text_runner.rb
   - test/context_fixtures_test.rb
   - test/context_run_test.rb
-  - test/craps_collector_test.rb
   - test/error_reporting_test.rb
   - test/expectations_test.rb
   - test/get_classes.rb
   - test/mock_test.rb
-  - test/movie_collector_test.rb
-  - test/rspec_craps_and_movie_test.rb
-  - test/rspec_craps_test.rb
-  - test/rspec_movie_test.rb
   - test/spec_collection_test.rb
   - test/specification_identification_test.rb
-  - test/test_unit_ext_spec.rb
   - test/text_runner_test.rb
   - examples/craps.rb
   - examples/craps_spec.rb

data/test/craps_collector_test.rb

@@ -1,17 +0,0 @@
-require 'test/unit'
-
-require 'spec'
-
-
-class CrapsCollectorTest < Test::Unit::TestCase
-	
-	def setup
-		require 'examples/craps_spec'
-	end
-
-	def test_should_collect_only_craps_specification
-		assert_equal CrapsSpecification.specifications.length, Spec::Collector.collection.length
-	end
-
-end
-

data/test/movie_collector_test.rb

@@ -1,19 +0,0 @@
-require 'test/unit'
-
-require 'spec'
-
-
-class MovieCollectorTest < Test::Unit::TestCase
-
-	def setup
-		require 'examples/movie_spec'
-	end
-
-	def test_should_collect_only_movie_specs
-		specifications = EmptyMovieList.specifications.length 
-		specifications += OneMovieList.specifications.length
-		assert_equal specifications, Spec::Collector.collection.length
-	end
-
-end
-

data/test/rspec_craps_and_movie_test.rb

@@ -1,32 +0,0 @@
-require 'test/unit'
-
-require 'rspec'
-require 'get_classes'
-
-class RSpecCrapsAndMovieTest < Test::Unit::TestCase
-
-	def setup
-    @rspec = RSpec.new(["examples/craps_spec.rb", "examples/movie_spec.rb"])
-	end
-
-  def test_should_load_craps_and_movie_specs
-    assert_equal true, get_classes.include?('CrapsSpecification')
-    assert_equal true, get_classes.include?('EmptyMovieList')
-    assert_equal true, get_classes.include?('OneMovieList')
-  end
-
-	def test_should_include_all_specifications
-		specifications = CrapsSpecification.collection.length
-		specifications += EmptyMovieList.collection.length
-		specifications += OneMovieList.collection.length
-		assert_equal specifications, Spec::Collector.collection.length
-	end
-
-	def test_should_run_all_specifications
-		buffer = ""
-		@rspec.run(Spec::TextRunner.new(buffer))
-		assert_equal true, buffer.include?("16 specifications, 16 expectations, 0 failures")
-	end
-
-end
-

data/test/rspec_craps_test.rb

@@ -1,35 +0,0 @@
-require 'test/unit'
-
-require 'spec'
-
-require 'rspec'
-
-require 'get_classes'
-
-class RSpecCrapsTest < Test::Unit::TestCase
-
-	def setup
-		@rspec = RSpec.new(["examples/craps_spec.rb"])
-	end
-
-  def test_should_load_craps_spec  
-    assert_equal true, get_classes.include?('CrapsSpecification')
-	end
-	
-	def test_should_not_load_movie_specs
-		assert_equal false, get_classes.include?('OneMovieList')
-		assert_equal false, get_classes.include?('EmptyMovieList')
-  end
-
-	def test_should_include_craps_specifications
-		assert_equal CrapsSpecification.collection.length, Spec::Collector.collection.length
-	end
-
-	def test_should_run_craps_specifications
-		buffer = ""
-		@rspec.run(Spec::TextRunner.new(buffer))
-		assert_equal true, buffer.include?("12 specifications, 12 expectations, 0 failures")
-	end
-
-end
-

data/test/rspec_movie_test.rb

@@ -1,33 +0,0 @@
-require 'test/unit'
-
-require 'rspec'
-require 'get_classes'
-
-class RSpecMovieTest < Test::Unit::TestCase
-
-	def setup
-    @rspec = RSpec.new(["examples/movie_spec.rb"])
-	end
-
-  def test_should_load_movie_spec
-    assert_equal true, get_classes.include?('EmptyMovieList')
-    assert_equal true, get_classes.include?('OneMovieList')
-  end
-
-	def test_should_not_load_craps_spec
-		assert_equal false, get_classes.include?('CrapsSpecification')
-	end
-
-	def test_should_include_movie_specifications
-		specifications = EmptyMovieList.collection.length + OneMovieList.collection.length
-		assert_equal specifications, Spec::Collector.collection.length
-	end
-
-	def test_should_run_movie_specifications
-		buffer = ""
-		@rspec.run(Spec::TextRunner.new(buffer))
-		assert_equal true, buffer.include?("4 specifications, 4 expectations, 0 failures")
-	end
-
-end
-

data/test/test_unit_ext_spec.rb

@@ -1,9 +0,0 @@
-require 'spec'
-
-module Foo
-  class BarSpec < Spec::Context
-    def should_fail
-      raise "ERRORRRR"
-    end
-  end
-end