Merge af946d8 into b897913

features/.nav

@@ -12,6 +12,7 @@
   - tag.feature
   - line_number_appended_to_path.feature
   - exit_status.feature
+  - order.md (`--order` option)
   - rake_task.feature
 - pending:
   - pending_examples.feature

features/Upgrade.md

@@ -239,10 +239,10 @@ passed to `it_should_behave_like`.
 
 See [features/example\_groups/shared\_example\_group.feature](http://github.com/rspec/rspec-core/blob/master/features/example_groups/shared_example_group.feature) for more information.
 
-NOTICE: The including example groups no longer have access to any of the
-methods, hooks, or state defined inside a shared group. This will break rspec-1
-specs that were using shared example groups to extend the behavior of including
-groups.
+**NOTICE:** An example group including shared examples no longer has access to
+any of the methods, hooks or state defined inside the shared group. This will
+break rspec-1 specs that were using shared example groups to extend the behavior
+of including groups.
 
 # Upgrading from rspec-1.x
 

features/command_line/README.md

@@ -3,23 +3,26 @@ behavior, including output formats, filtering examples, etc.
 
 For a full list of options, run the `rspec` command with the `--help` flag:
 
-    $ rspec --help
+```ruby
+$ rspec --help
+```
 
 ### Run with `ruby`
 
-Generally, life is simpler if you just use the `rspec` command. If you must use the `ruby`
-command, however, you'll need to require `"rspec/autorun"`. You can
-either pass a `-rrspec/autorun` CLI option when invoking `ruby`, or add
-a `require 'rspec/autorun'` to one or more of your spec files.
+Generally, life is simpler if you just use the `rspec` command. If you must use
+the `ruby` command, however, you'll need to require `rspec/autorun`. You can
+either pass a `-rrspec/autorun` CLI option when invoking `ruby`, or add a
+`require 'rspec/autorun'` to one or more of your spec files.
 
 It is conventional to put configuration in and require assorted support files
 from `spec/spec_helper.rb`. It is also conventional to require that file from
 the spec files using `require 'spec_helper'`. This works because RSpec
 implicitly adds the `spec` directory to the `LOAD_PATH`. It also adds `lib`, so
 your implementation files will be on the `LOAD_PATH` as well.
 
-If you're using the `ruby` command, you'll need to do this yourself
-(with the `-I` option).  Putting these together, your command might be
-something like this:
+If you're using the `ruby` command, you'll need to do this yourself (with the
+`-I` option). Putting these together, your command might be something like this:
 
-    $ ruby -Ilib -Ispec -rrspec/autorun path/to/spec.rb
+```ruby
+$ ruby -Ilib -Ispec -rrspec/autorun path/to/spec.rb
+```

features/command_line/dry_run.feature

@@ -1,17 +1,17 @@
-Feature: --dry-run
+Feature: `--dry-run` option
 
-  Use the `--dry-run` option to have RSpec print your suite's formatter
-  output without running any examples or hooks.
+  Use the `--dry-run` option to have RSpec print your suite's formatter output
+  without running any examples or hooks.
 
-  Scenario: Using --dry-run
+  Scenario: Using `--dry-run`
     Given a file named "spec/dry_run_spec.rb" with:
       """ruby
       RSpec.configure do |c|
         c.before(:suite) { puts "before suite" }
         c.after(:suite)  { puts "after suite"  }
       end
 
-      describe "dry run" do
+      RSpec.describe "dry run" do
         before(:context) { fail }
         before(:example) { fail }
 

features/command_line/example_name_option.feature

@@ -1,34 +1,35 @@
-Feature: --example option
+Feature: `--example` option
 
-  Use the --example (or -e) option to filter examples by name.
+  Use the `--example` (or `-e`) option to filter examples by name.
 
-  The argument is matched against the full description of the example,
-  which is the concatenation of descriptions of the group (including
-  any nested groups) and the example.
+  The argument is matched against the full description of the example, which is
+  the concatenation of descriptions of the group (including any nested groups)
+  and the example.
 
   This allows you to run a single uniquely named example, all examples with
   similar names, all the examples in a uniquely named group, etc, etc.
 
-  You can also use the option more than once to specify multiple example matches.
+  You can also use the option more than once to specify multiple example
+  matches.
 
   Background:
     Given a file named "first_spec.rb" with:
       """ruby
-      describe "first group" do
+      RSpec.describe "first group" do
         it "first example in first group" do; end
         it "second example in first group" do; end
       end
       """
     And a file named "second_spec.rb" with:
       """ruby
-      describe "second group" do
+      RSpec.describe "second group" do
         it "first example in second group" do; end
         it "second example in second group" do; end
       end
       """
     And a file named "third_spec.rb" with:
       """ruby
-      describe "third group" do
+      RSpec.describe "third group" do
         it "first example in third group" do; end
         context "nested group" do
           it "first example in nested group" do; end
@@ -38,7 +39,7 @@ Feature: --example option
       """
     And a file named "fourth_spec.rb" with:
       """ruby
-      describe Array do
+      RSpec.describe Array do
         describe "#length" do
           it "is the number of items" do
             expect(Array.new([1,2,3]).length).to eq 3
@@ -47,39 +48,39 @@ Feature: --example option
       end
       """
 
-  Scenario: no matches
+  Scenario: No matches
     When I run `rspec . --example nothing_like_this`
     Then the process should succeed even though no examples were run
 
-  Scenario: match on one word
+  Scenario: Match on one word
     When I run `rspec . --example example`
     Then the examples should all pass
 
-  Scenario: one match in each context
+  Scenario: One match in each context
     When I run `rspec . --example 'first example'`
     Then the examples should all pass
 
-  Scenario: one match in one file using just the example name
+  Scenario: One match in one file using just the example name
     When I run `rspec . --example 'first example in first group'`
     Then the examples should all pass
 
-  Scenario: one match in one file using the example name and the group name
+  Scenario: One match in one file using the example name and the group name
     When I run `rspec . --example 'first group first example in first group'`
     Then the examples should all pass
 
-  Scenario: all examples in one group
+  Scenario: All examples in one group
     When I run `rspec . --example 'first group'`
     Then the examples should all pass
 
-  Scenario: one match in one file with group name
+  Scenario: One match in one file with group name
     When I run `rspec . --example 'second group first example'`
     Then the examples should all pass
 
-  Scenario: all examples in one group including examples in nested groups
+  Scenario: All examples in one group including examples in nested groups
     When I run `rspec . --example 'third group'`
     Then the examples should all pass
 
-  Scenario: Object#method
+  Scenario: Match using `ClassName#method_name` form
     When I run `rspec . --example 'Array#length'`
     Then the examples should all pass
 

features/command_line/exit_status.feature

@@ -1,13 +1,13 @@
-Feature: exit status
+Feature: `--failure-exit-code` option (exit status)
 
-  The rspec command exits with an exit status of 0 if all examples pass,
-  and 1 if any examples fail. The failure exit code can be overridden
-  using the --failure-exit-code option.
+  The `rspec` command exits with an exit status of 0 if all examples pass, and 1
+  if any examples fail. The failure exit code can be overridden using the
+  `--failure-exit-code` option.
 
-  Scenario: exit with 0 when all examples pass
+  Scenario: Exit with 0 when all examples pass
     Given a file named "ok_spec.rb" with:
       """ruby
-      describe "ok" do
+      RSpec.describe "ok" do
         it "passes" do
         end
       end
@@ -16,10 +16,10 @@ Feature: exit status
     Then the exit status should be 0
     And the examples should all pass
 
-  Scenario: exit with 1 when one example fails
+  Scenario: Exit with 1 when one example fails
     Given a file named "ko_spec.rb" with:
       """ruby
-      describe "KO" do
+      RSpec.describe "KO" do
         it "fails" do
           raise "KO"
         end
@@ -29,10 +29,10 @@ Feature: exit status
     Then the exit status should be 1
     And the output should contain "1 example, 1 failure"
 
-  Scenario: exit with 1 when a nested examples fails
+  Scenario: Exit with 1 when a nested examples fails
     Given a file named "nested_ko_spec.rb" with:
       """ruby
-      describe "KO" do
+      RSpec.describe "KO" do
         describe "nested" do
           it "fails" do
             raise "KO"
@@ -44,18 +44,18 @@ Feature: exit status
     Then the exit status should be 1
     And the output should contain "1 example, 1 failure"
 
-  Scenario: exit with 0 when no examples are run
+  Scenario: Exit with 0 when no examples are run
     Given a file named "a_no_examples_spec.rb" with:
       """ruby
       """
     When I run `rspec a_no_examples_spec.rb`
     Then the exit status should be 0
     And the output should contain "0 examples"
 
-  Scenario: exit with 2 when one example fails and --failure-exit-code is 2
+  Scenario: Exit with 2 when one example fails and `--failure-exit-code` is 2
     Given a file named "ko_spec.rb" with:
       """ruby
-      describe "KO" do
+      RSpec.describe "KO" do
         it "fails" do
           raise "KO"
         end
@@ -65,7 +65,7 @@ Feature: exit status
     Then the exit status should be 2
     And the output should contain "1 example, 1 failure"
 
-  Scenario: exit with rspec's exit code when an at_exit hook is added upstream
+  Scenario: Exit with RSpec's exit code when an `at_exit` hook is added upstream
     Given a file named "exit_at_spec.rb" with:
       """ruby
       require 'rspec/autorun'

features/command_line/fail_fast.feature

@@ -1,13 +1,14 @@
-Feature: --fail-fast
+Feature: `--fail-fast` option
 
-  Use the `--fail-fast` option to tell RSpec to stop running the test suite on the first failed test.
+  Use the `--fail-fast` option to tell RSpec to stop running the test suite on
+  the first failed test.
 
   You may also specify `--no-fail-fast` to turn it off (default behaviour).
 
   Background:
     Given a file named "fail_fast_spec.rb" with:
       """ruby
-      describe "fail fast" do
+      RSpec.describe "fail fast" do
         it "passing test" do; end
         it "failing test" do
           fail
@@ -16,11 +17,11 @@ Feature: --fail-fast
       end
       """
 
-  Scenario: Using --fail-fast
+  Scenario: Using `--fail-fast`
     When I run `rspec . --fail-fast`
     Then the output should contain ".F"
     Then the output should not contain ".F."
 
-  Scenario: Using --no-fail-fast
+  Scenario: Using `--no-fail-fast`
     When I run `rspec . --no-fail-fast`
-    Then the output should contain ".F."
+    Then the output should contain ".F."

features/command_line/format_option.feature

@@ -1,6 +1,6 @@
-Feature: --format option
+Feature: `--format` option
 
-  Use the --format option to tell RSpec how to format the output.
+  Use the `--format` option to tell RSpec how to format the output.
 
   RSpec ships with several formatters built in. By default, it uses the progress
   formatter, which generates output like this:
@@ -12,19 +12,23 @@ Feature: --format option
   Use the documentation formatter to see the documentation strings passed to
   `describe`, `it`, and their aliases:
 
-      $ rspec spec --format documentation
+  ```bash
+  $ rspec spec --format documentation
+  ```
 
-  You can also specify an output target ($stdout by default) with an --out
-  option immediately following the --format option:
+  You can also specify an output target (`$stdout` by default) with an `--out`
+  option immediately following the `--format` option:
 
-      $ rspec spec --format documentation --out rspec.txt
+  ```bash
+  $ rspec spec --format documentation --out rspec.txt
+  ```
 
   Run `rspec --help` to see a listing of available formatters.
 
   Background:
     Given a file named "example_spec.rb" with:
       """ruby
-      describe "something" do
+      RSpec.describe "something" do
         it "does something that passes" do
           expect(5).to eq(5)
         end
@@ -36,40 +40,47 @@ Feature: --format option
         it "does something that is pending", :pending => true do
           expect(5).to be < 3
         end
+
+        it "does something that is skipped", :skip => true do
+          expect(5).to be < 3
+        end
       end
       """
 
-  Scenario: progress bar format (default)
+  Scenario: Progress bar format (default)
     When I run `rspec --format progress example_spec.rb`
-    Then the output should contain ".F*"
+    Then the output should contain ".F**"
 
-  Scenario: documentation format
+  Scenario: Documentation format
     When I run `rspec example_spec.rb --format documentation`
     Then the output should contain:
       """
       something
         does something that passes
         does something that fails (FAILED - 1)
         does something that is pending (PENDING: No reason given)
+        does something that is skipped (PENDING: No reason given)
       """
 
-  Scenario: documentation format saved to a file
+  Scenario: Documentation format saved to a file
     When I run `rspec example_spec.rb --format documentation --out rspec.txt`
     Then the file "rspec.txt" should contain:
       """
       something
         does something that passes
         does something that fails (FAILED - 1)
         does something that is pending (PENDING: No reason given)
+        does something that is skipped (PENDING: No reason given)
       """
 
-  Scenario: multiple formats and output targets
+  Scenario: Multiple formats and output targets
     When I run `rspec example_spec.rb --format progress --format documentation --out rspec.txt`
-    Then the output should contain ".F*"
+    Then the output should contain ".F**"
     And the file "rspec.txt" should contain:
       """
       something
         does something that passes
         does something that fails (FAILED - 1)
         does something that is pending (PENDING: No reason given)
+        does something that is skipped (PENDING: No reason given)
       """