Add --only-pending CLI option

features/command_line/only_failures.feature

@@ -110,4 +110,4 @@ Feature: Using the `--only-failures` option
  Scenario: Clear error given when using `--only-failures` without configuring `example_status_persistence_file_path`
  Given I have not configured `example_status_persistence_file_path`
  When I run `rspec --only-failures`
- Then it should fail with "To use `--only-failures`, you must first set `config.example_status_persistence_file_path`."
+ Then it should fail with "To use `--only-failures` or `--only-pending`, you must first set `config.example_status_persistence_file_path`."

features/command_line/only_pending.feature

@@ -0,0 +1,94 @@
+Feature: Using the `--only-pending` option
+
+ The `--only-pending` option filters what examples are run so that only those that failed the last time they ran are executed. To use this option, you first have to configure `config.example_status_persistence_file_path`, which RSpec will use to store the status of each example the last time it ran.
+
+ Either of these options can be combined with another a directory or file name; RSpec will run just the failures from the set of loaded examples.
+
+ Background:
+ Given a file named "spec/spec_helper.rb" with:
+ """ruby
+ RSpec.configure do |c|
+ c.example_status_persistence_file_path = "examples.txt"
+ end
+ """
+ And a file named ".rspec" with:
+ """
+ --require spec_helper
+ --order random
+ --format documentation
+ """
+ And a file named "spec/array_spec.rb" with:
+ """ruby
+ RSpec.describe 'Array' do
+ it "checks for inclusion of 1" do
+ expect([1, 2]).to include(1)
+ end
+
+ it "checks for inclusion of 2", skip: "just not ready for this yet..." do
+ expect([1, 2]).to include(2)
+ end
+
+ it "checks for inclusion of 3" do
+ expect([1, 2]).to include(3) # failure
+ end
+ end
+ """
+ And a file named "spec/string_spec.rb" with:
+ """ruby
+ RSpec.describe 'String' do
+ it "checks for inclusion of 'foo'" do
+ expect("food").to include('foo')
+ end
+
+ it "checks for inclusion of 'bar'" do
+ expect("food").to include('bar') # failure
+ end
+
+ it "checks for inclusion of 'baz'" do
+ expect("bazzy").to include('baz')
+ end
+
+ it "checks for inclusion of 'foobar'" do
+ expect("food").to include('foobar') # failure
+ end
+
+ it "checks for inclusion of 'sum'", skip: "just not ready for this yet..." do
+ expect("lorem ipsum").to include('sum')
+ end
+
+ it "checks for inclusion of 'sit'", skip: "...nor am I ready for this..." do
+ expect("dolor sit").to include('sit')
+ end
+ end
+ """
+ And a file named "spec/passing_spec.rb" with:
+ """ruby
+ puts "Loading passing_spec.rb"
+
+ RSpec.describe "A passing spec" do
+ it "passes" do
+ expect(1).to eq(1)
+ end
+ end
+ """
+ And I have run `rspec` once, resulting in "10 examples, 3 failures, 3 pending"
+
+ Scenario: Running `rspec --only-pending` loads only spec files with failures and runs only the failures
+ When I run `rspec --only-pending`
+ Then the output from "rspec --only-pending" should contain "3 examples, 0 failures, 3 pending"
+ And the output from "rspec --only-pending" should not contain "Loading passing_spec.rb"
+
+ Scenario: Combine `--only-pending` with a file name
+ When I run `rspec spec/array_spec.rb --only-pending`
+ Then the output should contain "1 example, 0 failures, 1 pending"
+ When I run `rspec spec/string_spec.rb --only-pending`
+ Then the output should contain "2 examples, 0 failures, 2 pending"
+
+ Scenario: Running `rspec --only-pending` with spec files that pass doesn't run anything
+ When I run `rspec spec/passing_spec.rb --only-pending`
+ Then it should pass with "0 examples, 0 failures"
+
+ Scenario: Clear error given when using `--only-pending` without configuring `example_status_persistence_file_path`
+ Given I have not configured `example_status_persistence_file_path`
+ When I run `rspec --only-pending`
+ Then it should fail with "To use `--only-failures` or `--only-pending`, you must first set `config.example_status_persistence_file_path`."

lib/rspec/core/configuration.rb

@@ -179,7 +179,7 @@ def deprecation_stream=(value)
 
  # @macro define_reader
  # The file path to use for persisting example statuses. Necessary for the
- # `--only-failures` and `--next-failure` CLI options.
+ # `--only-failures`, `--only-pending`, and `--next-failure` CLI options.
  #
  # @overload example_status_persistence_file_path
  # @return [String] the file path
@@ -188,7 +188,7 @@ def deprecation_stream=(value)
  define_reader :example_status_persistence_file_path
 
  # Sets the file path to use for persisting example statuses. Necessary for the
- # `--only-failures` and `--next-failure` CLI options.
+ # `--only-failures`, `--only-pending`, and `--next-failure` CLI options.
  def example_status_persistence_file_path=(value)
  @example_status_persistence_file_path = value
  clear_values_derived_from_example_status_persistence_file_path
@@ -199,9 +199,24 @@ def example_status_persistence_file_path=(value)
  define_reader :only_failures
  alias_method :only_failures?, :only_failures
 
+ # @macro define_reader
+ # Indicates if the `--only-pending` flag is being used.
+ define_reader :only_pending
+ alias_method :only_pending?, :only_pending
+
+ # @private
+ def only_flag_set?
+ only_failures? || only_pending?
+ end
+
  # @private
- def only_failures_but_not_configured?
- only_failures? && !example_status_persistence_file_path
+ def multiple_only_flags?
+ only_failures && only_pending?
+ end
+
+ # @private
+ def only_flag_but_not_configured?
+ only_flag_set? && !example_status_persistence_file_path
  end
 
  # @macro define_reader
@@ -1143,6 +1158,14 @@ def spec_files_with_failures
  end.to_a
  end
 
+ # @private
+ def spec_files_with_pending
+ @spec_files_with_pending ||= last_run_statuses.inject(Set.new) do |files, (id, status)|
+ files << Example.parse_id(id).first if status == PENDING_STATUS
+ files
+ end.to_a
+ end
+
  # Creates a method that delegates to `example` including the submitted
  # `args`. Used internally to add variants of `example` like `pending`:
  # @param name [String] example name alias
@@ -2196,15 +2219,27 @@ def run_suite_hooks(hook_description, hooks)
  end
  end
 
- def get_files_to_run(paths)
- files = FlatMap.flat_map(paths_to_check(paths)) do |path|
+ def get_files(paths)
+ FlatMap.flat_map(paths_to_check(paths)) do |path|
  path = path.gsub(File::ALT_SEPARATOR, File::SEPARATOR) if File::ALT_SEPARATOR
  File.directory?(path) ? gather_directories(path) : extract_location(path)
  end.uniq
+ end
+
+ def get_files_to_run(paths)
+ files = get_files(paths)
+ return files unless only_flag_set?
 
- return files unless only_failures?
  relative_files = files.map { |f| Metadata.relative_path(File.expand_path f) }
- intersection = (relative_files & spec_files_with_failures.to_a)
+
+ # If both are set, #fail_if_config_and_cli_options_invalid should have caught it.
+ case [only_failures?, only_pending?]
+ in [true, _]
+ intersection = (relative_files & spec_files_with_failures.to_a)
+ in [_, true]
+ intersection = (relative_files & spec_files_with_pending.to_a)
+ end
+
  intersection.empty? ? files : intersection
  end
 
@@ -2339,6 +2374,7 @@ def update_pattern_attr(name, value)
  def clear_values_derived_from_example_status_persistence_file_path
  @last_run_statuses = nil
  @spec_files_with_failures = nil
+ @spec_files_with_pending = nil
  end
 
  def configure_group_with(group, module_list, application_method)

lib/rspec/core/configuration_options.rb

@@ -89,7 +89,7 @@ def order(keys)
 
  # `files_or_directories_to_run` uses `default_path` so it must be
  # set before it.
- :default_path, :only_failures,
+ :default_path, :only_failures, :only_pending,
 
  # These must be set before `requires` to support checking
  # `config.files_to_run` from within `spec_helper.rb` when a

lib/rspec/core/option_parser.rb

@@ -217,6 +217,10 @@ def parser(options)
  options[:order] ||= 'defined'
  end
 
+ parser.on('--only-pending', "Filter to just the examples that were pending the last time they ran.") do
+ configure_only_pending(options)
+ end
+
  parser.on('-P', '--pattern PATTERN', 'Load files matching pattern (default: "spec/**/*_spec.rb").') do |o|
  if options[:pattern]
  options[:pattern] += ',' + o
@@ -319,5 +323,10 @@ def configure_only_failures(options)
  options[:only_failures] = true
  add_tag_filter(options, :inclusion_filter, :last_run_status, 'failed')
  end
+
+ def configure_only_pending(options)
+ options[:only_pending] = true
+ add_tag_filter(options, :inclusion_filter, :last_run_status, 'pending')
+ end
  end
 end

lib/rspec/core/project_initializer/spec/spec_helper.rb

@@ -55,8 +55,8 @@
  config.filter_run_when_matching :focus
 
  # Allows RSpec to persist some state between runs in order to support
- # the `--only-failures` and `--next-failure` CLI options. We recommend
- # you configure your source control system to ignore this file.
+ # the `--only-failures`, `--only-pending`, and `--next-failure` CLI options.
+ # We recommend you configure your source control system to ignore this file.
  config.example_status_persistence_file_path = "spec/examples.txt"
 
  # Limits the available syntax to the non-monkey patched syntax that is

lib/rspec/core/world.rb

@@ -183,7 +183,7 @@ def announce_filters
  end
  end
 
- if @configuration.run_all_when_everything_filtered? && example_count.zero? && !@configuration.only_failures?
+ if @configuration.run_all_when_everything_filtered? && example_count.zero? && !@configuration.only_flag_set?
  report_filter_message("#{everything_filtered_message}; ignoring #{inclusion_filter.description}")
  filtered_examples.clear
  inclusion_filter.clear
@@ -250,13 +250,21 @@ def descending_declaration_line_numbers_by_file
  end
 
  def fail_if_config_and_cli_options_invalid
- return unless @configuration.only_failures_but_not_configured?
+ if @configuration.only_flag_but_not_configured?
+ reporter.abort_with(
+ "\nTo use `--only-failures` or `--only-pending`, you must first set " \
+ "`config.example_status_persistence_file_path`.",
+ 1 # exit code
+ )
+ end
 
- reporter.abort_with(
- "\nTo use `--only-failures`, you must first set " \
- "`config.example_status_persistence_file_path`.",
- 1 # exit code
- )
+ if @configuration.multiple_only_flags?
+ reporter.abort_with(
+ "\nYou cannot use `--only-failures` and `--only-pending` together. " \
+ "Please set one or the other.",
+ 1 # exit code
+ )
+ end
  end
 
  # @private