opal-rspec 0.8.0 → 1.0.0.alpha1

data/rspec-core/upstream/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/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:
 
 ```
@@ -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/rspec-core/upstream/REPORT_TEMPLATE.md

@@ -0,0 +1,43 @@
+<!---
+This file was generated on 2020-12-25T18:48:30+00:00 from the rspec-dev repo.
+DO NOT modify it by hand as your changes will get lost the next time it is generated.
+-->
+
+# Report template
+
+```ruby
+# frozen_string_literal: true
+
+begin
+  require "bundler/inline"
+rescue LoadError => e
+  $stderr.puts "Bundler version 1.10 or later is required. Please update your Bundler"
+  raise e
+end
+
+gemfile(true) do
+  source "https://rubygems.org"
+
+  gem "rspec", "3.7.0" # Activate the gem and version you are reporting the issue against.
+end
+
+puts "Ruby version is: #{RUBY_VERSION}"
+require 'rspec/autorun'
+
+RSpec.describe 'additions' do
+  it 'returns 2' do
+    expect(1 + 1).to eq(2)
+  end
+
+  it 'returns 1' do
+    expect(3 - 1).to eq(-1)
+  end
+end
+```
+
+Simply copy the content of the appropriate template into a `.rb` file on your computer
+and make the necessary changes to demonstrate the issue. You can execute it by running
+`ruby rspec_report.rb` in your terminal.
+
+You can then share your executable test case as a [gist](https://gist.github.com), or
+simply paste the content into the issue description.

data/rspec-core/upstream/Rakefile

@@ -78,7 +78,7 @@ task :default => [:spec, :cucumber, :rubocop]
 task :verify_private_key_present do
   private_key = File.expand_path('~/.gem/rspec-gem-private_key.pem')
   unless File.exist?(private_key)
-    raise "Your private key is not present. This gem should not be built without that."
+    raise "Your private key is not present. This gem should not be built without it."
   end
 end
 

data/rspec-core/upstream/benchmarks/allocations/1000_groups_1_example.rb

@@ -0,0 +1,124 @@
+require_relative "helper"
+
+benchmark_allocations do
+  1000.times do |i|
+    RSpec.describe "group #{i}" do
+      it "has one example" do
+      end
+    end
+  end
+end
+
+__END__
+
+Original allocations:
+
+               class_plus                 count
+----------------------------------------  -----
+String                                    28000
+Array                                     15000
+RubyVM::Env                                9000
+Proc                                       9000
+Hash                                       9000
+RSpec::Core::Hooks::HookCollection         6000
+Array<String>                              5000
+MatchData                                  3000
+Array<String,Fixnum>                       2000
+Array<Module>                              2000
+Module                                     2000
+RSpec::Core::Example::ExecutionResult      2000
+RSpec::Core::Metadata::ExampleGroupHash    1000
+Class                                      1000
+Array<Hash>                                1000
+RSpec::Core::Hooks::AroundHookCollection   1000
+RSpec::Core::Hooks::HookCollections        1000
+RSpec::Core::Metadata::ExampleHash         1000
+RSpec::Core::Example                       1000
+Array<RSpec::Core::Example>                1000
+
+
+After removing `:suite` support from `Hooks` module,
+it cut Array and RSpec::Core::Hooks::HookCollection
+allocations by 2000 each:
+
+               class_plus                 count
+----------------------------------------  -----
+String                                    28000
+Array                                     13000
+Proc                                       9000
+RubyVM::Env                                9000
+Hash                                       9000
+Array<String>                              5000
+RSpec::Core::Hooks::HookCollection         4000
+MatchData                                  3000
+Array<Module>                              2000
+RSpec::Core::Example::ExecutionResult      2000
+Module                                     2000
+Array<String,Fixnum>                       2000
+RSpec::Core::Hooks::HookCollections        1000
+RSpec::Core::Example                       1000
+Array<RSpec::Core::Example>                1000
+RSpec::Core::Metadata::ExampleHash         1000
+RSpec::Core::Hooks::AroundHookCollection   1000
+RSpec::Core::Metadata::ExampleGroupHash    1000
+Class                                      1000
+Array<Hash>                                1000
+
+....
+
+Later, our allocations were:
+
+              class_plus                 count
+---------------------------------------  -----
+String                                   26000
+Hash                                     19000
+Array                                    18000
+Set                                      10000
+Proc                                      9000
+RubyVM::Env                               9000
+RSpec::Core::Hooks::HookCollection        5000
+RSpec::Core::FilterableItemRepository     5000
+Array<String>                             5000
+MatchData                                 3000
+RSpec::Core::Example::ExecutionResult     2000
+Array<String,Fixnum>                      2000
+Module                                    2000
+Array<Module>                             2000
+RSpec::Core::Metadata::ExampleGroupHash   1000
+Class                                     1000
+RSpec::Core::Metadata::ExampleHash        1000
+RSpec::Core::Example                      1000
+Array<RSpec::Core::Example>               1000
+Array<Hash>                               1000
+RSpec::Core::Hooks::HookCollections       1000
+
+
+After changing the hooks implementation to lazily
+instantiate `HookCollection` instances, it dropped
+our allocations by:
+  - 8K hashes
+  - 10K arrays
+  - 10K sets
+  - 5K FilterableItemRepository
+  - 5K HookCollecion
+
+              class_plus                 count
+---------------------------------------  -----
+String                                   26000
+Hash                                     11000
+Array                                     8000
+Proc                                      5000
+RubyVM::Env                               5000
+Array<String>                             5000
+MatchData                                 3000
+Array<Module>                             2000
+Array<String,Fixnum>                      2000
+RSpec::Core::Example::ExecutionResult     2000
+Module                                    2000
+Array<Hash>                               1000
+RSpec::Core::Metadata::ExampleGroupHash   1000
+Class                                     1000
+RSpec::Core::Metadata::ExampleHash        1000
+RSpec::Core::Example                      1000
+Array<RSpec::Core::Example>               1000
+RSpec::Core::Hooks::HookCollections       1000

data/rspec-core/upstream/benchmarks/allocations/1_group_1000_examples.rb

@@ -0,0 +1,63 @@
+require_relative "helper"
+
+benchmark_allocations do
+  RSpec.describe "one example group" do
+    1000.times do |i|
+      example "example #{i}" do
+      end
+    end
+  end
+end
+
+__END__
+
+Original stats:
+
+               class_plus                 count
+----------------------------------------  -----
+String                                    22046
+Hash                                       3006
+Array<String>                              3002
+Proc                                       2007
+RubyVM::Env                                2007
+Array                                      1013
+Regexp                                     1001
+RSpec::Core::Example::ExecutionResult      1001
+Array<String,Fixnum>                       1001
+RSpec::Core::Example                       1000
+RSpec::Core::Metadata::ExampleHash         1000
+RSpec::Core::Hooks::HookCollection            6
+MatchData                                     4
+Array<Module>                                 2
+Module                                        2
+RSpec::Core::Metadata::ExampleGroupHash       1
+RSpec::Core::Hooks::AroundHookCollection      1
+Class                                         1
+Array<Hash>                                   1
+RSpec::Core::Hooks::HookCollections           1
+Array<RSpec::Core::Example>                   1
+
+After my fixes:
+
+               class_plus                 count
+----------------------------------------  -----
+String                                     6030
+Hash                                       3006
+Array<String>                              3002
+RubyVM::Env                                2007
+Proc                                       2007
+Array                                      1013
+RSpec::Core::Example::ExecutionResult      1001
+Array<String,Fixnum>                       1001
+RSpec::Core::Metadata::ExampleHash         1000
+RSpec::Core::Example                       1000
+RSpec::Core::Hooks::HookCollection            6
+MatchData                                     4
+Module                                        2
+Array<Module>                                 2
+RSpec::Core::Hooks::HookCollections           1
+Array<RSpec::Core::Example>                   1
+RSpec::Core::Hooks::AroundHookCollection      1
+RSpec::Core::Metadata::ExampleGroupHash       1
+Class                                         1
+Array<Hash>                                   1

data/rspec-core/upstream/benchmarks/allocations/helper.rb

@@ -0,0 +1,30 @@
+$LOAD_PATH.unshift File.expand_path("../../../lib", __FILE__)
+require 'rspec/core'
+require 'allocation_stats'
+
+def benchmark_allocations(burn: 1, min_allocations: 0)
+  stats = AllocationStats.new(burn: burn).trace do
+    yield
+  end
+
+  columns = if ENV['DETAIL']
+              [:sourcefile, :sourceline, :class_plus]
+            else
+              [:class_plus]
+            end
+
+  results = stats.allocations(alias_paths: true).group_by(*columns).from_pwd.sort_by_size.to_text
+  count_regex = /\s+(\d+)\z/
+
+  total_objects = results.split("\n").map { |line| line[count_regex, 1] }.compact.map { |c| Integer(c) }.inject(0, :+)
+
+  filtered = results.split("\n").select do |line|
+    count = line[count_regex, 1]
+    count.nil? || Integer(count) >= min_allocations
+  end
+
+  puts filtered.join("\n")
+  line_length = filtered.last.length
+  puts "-" * line_length
+  puts "Total:#{total_objects.to_s.rjust(line_length - "Total:".length)}"
+end

data/rspec-core/upstream/benchmarks/allocations/running_1000_groups_1_example.rb

@@ -0,0 +1,100 @@
+require_relative "helper"
+
+1000.times do |i|
+  RSpec.describe "group #{i}" do
+    it "has one example" do
+    end
+  end
+end
+
+benchmark_allocations(burn: 0, min_allocations: 50) do
+  RSpec::Core::Runner.run([])
+end
+
+__END__
+
+Before optimization:
+
+                                          class_plus                                             count
+-----------------------------------------------------------------------------------------------  -----
+Array<Symbol>                                                                                    26021
+String                                                                                           21331
+Array                                                                                            19402
+Array<Symbol,Proc>                                                                                6001
+Array<RSpec::Core::Example>                                                                       6001
+RSpec::Core::Hooks::HookCollection                                                                4004
+Array<Class>                                                                                      4004
+Hash                                                                                              3098
+Proc                                                                                              3096
+RubyVM::Env                                                                                       3056
+Time                                                                                              2002
+Random                                                                                            2001
+RSpec::Core::Hooks::AroundHookCollection                                                          2000
+RSpec::Core::Notifications::GroupNotification                                                     2000
+RSpec::Core::Notifications::ExampleNotification                                                   2000
+RSpec::Core::Hooks::GroupHookCollection                                                           2000
+Array<Symbol,TrueClass>                                                                           1003
+Array<Class,Module>                                                                               1002
+Array<TrueClass>                                                                                  1002
+RSpec::Core::Example::Procsy                                                                      1000
+RubyVM::InstructionSequence                                                                        506
+Array<Fixnum,FalseClass>                                                                           391
+Array<Array>                                                                                       205
+Array<String>                                                                                       52
+
+
+After optimization, we allocate 2000 less arrays and 2000 less RSpec::Core::Hooks::HookCollection
+instances. That's 2 less of each per example group.
+
+                                          class_plus                                             count
+-----------------------------------------------------------------------------------------------  -----
+Array<Symbol>                                                                                    26021
+String                                                                                           21331
+Array                                                                                            17400
+Array<Symbol,Proc>                                                                                6001
+Array<RSpec::Core::Example>                                                                       6001
+Array<Class>                                                                                      4004
+Hash                                                                                              3098
+Proc                                                                                              3096
+RubyVM::Env                                                                                       3056
+RSpec::Core::Hooks::HookCollection                                                                2002
+Time                                                                                              2002
+Random                                                                                            2001
+RSpec::Core::Notifications::ExampleNotification                                                   2000
+RSpec::Core::Notifications::GroupNotification                                                     2000
+RSpec::Core::Hooks::GroupHookCollection                                                           2000
+Array<Symbol,TrueClass>                                                                           1003
+Array<Class,Module>                                                                               1002
+Array<TrueClass>                                                                                  1002
+RSpec::Core::Example::Procsy                                                                      1000
+RSpec::Core::Hooks::AroundHookCollection                                                          1000
+RubyVM::InstructionSequence                                                                        506
+Array<Fixnum,FalseClass>                                                                           391
+Array<Array>                                                                                       205
+Array<String>                                                                                       52
+
+After yet further optimization (where HookCollection instances are only created when hooks are added),
+we've reduced allocations significantly further:
+
+                                          class_plus                                             count
+-----------------------------------------------------------------------------------------------  -----
+String                                                                                           21332
+Array                                                                                            13412
+Array<Symbol>                                                                                     6021
+Array<Symbol,Proc>                                                                                6001
+Array<RSpec::Core::Example>                                                                       6001
+Hash                                                                                              3105
+Array<Class>                                                                                      3004
+Proc                                                                                              2101
+RubyVM::Env                                                                                       2061
+Time                                                                                              2002
+Random                                                                                            2001
+RSpec::Core::Notifications::GroupNotification                                                     2000
+RSpec::Core::Notifications::ExampleNotification                                                   2000
+Array<Symbol,TrueClass>                                                                           1003
+Array<Class,Module>                                                                               1002
+Array<TrueClass>                                                                                  1002
+RubyVM::InstructionSequence                                                                        506
+Array<Fixnum,FalseClass>                                                                           391
+Array<Array>                                                                                       208
+Array<String>                                                                                       52