sspec-core 3.8.0

data/LICENSE.md

@@ -0,0 +1,26 @@
+The MIT License (MIT)
+=====================
+
+* 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
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,384 @@
+# rspec-core [![Build Status](https://secure.travis-ci.org/rspec/rspec-core.svg?branch=master)](http://travis-ci.org/rspec/rspec-core) [![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
+
+    gem install rspec      # for rspec-core, rspec-expectations, rspec-mocks
+    gem install rspec-core # for rspec-core only
+    rspec --help
+
+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 rspec-core rspec-expectations rspec-mocks rspec-support].each do |lib|
+  gem lib, :git => "https://github.com/rspec/#{lib}.git", :branch => 'master'
+end
+```
+
+## 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)
+
+## Basic Structure
+
+RSpec uses the words "describe" and "it" so we can express concepts like a conversation:
+
+    "Describe an order."
+    "It sums the prices of its line items."
+
+```ruby
+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)
+    )))
+    order.add_entry(LineItem.new(:item => Item.new(
+      :price => Money.new(2.22, :USD),
+      :quantity => 2
+    )))
+
+    expect(order.total).to eq(Money.new(5.55, :USD))
+  end
+end
+```
+
+The `describe` method creates an [ExampleGroup](http://rubydoc.info/gems/rspec-core/RSpec/Core/ExampleGroup).  Within the
+block passed to `describe` you can declare examples using the `it` method.
+
+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
+
+You can also declare nested nested groups using the `describe` or `context`
+methods:
+
+```ruby
+RSpec.describe Order do
+  context "with no items" do
+    it "behaves one way" do
+      # ...
+    end
+  end
+
+  context "with one item" do
+    it "behaves another way" do
+      # ...
+    end
+  end
+end
+```
+
+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
+off of `RSpec`. For backwards compatibility, they are also available
+off of the `main` object and `Module` unless you disable monkey
+patching.
+
+You can declare examples within a group using any of `it`, `specify`, or
+`example`.
+
+## Shared Examples and Contexts
+
+Declare a shared example group using `shared_examples`, and then include it
+in any group using `include_examples`.
+
+```ruby
+RSpec.shared_examples "collections" do |collection_class|
+  it "is empty when first created" do
+    expect(collection_class.new).to be_empty
+  end
+end
+
+RSpec.describe Array do
+  include_examples "collections", Array
+end
+
+RSpec.describe Hash do
+  include_examples "collections", Hash
+end
+```
+
+Nearly anything that can be declared within an example group can be declared
+within a shared example group. This includes `before`, `after`, and `around`
+hooks, `let` declarations, and nested groups/contexts.
+
+You can also use the names `shared_context` and `include_context`. These are
+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
+
+rspec-core stores a metadata hash with every example and group, which
+contains their descriptions, the locations at which they were
+declared, etc, etc. This hash powers many of rspec-core's features,
+including output formatters (which access descriptions and locations),
+and filtering before and after hooks.
+
+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 |example|
+  expect(example.metadata[:description]).to eq("does something")
+end
+```
+
+### `described_class`
+
+When a class is passed to `describe`, you can access it from an example
+using the `described_class` method, which is a wrapper for
+`example.metadata[:described_class]`.
+
+```ruby
+RSpec.describe Widget do
+  example do
+    expect(described_class).to equal(Widget)
+  end
+end
+```
+
+This is useful in extensions or shared example groups in which the specific
+class is unknown. Taking the collections shared example group from above, we can
+clean it up a bit using `described_class`:
+
+```ruby
+RSpec.shared_examples "collections" do
+  it "is empty when first created" do
+    expect(described_class.new).to be_empty
+  end
+end
+
+RSpec.describe Array do
+  include_examples "collections"
+end
+
+RSpec.describe Hash do
+  include_examples "collections"
+end
+```
+
+## 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`
+
+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.
+
+## Get Started
+
+Start with a simple example of behavior you expect from your system. Do
+this before you write any implementation code:
+
+```ruby
+# in spec/calculator_spec.rb
+RSpec.describe Calculator do
+  describe '#add' do
+    it 'returns the sum of its arguments' do
+      expect(Calculator.new.add(1, 2)).to eq(3)
+    end
+  end
+end
+```
+
+Run this with the rspec command, and watch it fail:
+
+```
+$ rspec spec/calculator_spec.rb
+./spec/calculator_spec.rb:1: uninitialized constant Calculator
+```
+
+Address the failure by defining a skeleton of the `Calculator` class:
+
+```ruby
+# in lib/calculator.rb
+class Calculator
+  def add(a, b)
+  end
+end
+```
+
+Be sure to require the implementation file in the spec:
+
+```ruby
+# in spec/calculator_spec.rb
+# - RSpec adds ./lib to the $LOAD_PATH
+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:
+
+```
+$ rspec spec/calculator_spec.rb
+.
+
+Finished in 0.000315 seconds
+1 example, 0 failures
+```
+
+Use the `documentation` formatter to see the resulting spec:
+
+```
+$ rspec spec/calculator_spec.rb --format doc
+Calculator
+  #add
+    returns the sum of its arguments
+
+Finished in 0.000379 seconds
+1 example, 0 failures
+```
+
+## Also see
+
+* [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/exe/rspec

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+
+require 'rspec/core'
+RSpec::Core::Runner.invoke

data/lib/rspec/autorun.rb

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

data/lib/rspec/core.rb

@@ -0,0 +1,185 @@
+# rubocop:disable Style/GlobalVars
+$_rspec_core_load_started_at = Time.now
+# rubocop:enable Style/GlobalVars
+
+require "rspec/support"
+RSpec::Support.require_rspec_support "caller_filter"
+
+RSpec::Support.define_optimized_require_for_rspec(:core) { |f| require_relative f }
+
+%w[
+  version
+  warnings
+
+  set
+  flat_map
+  filter_manager
+  dsl
+  notifications
+  reporter
+
+  hooks
+  memoized_helpers
+  metadata
+  metadata_filter
+  pending
+  formatters
+  ordering
+
+  world
+  configuration
+  option_parser
+  configuration_options
+  runner
+  invocations
+  example
+  shared_example_group
+  example_group
+].each { |name| RSpec::Support.require_rspec_core name }
+
+# Namespace for all core RSpec code.
+module RSpec
+  autoload :SharedContext, 'rspec/core/shared_context'
+
+  extend RSpec::Core::Warnings
+
+  class << self
+    # Setters for shared global objects
+    # @api private
+    attr_writer :configuration, :world
+  end
+
+  # Used to ensure examples get reloaded and user configuration gets reset to
+  # defaults between multiple runs in the same process.
+  #
+  # Users must invoke this if they want to have the configuration reset when
+  # they use the runner multiple times within the same process. Users must deal
+  # themselves with re-configuration of RSpec before run.
+  def self.reset
+    RSpec::ExampleGroups.remove_all_constants
+    @world = nil
+    @configuration = nil
+  end
+
+  # Used to ensure examples get reloaded between multiple runs in the same
+  # process and ensures user configuration is persisted.
+  #
+  # Users must invoke this if they want to clear all examples but preserve
+  # current configuration when they use the runner multiple times within the
+  # same process.
+  def self.clear_examples
+    world.reset
+    configuration.reset_reporter
+    configuration.start_time = ::RSpec::Core::Time.now
+    configuration.reset_filters
+  end
+
+  # Returns the global [Configuration](RSpec/Core/Configuration) object. While
+  # you _can_ use this method to access the configuration, the more common
+  # convention is to use [RSpec.configure](RSpec#configure-class_method).
+  #
+  # @example
+  #     RSpec.configuration.drb_port = 1234
+  # @see RSpec.configure
+  # @see Core::Configuration
+  def self.configuration
+    @configuration ||= RSpec::Core::Configuration.new
+  end
+
+  # Yields the global configuration to a block.
+  # @yield [Configuration] global configuration
+  #
+  # @example
+  #     RSpec.configure do |config|
+  #       config.add_formatter 'documentation'
+  #     end
+  # @see Core::Configuration
+  def self.configure
+    yield configuration if block_given?
+  end
+
+  # The example being executed.
+  #
+  # The primary audience for this method is library authors who need access
+  # to the example currently being executed and also want to support all
+  # versions of RSpec 2 and 3.
+  #
+  # @example
+  #
+  #     RSpec.configure do |c|
+  #       # context.example is deprecated, but RSpec.current_example is not
+  #       # available until RSpec 3.0.
+  #       fetch_current_example = RSpec.respond_to?(:current_example) ?
+  #         proc { RSpec.current_example } : proc { |context| context.example }
+  #
+  #       c.before(:example) do
+  #         example = fetch_current_example.call(self)
+  #
+  #         # ...
+  #       end
+  #     end
+  #
+  def self.current_example
+    RSpec::Support.thread_local_data[:current_example]
+  end
+
+  # Set the current example being executed.
+  # @api private
+  def self.current_example=(example)
+    RSpec::Support.thread_local_data[:current_example] = example
+  end
+
+  # @private
+  # Internal container for global non-configuration data.
+  def self.world
+    @world ||= RSpec::Core::World.new
+  end
+
+  # 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
+    # it.
+    class Time
+      class << self
+        define_method(:now, &::Time.method(:now))
+      end
+    end
+
+    # @private path to executable file.
+    def self.path_to_executable
+      @path_to_executable ||= File.expand_path('../../../exe/rspec', __FILE__)
+    end
+  end
+
+  # @private
+  MODULES_TO_AUTOLOAD = {
+    :Matchers     => "rspec/expectations",
+    :Expectations => "rspec/expectations",
+    :Mocks        => "rspec/mocks"
+  }
+
+  # @private
+  def self.const_missing(name)
+    # Load rspec-expectations when RSpec::Matchers is referenced. This allows
+    # people to define custom matchers (using `RSpec::Matchers.define`) before
+    # rspec-core has loaded rspec-expectations (since it delays the loading of
+    # it to allow users to configure a different assertion/expectation
+    # framework). `autoload` can't be used since it works with ruby's built-in
+    # require (e.g. for files that are available relative to a load path dir),
+    # but not with rubygems' extended require.
+    #
+    # As of rspec 2.14.1, we no longer require `rspec/mocks` and
+    # `rspec/expectations` when `rspec` is required, so we want
+    # to make them available as an autoload.
+    require MODULES_TO_AUTOLOAD.fetch(name) { return super }
+    ::RSpec.const_get(name)
+  end
+
+  Core::DSL.expose_globally!
+  Core::SharedExampleGroup::TopLevelDSL.expose_globally!
+end