rspec-core 2.8.0.rc1 → 2.8.0.rc2

data/License.txt

@@ -0,0 +1,24 @@
+(The MIT License)
+
+Copyright (c) 2009 Chad Humphries, David Chelimsky
+Copyright (c) 2006 David Chelimsky, The RSpec Development Team
+Copyright (c) 2005 Steven Baker
+
+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.

data/README.md

@@ -1,67 +1,227 @@
 # rspec-core
 
-rspec-core provides the structure for writing executable examples of how your
-code should behave.
-
-## Install
-
-    gem install rspec      # for rspec-core, rspec-expectations, rspec-mocks
-    gem install rspec-core # for rspec-core only
+```
+gem install rspec      # for rspec-core, rspec-expectations, rspec-mocks
+gem install rspec-core # for rspec-core only
+```
+
+# overview
+
+rspec-core provides the structure for writing executable examples of how
+your code should behave.  It uses the words "describe" and "it" so we can
+express concepts like a conversation:
+
+    "Describe an order."
+    "It sums the prices of its line items."
+
+## basic structure
+
+```ruby
+describe Order do
+  it "sums the prices of its line items" do
+    order = Order.new
+    order.add_entry(LineItem.new(:item => Item.new(
+      :price => Money.new(1.11, :USD)
+    )))
+    order.add_entry(LineItem.new(:item => Item.new(
+      :price => Money.new(2.22, :USD),
+      :quantity => 2
+    )))
+    order.total.should eq(Money.new(5.55, :USD))
+  end
+end
+```
+
+The `describe` method creates an [ExampleGroup](../RSpec/Core/ExampleGroup).  Within the
+block passed to `describe` you can declare examples using the `it` method.
+
+Under the hood, an example group is a class in which the block passed to
+`describe` is evaluated. The blocks passed to `it` are evaluated in the
+context of an _instance_ of that class.
+
+## nested groups
+
+You can also declare nested nested groups using the `describe` or `context`
+methods:
+
+```ruby
+describe Order do
+  context "with no items" do
+    it "behaves one way" do
+      # ...
+    end
+  end
 
-## Upgrading from rspec-1.x
+  context "with one item" do
+    it "behaves another way" do
+      # ...
+    end
+  end
+end
+```
+
+## aliases
+
+You can declare example groups using either `describe` or `context`, though
+only `describe` is available at the top level.
+
+You can declare examples within a group using any of `it`, `specify`, or
+`example`.
+
+## shared examples and contexts
+
+Declare a shared example group using `shared_examples`, and then include it
+in any group using `include_examples`.
+
+```ruby
+shared_examples "collections" do |collection_class|
+  it "is empty when first created" do
+    collection_class.new.should be_empty
+  end
+end
+
+describe Array do
+  include_examples "collections", Array
+end
+
+describe Hash do
+  include_examples "collections", Hash
+end
+```
+
+Nearly anything that can be declared within an example group can be declared
+within a shared example group. This includes `before`, `after`, and `around`
+hooks, `let` declarations, and nested groups/contexts.
+
+You can also use the names `shared_context` and `include_context`. These are
+pretty much the same as `shared_examples` and `include_examples`, providing
+more accurate naming for in which you share hooks, `let` declarations, helper
+methods, etc, but no examples.
+
+## metadata
+
+rspec-core stores a metadata hash with every example and group, which
+contains like their descriptions, the locations at which they were
+declared, etc, etc. This hash powers many of rspec-core's features,
+including output formatters (which access descriptions and locations),
+and filtering before and after hooks.
+
+Although you probably won't ever need this unless you are writing an
+extension, you can access it from an example like this:
+
+```ruby
+it "does something" do
+  example.metadata[:description].should eq("does something")
+end
+```
+
+### `described_class`
+
+When a class is passed to `describe`, you can access it from an example
+using the `described_class` method, which is a wrapper for
+`example.metadata[:described_class]`.
+
+```ruby
+describe Widget do
+  example do
+    described_class.should equal(Widget)
+  end
+end
+```
+
+This is useful in extensions or shared example groups in which the specific
+class is unknown. Taking the shared examples example from above, we can
+clean it up a bit using `described_class`:
+
+```ruby
+shared_examples "collections" do
+  it "is empty when first created" do
+    described.new.should be_empty
+  end
+end
+
+describe Array do
+  include_examples "collections"
+end
+
+describe Hash do
+  include_examples "collections"
+end
+```
+
+## the `rspec` command
+
+When you install the rspec-core gem, it installs the `rspec` executable,
+which you'll use to run rspec. The `rspec` comes with many useful options.
+Run `rspec --help` to see the complete list.
+## see also
 
-See [features/Upgrade.md](http://github.com/rspec/rspec-core/blob/master/features/Upgrade.md)
+* [http://github.com/rspec/rspec](http://github.com/rspec/rspec)
+* [http://github.com/rspec/rspec-expectations](http://github.com/rspec/rspec-expectations)
+* [http://github.com/rspec/rspec-mocks](http://github.com/rspec/rspec-mocks)
 
-## Get Started
+## get started
 
 Start with a simple example of behavior you expect from your system. Do
 this before you write any implementation code:
 
-    # in spec/calculator_spec.rb
-    describe Calculator do
-      it "add(x,y) returns the sum of its arguments" do
-        Calculator.new.add(1, 2).should eq(3)
-      end
-    end
+```ruby
+# in spec/calculator_spec.rb
+describe Calculator do
+  it "add(x,y) returns the sum of its arguments" do
+    Calculator.new.add(1, 2).should eq(3)
+  end
+end
+```
 
 Run this with the rspec command, and watch it fail:
 
-    $ rspec spec/calculator_spec.rb
-    ./spec/calculator_spec.rb:1: uninitialized constant Calculator
+```
+$ rspec spec/calculator_spec.rb
+./spec/calculator_spec.rb:1: uninitialized constant Calculator
+```
 
 Implement the simplest solution:
 
-    # in lib/calculator.rb
-    class Calculator
-      def add(a,b)
-        a + b
-      end
-    end
+```ruby
+# in lib/calculator.rb
+class Calculator
+  def add(a,b)
+    a + b
+  end
+end
+```
 
 Be sure to require the implementation file in the spec:
 
-    # in spec/calculator_spec.rb
-    # - RSpec adds ./lib to the $LOAD_PATH
-    require "calculator"
+```ruby
+# in spec/calculator_spec.rb
+# - RSpec adds ./lib to the $LOAD_PATH
+require "calculator"
+```
 
 Now run the spec again, and watch it pass:
 
-    $ rspec spec/calculator_spec.rb
-    .
+```
+$ rspec spec/calculator_spec.rb
+.
 
-    Finished in 0.000315 seconds
-    1 example, 0 failures
+Finished in 0.000315 seconds
+1 example, 0 failures
+```
 
 Use the `documentation` formatter to see the resulting spec:
 
-    $ rspec spec/calculator_spec.rb --format doc
-    Calculator add
-      returns the sum of its arguments
+```
+$ rspec spec/calculator_spec.rb --format doc
+Calculator add
+  returns the sum of its arguments
 
-    Finished in 0.000379 seconds
-    1 example, 0 failures
+Finished in 0.000379 seconds
+1 example, 0 failures
+```
 
-## See also
+## Also see
 
 * [http://github.com/rspec/rspec](http://github.com/rspec/rspec)
 * [http://github.com/rspec/rspec-expectations](http://github.com/rspec/rspec-expectations)

data/features/command_line/format_option.feature

@@ -56,7 +56,7 @@ Feature: --format option
       something
         does something that passes
         does something that fails (FAILED - 1)
-        does something that is pending (PENDING: Not Yet Implemented)
+        does something that is pending (PENDING: No reason given)
       """
 
   Scenario: documentation format saved to a file
@@ -66,7 +66,7 @@ Feature: --format option
       something
         does something that passes
         does something that fails (FAILED - 1)
-        does something that is pending (PENDING: Not Yet Implemented)
+        does something that is pending (PENDING: No reason given)
       """
 
   Scenario: multiple formats
@@ -77,5 +77,5 @@ Feature: --format option
       something
         does something that passes
         does something that fails (FAILED - 1)
-        does something that is pending (PENDING: Not Yet Implemented)
+        does something that is pending (PENDING: No reason given)
       """

data/features/command_line/init.feature

@@ -0,0 +1,18 @@
+Feature: --init option
+
+  Use the --init option on the command line to generate conventional
+  files for an rspec project.
+
+  Scenario: generate .rspec
+    When I run `rspec --init`
+    Then the following files should exist:
+      | .rspec |
+    And the output should contain "create   .rspec"
+
+  Scenario: .rspec file already exists
+    Given a file named ".rspec" with:
+      """
+      --color
+      """
+    When I run `rspec --init`
+    Then the output should contain "exist   .rspec"

data/features/example_groups/shared_examples.feature

@@ -27,7 +27,7 @@ Feature: shared examples
   2.  Put files containing shared examples in `spec/support/` and require files
       in that directory from `spec/spec_helper.rb`:
 
-          Dir["spec/support/**/*.rb"].each {|f| require f}
+          Dir["./spec/support/**/*.rb"].each {|f| require f}
 
       This is included in the generated `spec/spec_helper.rb` file in
       `rspec-rails`

data/features/hooks/around_hooks.feature

@@ -199,7 +199,7 @@ Feature: around hooks
     When I run `rspec example_spec.rb`
     Then the output should contain "1 example, 0 failure"
 
-  Scenario: implicitly pending examples are detected as Not Yet Implemented
+  Scenario: implicitly pending examples are detected as Not yet implemented
     Given a file named "example_spec.rb" with:
       """
       describe "implicit pending example" do
@@ -207,7 +207,7 @@ Feature: around hooks
           example.run
         end
 
-        it "should be detected as Not Yet Implemented"
+        it "should be detected as Not yet implemented"
       end
       """
     When I run `rspec example_spec.rb`
@@ -215,8 +215,8 @@ Feature: around hooks
     And the output should contain:
       """
       Pending:
-        implicit pending example should be detected as Not Yet Implemented
-          # Not Yet Implemented
+        implicit pending example should be detected as Not yet implemented
+          # Not yet implemented
       """
 
 

data/features/pending/pending_examples.feature

@@ -13,7 +13,7 @@ Feature: pending examples
     When I run `rspec example_without_block_spec.rb`
     Then the exit status should be 0
     And the output should contain "1 example, 0 failures, 1 pending"
-    And the output should contain "Not Yet Implemented"
+    And the output should contain "Not yet implemented"
     And the output should contain "example_without_block_spec.rb:2"
 
   Scenario: pending any arbitary reason, with no block
@@ -98,13 +98,13 @@ Feature: pending examples
       """
       Pending:
         an example is pending using xit
-          # Not Yet Implemented
+          # Temporarily disabled with xit
           # ./temporarily_pending_spec.rb:2
         an example is pending using xspecify
-          # Not Yet Implemented
+          # Temporarily disabled with xspecify
           # ./temporarily_pending_spec.rb:5
         an example is pending using xexample
-          # Not Yet Implemented
+          # Temporarily disabled with xexample
           # ./temporarily_pending_spec.rb:8
       """
 
@@ -149,7 +149,7 @@ Feature: pending examples
       """
       an example
         checks something
-         (PENDING: Not Yet Implemented)
+         (PENDING: No reason given)
       """
 
   Scenario: conditionally pending examples

data/features/support/env.rb

@@ -1,5 +1,12 @@
 require 'aruba/cucumber'
 
 Before do
-  RUBY_PLATFORM =~ /java/ ? @aruba_timeout_seconds = 60 : @aruba_timeout_seconds = 5
+  if RUBY_PLATFORM =~ /java/
+    # ideas taken from: http://blog.headius.com/2010/03/jruby-startup-time-tips.html
+    set_env('JRUBY_OPTS', '-X-C') # disable JIT since these processes are so short lived
+    set_env('JAVA_OPTS', '-d32') # force jRuby to use client JVM for faster startup times
+    @aruba_timeout_seconds = 60
+  else
+    @aruba_timeout_seconds = 5
+  end
 end

data/lib/autotest/rspec2.rb

@@ -1,8 +1,6 @@
 require 'autotest'
 require 'rspec/core/deprecation'
 
-class RSpecCommandError < StandardError; end
-
 class Autotest::Rspec2 < Autotest
 
   RSPEC_EXECUTABLE = File.expand_path('../../../exe/rspec', __FILE__)
@@ -55,19 +53,17 @@ class Autotest::Rspec2 < Autotest
     end
   end
 
-  # @private
+  private
+
   def suffix
     using_bundler? ? "" : defined?(:Gem) ? " -rrubygems" : ""
   end
 
-  # @private
   def using_bundler?
     prefix =~ /bundle exec/
   end
 
-  # @private
   def gemfile?
     File.exist?('./Gemfile')
   end
-
 end