rspec-core 3.2.3 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6ffb9391f287b05bbc4b0e880a9e3298d654dd62
-  data.tar.gz: 371448563101988388e4b14c0e5ab7425c4523bb
+  metadata.gz: a92217ba6e7e8646843f147e18e37e7e0ae135c4
+  data.tar.gz: e4570a04042e8062b594b4fa4ced79df03b7f620
 SHA512:
-  metadata.gz: 0c23ef42b3e1dea1f69b392bae0f2d2ad4e9e5ff6d90fa6c9e931766deae1f8a171f200df3e67320d015cd2196989a7d3c293fc68b0288364aa946d574b49541
-  data.tar.gz: 4dd69a42f3893d6fa6cc493a211bd2a346a589efeef033caf40a83dd804e568d0f664370f265e21131bec5596afba712ed2ceafd17c8ccd0eeae7e9add1f3d74
+  metadata.gz: 94d1f44cd702b90bd31088dbc28908732b1ab07a92865c1673d3fd2fcc29839794e661bb4dccdcf58bafb17e18129765e036e4df33f7da1de3b7a79208743b84
+  data.tar.gz: 4822312a6d75661ca374adf584af31f940415524bc787a93cd7f5ce99c24400f61f6f096f920f84ca83bbec2800cca45d5b466cf0135baa053b79a2792f7761d

data/Changelog.md

@@ -1,3 +1,78 @@
+### 3.3.0 / 2015-06-12
+[Full Changelog](http://github.com/rspec/rspec-core/compare/v3.2.3...v3.3.0)
+
+Enhancements:
+
+* Expose the reporter used to run examples via `RSpec::Core::Example#reporter`.
+  (Jon Rowe, #1866)
+* Make `RSpec::Core::Reporter#message` a public supported API. (Jon Rowe, #1866)
+* Allow custom formatter events to be published via
+  `RSpec::Core::Reporter#publish(event_name, hash_of_attributes)`. (Jon Rowe, #1869)
+* Remove dependency on the standard library `Set` and replace with `RSpec::Core::Set`.
+  (Jon Rowe, #1870)
+* Assign a unique id to each example and group so that they can be
+  uniquely identified, even for shared examples (and similar situations)
+  where the location isn't unique. (Myron Marston, #1884)
+* Use the example id in the rerun command printed for failed examples
+  when the location is not unique. (Myron Marston, #1884)
+* Add `config.example_status_persistence_file_path` option, which is
+  used to persist the last run status of each example. (Myron Marston, #1888)
+* Add `:last_run_status` metadata to each example, which indicates what
+  happened the last time an example ran. (Myron Marston, #1888)
+* Add `--only-failures` CLI option which filters to only the examples
+  that failed the last time they ran. (Myron Marston, #1888)
+* Add `--next-failure` CLI option which allows you to repeatedly focus
+  on just one of the currently failing examples, then move on to the
+  next failure, etc. (Myron Marston, #1888)
+* Make `--order random` ordering stable, so that when you rerun a
+  subset with a given seed, the examples will be order consistently
+  relative to each other. (Myron Marston, #1908)
+* Set example group constant earlier so errors when evaluating the context
+  include the example group name (Myron Marson, #1911)
+* Make `let` and `subject` threadsafe. (Josh Cheek, #1858)
+* Add version information into the JSON formatter. (Mark Swinson, #1883)
+* Add `--bisect` CLI option, which will repeatedly run your suite in
+  order to isolate the failures to the smallest reproducible case.
+  (Myron Marston, #1917)
+* For `config.include`, `config.extend` and `config.prepend`, apply the
+  module to previously defined matching example groups. (Eugene Kenny, #1935)
+* When invalid options are parsed, notify users where they came from
+  (e.g. `.rspec` or `~/.rspec` or `ENV['SPEC_OPTS']`) so they can
+  easily find the source of the problem. (Myron Marston, #1940)
+* Add pending message contents to the json formatter output. (Jon Rowe, #1949)
+* Add shared group backtrace to the output displayed by the built-in
+  formatters for pending examples that have been fixed. (Myron Marston, #1946)
+* Add support for `:aggregate_failures` metadata. Tag an example or
+  group with this metadata and it'll use rspec-expectations'
+  `aggregate_failures` feature to allow multiple failures in an example
+  and list them all, rather than aborting on the first failure. (Myron
+  Marston, #1946)
+* When no formatter implements #message add a fallback to prevent those
+  messages being lost. (Jon Rowe, #1980)
+* Profiling examples now takes into account time spent in `before(:context)`
+  hooks. (Denis Laliberté, Jon Rowe, #1971)
+* Improve failure output when an example has multiple exceptions, such
+  as one from an `it` block and one from an `after` block. (Myron Marston, #1985)
+
+Bug Fixes:
+
+* Handle invalid UTF-8 strings within exception methods. (Benjamin Fleischer, #1760)
+* Fix Rake Task quoting of file names with quotes to work properly on
+  Windows. (Myron Marston, #1887)
+* Fix `RSpec::Core::RakeTask#failure_message` so that it gets printed
+  when the task failed. (Myron Marston, #1905)
+* Make `let` work properly when defined in a shared context that is applied
+  to an individual example via metadata. (Myron Marston, #1912)
+* Ensure `rspec/autorun` respects configuration defaults. (Jon Rowe, #1933)
+* Prevent modules overriding example group defined methods when included,
+  prepended or extended by config defined after an example group. (Eugene Kenny, #1935)
+* Fix regression which caused shared examples to be mistakenly run when specs
+  where filtered to a particular location.  (Ben Axnick, #1963)
+* Fix time formatting logic so that it displays 70 seconds as "1 minute,
+  10 seconds" rather than "1 minute, 1 second". (Paul Brennan, #1984)
+* Fix regression where the formatter loader would allow duplicate formatters.
+  (Jon Rowe, #1990)
+
 ### 3.2.3 / 2015-04-06
 [Full Changelog](http://github.com/rspec/rspec-core/compare/v3.2.2...v3.2.3)
 

data/README.md

@@ -4,7 +4,7 @@ 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
@@ -14,12 +14,12 @@ Want to run against the `master` branch? You'll need to include the dependent
 RSpec repos as well. Add the following to your `Gemfile`:
 
 ```ruby
-%w[rspec-core rspec-expectations rspec-mocks rspec-support].each do |lib|
+%w[rspec rspec-core rspec-expectations rspec-mocks rspec-support].each do |lib|
   gem lib, :git => "git://github.com/rspec/#{lib}.git", :branch => 'master'
 end
 ```
 
-## basic structure
+## Basic Structure
 
 RSpec uses the words "describe" and "it" so we can express concepts like a conversation:
 
@@ -30,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)
     )))
@@ -37,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
@@ -49,7 +51,7 @@ 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`
 methods:
@@ -70,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
@@ -81,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`.
@@ -111,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
@@ -123,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
 ```
@@ -162,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:
@@ -204,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
 ```
@@ -223,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/calcalator_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/calcalator_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:
 
 ```

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.rb

@@ -2,8 +2,6 @@
 $_rspec_core_load_started_at = Time.now
 # rubocop:enable Style/GlobalVars
 
-require 'rbconfig'
-
 require "rspec/support"
 RSpec::Support.require_rspec_support "caller_filter"
 
@@ -13,6 +11,7 @@ RSpec::Support.define_optimized_require_for_rspec(:core) { |f| require_relative
   version
   warnings
 
+  set
   flat_map
   filter_manager
   dsl
@@ -82,12 +81,9 @@ module RSpec
   # @see RSpec.configure
   # @see Core::Configuration
   def self.configuration
-    @configuration ||= begin
-                         config = RSpec::Core::Configuration.new
-                         config.expose_dsl_globally = true
-                         config
-                       end
+    @configuration ||= RSpec::Core::Configuration.new
   end
+  configuration.expose_dsl_globally = true
 
   # Yields the global configuration to a block.
   # @yield [Configuration] global configuration
@@ -123,20 +119,13 @@ module RSpec
   #     end
   #
   def self.current_example
-    thread_local_metadata[:current_example]
+    RSpec::Support.thread_local_data[:current_example]
   end
 
   # Set the current example being executed.
   # @api private
   def self.current_example=(example)
-    thread_local_metadata[:current_example] = example
-  end
-
-  # @private
-  # A single thread local variable so we don't excessively pollute that
-  # namespace.
-  def self.thread_local_metadata
-    Thread.current[:_rspec] ||= { :shared_example_group_inclusions => [] }
+    RSpec::Support.thread_local_data[:current_example] = example
   end
 
   # @private
@@ -147,6 +136,9 @@ module RSpec
 
   # Namespace for the rspec-core code.
   module Core
+    autoload :ExampleStatusPersister, "rspec/core/example_status_persister"
+    autoload :Profiler,               "rspec/core/profiler"
+
     # @private
     # This avoids issues with reporting time caused by examples that
     # change the value/meaning of Time.now without properly restoring

data/lib/rspec/core/backtrace_formatter.rb

@@ -31,7 +31,7 @@ module RSpec
       end
 
       def format_backtrace(backtrace, options={})
-        return backtrace if options[:full_backtrace]
+        return backtrace if options[:full_backtrace] || backtrace.empty?
 
         backtrace.map { |l| backtrace_line(l) }.compact.
           tap do |filtered|
@@ -47,8 +47,6 @@ module RSpec
 
       def backtrace_line(line)
         Metadata.relative_path(line) unless exclude?(line)
-      rescue SecurityError
-        nil
       end
 
       def exclude?(line)

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

@@ -0,0 +1,66 @@
+RSpec::Support.require_rspec_core "bisect/server"
+RSpec::Support.require_rspec_core "bisect/runner"
+RSpec::Support.require_rspec_core "bisect/example_minimizer"
+RSpec::Support.require_rspec_core "formatters/bisect_progress_formatter"
+
+module RSpec
+  module Core
+    module Bisect
+      # @private
+      # The main entry point into the bisect logic. Coordinates among:
+      #   - Bisect::Server: Receives suite results.
+      #   - Bisect::Runner: Runs a set of examples and directs the results
+      #     to the server.
+      #   - Bisect::ExampleMinimizer: Contains the core bisect logic.
+      #   - Formatters::BisectProgressFormatter: provides progress updates
+      #     to the user.
+      class Coordinator
+        def self.bisect_with(original_cli_args, configuration, formatter)
+          new(original_cli_args, configuration, formatter).bisect
+        end
+
+        def initialize(original_cli_args, configuration, formatter)
+          @original_cli_args = original_cli_args
+          @configuration     = configuration
+          @formatter         = formatter
+        end
+
+        def bisect
+          @configuration.add_formatter @formatter
+
+          reporter.close_after do
+            repro = Server.run do |server|
+              runner    = Runner.new(server, @original_cli_args)
+              minimizer = ExampleMinimizer.new(runner, reporter)
+
+              gracefully_abort_on_sigint(minimizer)
+              minimizer.find_minimal_repro
+              minimizer.repro_command_for_currently_needed_ids
+            end
+
+            reporter.publish(:bisect_repro_command, :repro => repro)
+          end
+
+          true
+        rescue BisectFailedError => e
+          reporter.publish(:bisect_failed, :failure_explanation => e.message)
+          false
+        end
+
+      private
+
+        def reporter
+          @configuration.reporter
+        end
+
+        def gracefully_abort_on_sigint(minimizer)
+          trap('INT') do
+            repro = minimizer.repro_command_for_currently_needed_ids
+            reporter.publish(:bisect_aborted, :repro => repro)
+            exit(1)
+          end
+        end
+      end
+    end
+  end
+end