Document config options

features/configuration/drb.feature

@@ -0,0 +1,64 @@
+Feature: drb and drb port
+
+  Using the drb option and the drb_port option, users can run examples over DRb and set the port for that server.
+
+  Scenario: DRb is off by default
+    Given a file named "spec/example_spec.rb" with:
+      """ruby
+      describe "DRb status" do
+        it "is false" do
+          RSpec.configuration.drb?.should be_false
+        end
+      end
+      """
+    When I run `rspec spec/example_spec.rb`
+    Then the examples should all pass
+
+  Scenario: when DRb is turned on
+    Given a file named "spec/example_spec.rb" with:
+      """ruby
+      RSpec.configure do |c|
+         c.drb = true
+      end
+
+      describe "DRb status" do
+        it "is true" do
+          RSpec.configuration.drb?.should be_true
+        end
+      end
+      """
+    When I run `rspec spec/example_spec.rb`
+    Then the examples should all pass
+
+  Scenario: the default DRb port
+    Given a file named "spec/example_spec.rb" with:
+      """ruby
+      RSpec.configure do |c|
+         c.drb = true
+      end
+
+      describe "DRb port" do
+        it "is not set (is nil) by default" do
+          RSpec.configuration.drb_port.should be_nil
+        end
+      end
+      """
+    When I run `rspec spec/example_spec.rb`
+    Then the examples should all pass
+
+  Scenario: setting the DRb port
+    Given a file named "spec/example_spec.rb" with:
+      """ruby
+      RSpec.configure do |c|
+         c.drb = true
+         c.drb_port = 42
+      end
+
+      describe "DRb port" do
+        it "is what I set it to" do
+          RSpec.configuration.drb_port.should == 42
+        end
+      end
+      """
+    When I run `rspec spec/example_spec.rb`
+    Then the examples should all pass

features/configuration/failure_exit_code.feature

@@ -0,0 +1,36 @@
+Feature: failure exit code
+
+  Use the feature_exit_code option to set a custom exit code when RSpec fails.
+
+    RSpec.configure { |c| c.failure_exit_code = 42 }
+
+  Background:
+    Given a file named "spec/spec_helper.rb" with:
+      """ruby
+      RSpec.configure { |c| c.failure_exit_code = 42 }
+      """
+
+  Scenario: a failing spec with the default exit code
+    Given a file named "spec/example_spec.rb" with:
+      """ruby
+      describe "something" do
+        it "fails" do
+          fail
+        end
+      end
+      """
+    When I run `rspec spec/example_spec.rb`
+    Then the exit status should be 1
+
+  Scenario: a failing spec with a custom exit code
+    Given a file named "spec/example_spec.rb" with:
+      """ruby
+      require 'spec_helper'
+      describe "something" do
+        it "fails" do
+          fail
+        end
+      end
+      """
+    When I run `rspec spec/example_spec.rb`
+    Then the exit status should be 42

features/configuration/order_and_seed.feature

@@ -0,0 +1,3 @@
+Feature: set the order and/or seed
+
+  You can set the order to run specs and specify a seed if you are running the specs using the 'random' ordering.  See <a href='../command_line/order.feature'>the documentation on the --order command line option</a> for more on this.

features/configuration/output_stream.feature

@@ -0,0 +1,24 @@
+Feature: output_stream
+
+  Define a custom output stream (default `$stdout`).  Aliases: `:output`, `:out`.
+
+    RSpec.configure { |c| c.output_stream = File.open('saved_output', 'w') }
+
+  Background:
+    Given a file named "spec/spec_helper.rb" with:
+      """ruby
+      RSpec.configure {|c| c.output_stream = File.open('saved_output', 'w') }
+      """
+
+  Scenario: redirecting output
+    Given a file named "spec/example_spec.rb" with:
+      """ruby
+      require 'spec_helper'
+      describe "an example" do
+        it "passes" do
+          true
+        end
+      end
+      """
+    When I run `rspec spec/example_spec.rb`
+    Then the file "saved_output" should contain "1 example, 0 failures"

features/configuration/pattern.feature

@@ -0,0 +1,30 @@
+Feature: pattern
+
+  Use the pattern option to tell RSpec to look for specs in files that match a pattern other than "**/*_spec.rb".
+
+  Background:
+    Given a file named "spec/example_spec.rb" with:
+      """ruby
+      describe "two specs here" do
+        it "passes" do
+        end
+
+        it "passes too" do
+        end
+      end
+      """
+    And a file named "spec/example_test.rb" with:
+      """ruby
+      describe "only one spec" do
+        it "passes" do
+        end
+      end
+      """
+
+  Scenario: by default, RSpec runs files that match "**/*_spec.rb"
+   When I run `rspec`
+   Then the output should contain "2 examples, 0 failures"
+
+  Scenario: the --pattern flag makes RSpec run files matching the specified pattern and ignore the default pattern
+   When I run `rspec -P "**/*_test.rb"`
+   Then the output should contain "1 example, 0 failures"

features/configuration/profile_examples.feature

@@ -0,0 +1,41 @@
+Feature: profile examples
+
+  Use the profile_examples option to tell RSpec to report the times
+  for the 10 slowest examples.
+
+    RSpec.configure { |c| c.profile_examples = true }
+
+  Background:
+    Given a file named "spec/spec_helper.rb" with:
+      """ruby
+      RSpec.configure { |c| c.profile_examples = true }
+      """
+
+  Scenario: profile_examples defaults to false
+    Given a file named "spec/example_spec.rb" with:
+      """ruby
+      describe "something" do
+        it "passes" do
+        end
+
+        it "also passes" do
+        end
+      end
+      """
+   When I run `rspec spec/example_spec.rb`
+   Then the output should not contain "Top 2 slowest examples"
+
+  Scenario: profile_examples reports on the slowest features
+    Given a file named "spec/example_spec.rb" with:
+      """ruby
+      require 'spec_helper'
+      describe "something" do
+        it "passes" do
+        end
+
+        it "also passes" do
+        end
+      end
+      """
+   When I run `rspec spec/example_spec.rb`
+   Then the output should contain "Top 2 slowest examples"

features/configuration/run_all_when_everything_filtered.feature

@@ -0,0 +1,60 @@
+Feature: run all when everything filtered
+
+  Use the run_all_when_everything_filtered option to tell RSpec to run
+  all the specs in the case where you try to run a filtered list of
+  specs but no specs match that filter.
+
+    RSpec.configure { |c| c.run_all_when_everything_filtered = true }
+
+  Background:
+    Given a file named "spec/spec_helper.rb" with:
+      """ruby
+      RSpec.configure {|c| c.run_all_when_everything_filtered = true}
+      """
+
+  Scenario: by default, no specs are run if they are all filtered out
+    Given a file named "spec/example_spec.rb" with:
+      """ruby
+      describe "examples" do
+        it "with no tag" do
+        end
+
+        it "with no tag as well" do
+        end
+      end
+      """
+    When I run `rspec spec/example_spec.rb --tag some_tag`
+    Then the output should contain "0 examples, 0 failures"
+
+  Scenario: when the run_all_when_everything_filtered option is turned on, if there are any matches for the filtering tag, only those features are run
+    Given a file named "spec/example_spec.rb" with:
+      """ruby
+      require "spec_helper"
+      describe "examples" do
+        it "with no tag", :some_tag => true do
+        end
+
+        it "with no tag as well" do
+        end
+      end
+      """
+    When I run `rspec spec/example_spec.rb --tag some_tag`
+    Then the output should contain "1 example, 0 failures"
+    And the output should contain "Run options: include {:some_tag=>true}"
+
+  Scenario: when the run_all_when_everything_filtered option is turned on, all the specs are run when the tag has no matches
+    Given a file named "spec/example_spec.rb" with:
+      """ruby
+      require "spec_helper"
+      describe "examples" do
+        it "with no tag" do
+        end
+
+        it "with no tag as well" do
+        end
+      end
+      """
+    When I run `rspec spec/example_spec.rb --tag some_tag`
+    Then the output should contain "2 examples, 0 failures"
+    And the output should contain "All examples were filtered out; ignoring {:some_tag=>true}"
+

features/configuration/show_failures_in_pending_blocks.feature

@@ -0,0 +1,61 @@
+Feature: show_failures_in_pending_blocks
+
+  Use the show_failures_in_pending_blocks option to run the code in pending blocks while keeping the tests pending.
+
+    RSpec.configure { |c| c.show_failures_in_pending_blocks = true }
+
+  Background:
+    Given a file named "spec/spec_helper.rb" with:
+      """ruby
+      RSpec.configure {|c| c.show_failures_in_pending_blocks = true}
+      """
+
+  Scenario: by default, code in pending examples is not exercised
+    Given a file named "spec/example_spec.rb" with:
+      """ruby
+      describe "fails" do
+        pending "code will not be exercised" do
+          fail
+        end
+      end
+      """
+    When I run `rspec spec/example_spec.rb`
+    Then the output should not contain "Failure/Error: pending { fail }"
+
+  Scenario: by default, code in pending blocks inside examples is not exercised
+    Given a file named "spec/example_spec.rb" with:
+      """ruby
+      describe "fails" do
+        it "code will not be exercised" do
+          pending { fail }
+        end
+      end
+      """
+    When I run `rspec spec/example_spec.rb`
+    Then the output should not contain "Failure/Error: pending { fail }"
+
+  Scenario: when turned on, pending code blocks inside examples are exercised
+    Given a file named "spec/example_spec.rb" with:
+      """ruby
+      require "spec_helper"
+      describe "fails" do
+        it "code will be exercised" do
+          pending { fail }
+        end
+      end
+      """
+    When I run `rspec spec/example_spec.rb`
+    Then the output should contain "Failure/Error: pending { fail }"
+
+  Scenario: when turned on, code inside pending examples is not exercised
+    Given a file named "spec/example_spec.rb" with:
+      """ruby
+      require "spec_helper"
+      describe "fails" do
+        pending "code will not be exercised" do
+          fail
+        end
+      end
+      """
+    When I run `rspec spec/example_spec.rb`
+    Then the output should not contain "Failure/Error: pending { fail }"

features/configuration/treat_symbols_as_metadata_keys_with_true_values.feature

@@ -0,0 +1,52 @@
+Feature: treat symbols as metadata keys with true values
+
+  Use the treat_symbols_as_metadata_keys_with_true_values option to tell RSpec that :key is shorthand for :key => true.
+
+    RSpec.configure { |c| c.treat_symbols_as_metadata_keys_with_true_values = true }
+
+  Background:
+    Given a file named "spec/spec_helper.rb" with:
+      """ruby
+      RSpec.configure { |c| c.treat_symbols_as_metadata_keys_with_true_values = true }
+      """
+
+  Scenario: by default, symbols without values are ignored and the specs are filtered out
+    Given a file named "spec/example_spec.rb" with:
+      """ruby
+      describe "failed filtering" do
+        it "this will be filted out", :some_tag do
+          true
+        end
+
+        it "so will this" do
+          false
+        end
+      end
+      """
+      When I run `rspec spec/example_spec.rb --tag some_tag`
+      Then the output should contain "0 examples, 0 failures"
+      And the output should contain "All examples were filtered out"
+
+  Scenario: when treat_symbols_as_metadata_keys_with_true_values is true, specs can be tagged with only a symbol
+    Given a file named "spec/example_spec.rb" with:
+      """ruby
+      require "spec_helper"
+      describe "run me", :some_tag do
+        it "runs" do
+          true
+        end
+      end
+
+      describe "run one of these" do
+        it "run this one", :some_tag do
+          true
+        end
+
+        it "but not me" do
+          false
+        end
+      end
+      """
+      When I run `rspec spec/example_spec.rb --tag some_tag`
+      Then the output should contain "2 examples, 0 failures"
+      And the output should contain "Run options: include {:some_tag=>true}"

lib/rspec/core/configuration.rb

@@ -99,7 +99,7 @@ def self.add_setting(name, opts={})
       # server, but you can use tools like spork.
       add_setting :drb
 
-      # The drb_port (default: `8989`).
+      # The drb_port (default: nil).
       add_setting :drb_port
 
       # Default: `$stderr`.