rspec-core 3.0.4 → 3.12.2

data/{License.txt → LICENSE.md}

@@ -1,9 +1,10 @@
-(The MIT License)
+The MIT License (MIT)
+=====================
 
-Copyright (c) 2012 Chad Humphries, David Chelimsky, Myron Marston
-Copyright (c) 2009 Chad Humphries, David Chelimsky
-Copyright (c) 2006 David Chelimsky, The RSpec Development Team
-Copyright (c) 2005 Steven Baker
+* Copyright © 2012 Chad Humphries, David Chelimsky, Myron Marston
+* Copyright © 2009 Chad Humphries, David Chelimsky
+* Copyright © 2006 David Chelimsky, The RSpec Development Team
+* Copyright © 2005 Steven Baker
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,16 +1,25 @@
-# rspec-core [![Build Status](https://secure.travis-ci.org/rspec/rspec-core.png?branch=master)](http://travis-ci.org/rspec/rspec-core) [![Code Climate](https://codeclimate.com/github/rspec/rspec-core.png)](https://codeclimate.com/github/rspec/rspec-core)
+# rspec-core [![Build Status](https://github.com/rspec/rspec-core/workflows/RSpec%20CI/badge.svg)](https://github.com/rspec/rspec-core/actions) [![Code Climate](https://codeclimate.com/github/rspec/rspec-core.svg)](https://codeclimate.com/github/rspec/rspec-core)
 
 rspec-core provides the structure for writing executable examples of how your
 code should behave, and an `rspec` command with tools to constrain which
 examples get run and tailor the output.
 
-## install
+## Install
 
     gem install rspec      # for rspec-core, rspec-expectations, rspec-mocks
     gem install rspec-core # for rspec-core only
     rspec --help
 
-## basic structure
+Want to run against the `main` branch? You'll need to include the dependent
+RSpec repos as well. Add the following to your `Gemfile`:
+
+```ruby
+%w[rspec rspec-core rspec-expectations rspec-mocks rspec-support].each do |lib|
+  gem lib, :git => "https://github.com/rspec/#{lib}.git", :branch => 'main'
+end
+```
+
+## Basic Structure
 
 RSpec uses the words "describe" and "it" so we can express concepts like a conversation:
 
@@ -21,6 +30,7 @@ RSpec uses the words "describe" and "it" so we can express concepts like a conve
 RSpec.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)
     )))
@@ -28,6 +38,7 @@ RSpec.describe Order do
       :price => Money.new(2.22, :USD),
       :quantity => 2
     )))
+
     expect(order.total).to eq(Money.new(5.55, :USD))
   end
 end
@@ -40,9 +51,9 @@ 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
+## Nested Groups
 
-You can also declare nested nested groups using the `describe` or `context`
+You can also declare nested groups using the `describe` or `context`
 methods:
 
 ```ruby
@@ -61,7 +72,10 @@ RSpec.describe Order do
 end
 ```
 
-## aliases
+Nested groups are subclasses of the outer example group class, providing
+the inheritance semantics you'd want for free.
+
+## Aliases
 
 You can declare example groups using either `describe` or `context`.
 For a top level example group, `describe` and `context` are available
@@ -72,7 +86,7 @@ patching.
 You can declare examples within a group using any of `it`, `specify`, or
 `example`.
 
-## shared examples and contexts
+## Shared Examples and Contexts
 
 Declare a shared example group using `shared_examples`, and then include it
 in any group using `include_examples`.
@@ -102,7 +116,7 @@ pretty much the same as `shared_examples` and `include_examples`, providing
 more accurate naming when you share hooks, `let` declarations, helper methods,
 etc, but no examples.
 
-## metadata
+## Metadata
 
 rspec-core stores a metadata hash with every example and group, which
 contains their descriptions, the locations at which they were
@@ -114,7 +128,7 @@ 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
+it "does something" do |example|
   expect(example.metadata[:description]).to eq("does something")
 end
 ```
@@ -153,26 +167,106 @@ RSpec.describe Hash do
 end
 ```
 
-## the `rspec` command
+## A Word on Scope
+
+RSpec has two scopes:
+
+* **Example Group**: Example groups are defined by a `describe` or
+  `context` block, which is eagerly evaluated when the spec file is
+  loaded. The block is evaluated in the context of a subclass of
+  `RSpec::Core::ExampleGroup`, or a subclass of the parent example group
+  when you're nesting them.
+* **Example**: Examples -- typically defined by an `it` block -- and any other
+  blocks with per-example semantics -- such as a `before(:example)` hook -- are
+  evaluated in the context of
+  an _instance_ of the example group class to which the example belongs.
+  Examples are _not_ executed when the spec file is loaded; instead,
+  RSpec waits to run any examples until all spec files have been loaded,
+  at which point it can apply filtering, randomization, etc.
+
+To make this more concrete, consider this code snippet:
+
+``` ruby
+RSpec.describe "Using an array as a stack" do
+  def build_stack
+    []
+  end
+
+  before(:example) do
+    @stack = build_stack
+  end
+
+  it 'is initially empty' do
+    expect(@stack).to be_empty
+  end
+
+  context "after an item has been pushed" do
+    before(:example) do
+      @stack.push :item
+    end
+
+    it 'allows the pushed item to be popped' do
+      expect(@stack.pop).to eq(:item)
+    end
+  end
+end
+```
+
+Under the covers, this is (roughly) equivalent to:
+
+``` ruby
+class UsingAnArrayAsAStack < RSpec::Core::ExampleGroup
+  def build_stack
+    []
+  end
+
+  def before_example_1
+    @stack = build_stack
+  end
+
+  def it_is_initially_empty
+    expect(@stack).to be_empty
+  end
+
+  class AfterAnItemHasBeenPushed < self
+    def before_example_2
+      @stack.push :item
+    end
+
+    def it_allows_the_pushed_item_to_be_popped
+      expect(@stack.pop).to eq(:item)
+    end
+  end
+end
+```
+
+To run these examples, RSpec would (roughly) do the following:
+
+``` ruby
+example_1 = UsingAnArrayAsAStack.new
+example_1.before_example_1
+example_1.it_is_initially_empty
+
+example_2 = UsingAnArrayAsAStack::AfterAnItemHasBeenPushed.new
+example_2.before_example_1
+example_2.before_example_2
+example_2.it_allows_the_pushed_item_to_be_popped
+```
+
+## The `rspec` Command
 
 When you install the rspec-core gem, it installs the `rspec` executable,
 which you'll use to run rspec. The `rspec` command comes with many useful
 options.
 Run `rspec --help` to see the complete list.
 
-## store command line options `.rspec`
+## Store Command Line Options `.rspec`
 
 You can store command line options in a `.rspec` file in the project's root
 directory, and the `rspec` command will read them as though you typed them on
 the command line.
 
-## autotest integration
-
-rspec-core no longer ships with an Autotest extension, if you require Autotest
-integration, please use the `rspec-autotest` gem and see [rspec/rspec-autotest](https://github.com/rspec/rspec-autotest)
-for details
-
-## get started
+## Get Started
 
 Start with a simple example of behavior you expect from your system. Do
 this before you write any implementation code:
@@ -195,13 +289,12 @@ $ rspec spec/calculator_spec.rb
 ./spec/calculator_spec.rb:1: uninitialized constant Calculator
 ```
 
-Implement the simplest solution:
+Address the failure by defining a skeleton of the `Calculator` class:
 
 ```ruby
 # in lib/calculator.rb
 class Calculator
-  def add(a,b)
-    a + b
+  def add(a, b)
   end
 end
 ```
@@ -214,6 +307,39 @@ Be sure to require the implementation file in the spec:
 require "calculator"
 ```
 
+Now run the spec again, and watch the expectation fail:
+
+```
+$ rspec spec/calculator_spec.rb
+F
+
+Failures:
+
+  1) Calculator#add returns the sum of its arguments
+     Failure/Error: expect(Calculator.new.add(1, 2)).to eq(3)
+
+       expected: 3
+            got: nil
+
+       (compared using ==)
+     # ./spec/calculator_spec.rb:6:in `block (3 levels) in <top (required)>'
+
+Finished in 0.00131 seconds (files took 0.10968 seconds to load)
+1 example, 1 failure
+
+Failed examples:
+
+rspec ./spec/calculator_spec.rb:5 # Calculator#add returns the sum of its arguments
+```
+
+Implement the simplest solution, by changing the definition of `Calculator#add` to:
+
+```ruby
+def add(a, b)
+  a + b
+end
+```
+
 Now run the spec again, and watch it pass:
 
 ```
@@ -236,8 +362,23 @@ Finished in 0.000379 seconds
 1 example, 0 failures
 ```
 
+## Contributing
+
+Once you've set up the environment, you'll need to cd into the working
+directory of whichever repo you want to work in. From there you can run the
+specs and cucumber features, and make patches.
+
+NOTE: You do not need to use rspec-dev to work on a specific RSpec repo. You
+can treat each RSpec repo as an independent project.
+
+* [Build details](BUILD_DETAIL.md)
+* [Code of Conduct](CODE_OF_CONDUCT.md)
+* [Detailed contributing guide](CONTRIBUTING.md)
+* [Development setup guide](DEVELOPMENT.md)
+
 ## Also see
 
-* [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)
+* [https://github.com/rspec/rspec](https://github.com/rspec/rspec)
+* [https://github.com/rspec/rspec-expectations](https://github.com/rspec/rspec-expectations)
+* [https://github.com/rspec/rspec-mocks](https://github.com/rspec/rspec-mocks)
+* [https://github.com/rspec/rspec-rails](https://github.com/rspec/rspec-rails)

data/lib/rspec/autorun.rb

@@ -1,2 +1,3 @@
 require 'rspec/core'
+# Ensure the default config is loaded
 RSpec::Core::Runner.autorun

data/lib/rspec/core/backtrace_formatter.rb

@@ -8,28 +8,31 @@ module RSpec
       def initialize
         @full_backtrace = false
 
-        patterns = [
-          "/lib\d*/ruby/",
-          "org/jruby/",
-          "bin/",
-          "/gems/",
-        ].map { |s| Regexp.new(s.gsub("/", File::SEPARATOR)) }
+        patterns = %w[ /lib\d*/ruby/ bin/ exe/rspec /lib/bundler/ /exe/bundle: ]
+        patterns << "org/jruby/" if RUBY_PLATFORM == 'java'
+        patterns.map! { |s| Regexp.new(s.gsub("/", File::SEPARATOR)) }
 
-        @system_exclusion_patterns = [Regexp.union(RSpec::CallerFilter::IGNORE_REGEX, *patterns)]
-        @exclusion_patterns = [] + @system_exclusion_patterns
-        @inclusion_patterns = [Regexp.new(Dir.getwd)]
-      end
+        @exclusion_patterns = [Regexp.union(RSpec::CallerFilter::IGNORE_REGEX, *patterns)]
+        @inclusion_patterns = []
 
-      def full_backtrace=(full_backtrace)
-        @full_backtrace = full_backtrace
+        return unless matches?(@exclusion_patterns, File.join(Dir.getwd, "lib", "foo.rb:13"))
+        inclusion_patterns << Regexp.new(Dir.getwd)
       end
 
+      attr_writer :full_backtrace
+
       def full_backtrace?
-        @full_backtrace || @exclusion_patterns.empty?
+        @full_backtrace || exclusion_patterns.empty?
+      end
+
+      def filter_gem(gem_name)
+        sep = File::SEPARATOR
+        exclusion_patterns << /#{sep}#{gem_name}(-[^#{sep}]+)?#{sep}/
       end
 
-      def format_backtrace(backtrace, options = {})
-        return backtrace if options[:full_backtrace]
+      def format_backtrace(backtrace, options={})
+        return [] unless backtrace
+        return backtrace if options[:full_backtrace] || backtrace.empty?
 
         backtrace.map { |l| backtrace_line(l) }.compact.
           tap do |filtered|
@@ -45,15 +48,11 @@ module RSpec
 
       def backtrace_line(line)
         Metadata.relative_path(line) unless exclude?(line)
-      rescue SecurityError
-        nil
       end
 
       def exclude?(line)
         return false if @full_backtrace
-        relative_line = Metadata.relative_path(line)
-        return false unless matches?(@exclusion_patterns, relative_line)
-        matches?(@system_exclusion_patterns, relative_line) || !matches?(@inclusion_patterns, line)
+        matches?(exclusion_patterns, line) && !matches?(inclusion_patterns, line)
       end
 
     private

data/lib/rspec/core/bisect/coordinator.rb

@@ -0,0 +1,62 @@
+RSpec::Support.require_rspec_core "bisect/shell_command"
+RSpec::Support.require_rspec_core "bisect/example_minimizer"
+RSpec::Support.require_rspec_core "bisect/utilities"
+RSpec::Support.require_rspec_core "formatters/bisect_progress_formatter"
+
+module RSpec
+  module Core
+    module Bisect
+      # The main entry point into the bisect logic. Coordinates among:
+      #   - Bisect::ShellCommand: Generates shell commands to run spec subsets
+      #   - Bisect::ExampleMinimizer: Contains the core bisect logic.
+      #   - A bisect runner: runs a set of examples and returns the results.
+      #   - A bisect formatter: provides progress updates to the user.
+      # @private
+      class Coordinator
+        def self.bisect_with(spec_runner, original_cli_args, formatter)
+          new(spec_runner, original_cli_args, formatter).bisect
+        end
+
+        def initialize(spec_runner, original_cli_args, formatter)
+          @spec_runner   = spec_runner
+          @shell_command = ShellCommand.new(original_cli_args)
+          @notifier      = Bisect::Notifier.new(formatter)
+        end
+
+        def bisect
+          repro = start_bisect_runner do |runner|
+            minimizer = ExampleMinimizer.new(@shell_command, runner, @notifier)
+
+            gracefully_abort_on_sigint(minimizer)
+            minimizer.find_minimal_repro
+            minimizer.repro_command_for_currently_needed_ids
+          end
+
+          @notifier.publish(:bisect_repro_command, :repro => repro)
+
+          true
+        rescue BisectFailedError => e
+          @notifier.publish(:bisect_failed, :failure_explanation => e.message)
+          false
+        ensure
+          @notifier.publish(:close)
+        end
+
+      private
+
+        def start_bisect_runner(&block)
+          klass = @spec_runner.configuration.bisect_runner_class
+          klass.start(@shell_command, @spec_runner, &block)
+        end
+
+        def gracefully_abort_on_sigint(minimizer)
+          trap('INT') do
+            repro = minimizer.repro_command_for_currently_needed_ids
+            @notifier.publish(:bisect_aborted, :repro => repro)
+            exit(1)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rspec/core/bisect/example_minimizer.rb

@@ -0,0 +1,173 @@
+RSpec::Support.require_rspec_core "bisect/utilities"
+
+module RSpec
+  module Core
+    module Bisect
+      # @private
+      # Contains the core bisect logic. Searches for examples we can ignore by
+      # repeatedly running different subsets of the suite.
+      class ExampleMinimizer
+        attr_reader :shell_command, :runner, :all_example_ids, :failed_example_ids
+        attr_accessor :remaining_ids
+
+        def initialize(shell_command, runner, notifier)
+          @shell_command = shell_command
+          @runner        = runner
+          @notifier      = notifier
+        end
+
+        def find_minimal_repro
+          prep
+
+          _, duration = track_duration do
+            bisect(non_failing_example_ids)
+          end
+
+          notify(:bisect_complete, :duration => duration,
+                                   :original_non_failing_count => non_failing_example_ids.size,
+                                   :remaining_count => remaining_ids.size)
+
+          remaining_ids + failed_example_ids
+        end
+
+        def bisect(candidate_ids)
+          notify(:bisect_dependency_check_started)
+          if get_expected_failures_for?([])
+            notify(:bisect_dependency_check_failed)
+            self.remaining_ids = []
+            return
+          end
+          notify(:bisect_dependency_check_passed)
+
+          bisect_over(candidate_ids)
+        end
+
+        def bisect_over(candidate_ids)
+          return if candidate_ids.one?
+
+          notify(
+            :bisect_round_started,
+            :candidate_range => example_range(candidate_ids),
+            :candidates_count => candidate_ids.size
+          )
+
+          slice_size = (candidate_ids.length / 2.0).ceil
+          lhs, rhs = candidate_ids.each_slice(slice_size).to_a
+
+          ids_to_ignore, duration = track_duration do
+            [lhs, rhs].find do |ids|
+              get_expected_failures_for?(remaining_ids - ids)
+            end
+          end
+
+          if ids_to_ignore
+            self.remaining_ids -= ids_to_ignore
+            notify(
+              :bisect_round_ignoring_ids,
+              :ids_to_ignore => ids_to_ignore,
+              :ignore_range => example_range(ids_to_ignore),
+              :remaining_ids => remaining_ids,
+              :duration => duration
+            )
+            bisect_over(candidate_ids - ids_to_ignore)
+          else
+            notify(
+              :bisect_round_detected_multiple_culprits,
+              :duration => duration
+            )
+            bisect_over(lhs)
+            bisect_over(rhs)
+          end
+        end
+
+        def currently_needed_ids
+          remaining_ids + failed_example_ids
+        end
+
+        def repro_command_for_currently_needed_ids
+          return shell_command.repro_command_from(currently_needed_ids) if remaining_ids
+          "(Not yet enough information to provide any repro command)"
+        end
+
+        # @private
+        # Convenience class for describing a subset of the candidate examples
+        ExampleRange = Struct.new(:start, :finish) do
+          def description
+            if start == finish
+              "example #{start}"
+            else
+              "examples #{start}-#{finish}"
+            end
+          end
+        end
+
+      private
+
+        def example_range(ids)
+          ExampleRange.new(
+            non_failing_example_ids.find_index(ids.first) + 1,
+            non_failing_example_ids.find_index(ids.last) + 1
+          )
+        end
+
+        def prep
+          notify(:bisect_starting, :original_cli_args => shell_command.original_cli_args,
+                                   :bisect_runner => runner.class.name)
+
+          _, duration = track_duration do
+            original_results    = runner.original_results
+            @all_example_ids    = original_results.all_example_ids
+            @failed_example_ids = original_results.failed_example_ids
+            @remaining_ids      = non_failing_example_ids
+          end
+
+          if @failed_example_ids.empty?
+            raise BisectFailedError, "\n\nNo failures found. Bisect only works " \
+                  "in the presence of one or more failing examples."
+          else
+            notify(:bisect_original_run_complete, :failed_example_ids => failed_example_ids,
+                                                  :non_failing_example_ids => non_failing_example_ids,
+                                                  :duration => duration)
+          end
+        end
+
+        def non_failing_example_ids
+          @non_failing_example_ids ||= all_example_ids - failed_example_ids
+        end
+
+        def get_expected_failures_for?(ids)
+          ids_to_run = ids + failed_example_ids
+          notify(
+            :bisect_individual_run_start,
+            :command => shell_command.repro_command_from(ids_to_run),
+            :ids_to_run => ids_to_run
+          )
+
+          results, duration = track_duration { runner.run(ids_to_run) }
+          notify(:bisect_individual_run_complete, :duration => duration, :results => results)
+
+          abort_if_ordering_inconsistent(results)
+          (failed_example_ids & results.failed_example_ids) == failed_example_ids
+        end
+
+        def track_duration
+          start = ::RSpec::Core::Time.now
+          [yield, ::RSpec::Core::Time.now - start]
+        end
+
+        def abort_if_ordering_inconsistent(results)
+          expected_order = all_example_ids & results.all_example_ids
+          return if expected_order == results.all_example_ids
+
+          raise BisectFailedError, "\n\nThe example ordering is inconsistent. " \
+                "`--bisect` relies upon consistent ordering (e.g. by passing " \
+                "`--seed` if you're using random ordering) to work properly."
+        end
+
+        def notify(*args)
+          @notifier.publish(*args)
+        end
+      end
+    end
+  end
+end