opal-rspec 0.7.0.rc.1 → 0.7.0.rc.2

data/rspec-expectations/upstream/Should.md

@@ -0,0 +1,168 @@
+#`should` and `should_not` syntax
+
+From the  beginning RSpec::Expectations provided `should` and `should_not` methods
+to define expectations on any object. In version 2.11 `expect` method was
+introduced which is now the recommended way to define expectations on an object.
+
+###Why switch over from `should` to `expect`
+
+####Fix edge case issues
+
+`should` and `should_not` work by being added to every object. However, RSpec
+does not own every object and cannot ensure they work consistently on every object.
+In particular, they can lead to surprising failures when used with BasicObject-subclassed
+proxy objects.
+
+`expect` avoids these problems altogether by not needing to be available on all objects.
+
+####Unification of block and value syntaxes
+
+Before version 2.11 `expect` was just a more readable alternative for block
+expectations. Since version 2.11 `expect` can be used for both block and value
+expectations.
+
+```ruby
+expect(actual).to eq(expected)
+expect { ... }.to raise_error(ErrorClass)
+```
+
+See
+[http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax](http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax)
+For a detailed explanation
+
+### One-liners
+
+The one-liner syntax supported by
+[rspec-core](http://rubydoc.info/gems/rspec-core)  uses `should` even when
+`config.syntax = :expect`. It reads better than the alternative, and does not
+require a global monkey patch:
+
+```ruby
+describe User do
+  it { should validate_presence_of :email }
+end
+```
+
+### Using either `expect` or `should` or both
+
+By default, both `expect` and `should` syntaxes are available. In the future,
+the default may be changed to only enable the `expect` syntax.
+
+If you want your project to only use any one of these syntaxes, you can configure
+it:
+
+```ruby
+RSpec.configure do |config|
+  config.expect_with :rspec do |c|
+    c.syntax = :expect             # disables `should`
+    # or
+    c.syntax = :should             # disables `expect`
+    # or
+    c.syntax = [:should, :expect]  # default, enables both `should` and `expect`
+  end
+end
+```
+
+See
+[RSpec::Expectations::Syntax#expect](http://rubydoc.info/gems/rspec-expectations/RSpec/Expectations/Syntax:expect)
+for more information.
+
+## Usage
+
+The `should` and `should_not` methods can be used to define expectations on any
+object. 
+
+```ruby
+actual.should eq expected
+actual.should be > 3
+[1, 2, 3].should_not include 4
+```
+
+## Using Built-in matchers
+
+### Equivalence
+
+```ruby
+actual.should     eq(expected)  # passes if actual == expected
+actual.should     == expected   # passes if actual == expected
+actual.should_not eql(expected) # passes if actual.eql?(expected)
+```
+
+Note: we recommend the `eq` matcher over `==` to avoid Ruby's "== in a
+useless context" warning when the `==` matcher is used anywhere but the
+last statement of an example.
+
+### Identity
+
+```ruby
+actual.should     be(expected)    # passes if actual.equal?(expected)
+actual.should_not equal(expected) # passes if actual.equal?(expected)
+```
+
+### Comparisons
+
+```ruby
+actual.should be >  expected
+actual.should be >= expected
+actual.should be <= expected
+actual.should be <  expected
+actual.should be_within(delta).of(expected)
+```
+
+### Regular expressions
+
+```ruby
+actual.should match(/expression/)
+actual.should =~ /expression/
+```
+
+### Types/classes
+
+```ruby
+actual.should     be_an_instance_of(expected)
+actual.should_not be_a_kind_of(expected)
+```
+
+### Truthiness
+
+```ruby
+actual.should be_true  # passes if actual is truthy (not nil or false)
+actual.should be_false # passes if actual is falsy (nil or false)
+actual.should be_nil   # passes if actual is nil
+```
+
+### Predicate matchers
+
+```ruby
+actual.should     be_xxx         # passes if actual.xxx?
+actual.should_not have_xxx(:arg) # passes if actual.has_xxx?(:arg)
+```
+
+### Ranges (Ruby >= 1.9 only)
+
+```ruby
+(1..10).should cover(3)
+```
+
+### Collection membership
+
+```ruby
+actual.should include(expected)
+actual.should start_with(expected)
+actual.should end_with(expected)
+```
+
+#### Examples
+
+```ruby
+[1,2,3].should       include(1)
+[1,2,3].should       include(1, 2)
+[1,2,3].should       start_with(1)
+[1,2,3].should       start_with(1,2)
+[1,2,3].should       end_with(3)
+[1,2,3].should       end_with(2,3)
+{:a => 'b'}.should   include(:a => 'b')
+"this string".should include("is str")
+"this string".should start_with("this")
+"this string".should end_with("ring")
+```

data/rspec-expectations/upstream/benchmarks/2.x_vs_3.x_matcher_dsl_implementation.rb

@@ -0,0 +1,253 @@
+$LOAD_PATH.unshift "./lib"
+require 'benchmark'
+require 'rspec/expectations'
+
+include RSpec::Expectations
+include RSpec::Matchers
+
+n = 1000
+
+puts "3 runs of #{n} times for each example running rspec-expectations #{RSpec::Expectations::Version::STRING} -- #{RUBY_ENGINE}/#{RUBY_VERSION}"
+
+puts "Defining a custom matcher"
+Benchmark.benchmark do |bm|
+  3.times do |i|
+    bm.report do
+      n.times do |j|
+        RSpec::Matchers.define :"define_matcher_#{i}_#{j}" do
+          match { }
+        end
+      end
+    end
+  end
+end
+
+puts "Getting an instance of a custom matcher"
+RSpec::Matchers.define :be_a_multiple_of do |x|
+  match { |actual| (actual % x).zero? }
+end
+
+Benchmark.benchmark do |bm|
+  3.times do
+    bm.report do
+      n.times do |i|
+        be_a_multiple_of(i)
+      end
+    end
+  end
+end
+
+puts "Using a previously gotten custom matcher instance -- positive match"
+Benchmark.benchmark do |bm|
+  1.upto(3) do |i|
+    matcher = be_a_multiple_of(i)
+    bm.report do
+      n.times do |j|
+        expect(i * j).to matcher
+      end
+    end
+  end
+end
+
+puts "Using a previously gotten custom matcher instance -- negative match"
+Benchmark.benchmark do |bm|
+  2.upto(4) do |i|
+    matcher = be_a_multiple_of(i)
+    bm.report do
+      n.times do |j|
+        begin
+          expect(1 + i * j).to matcher
+        rescue RSpec::Expectations::ExpectationNotMetError
+        end
+      end
+    end
+  end
+end
+
+=begin
+
+Results are below for:
+
+- MRI 2.0.0, MRI 1.9.3, JRuby 1.7.4
+- Against 2.14.3, 3.0.0.pre before matcher DSL rewrite, 3.0.0.pre after matcher DSL rewrite
+
+Conclusions:
+
+* Getting an instance of a custom matcher was insanely slow in 2.x,
+  and it looks like the `making_declared_methods_public` hack for 1.8.6
+  was the primary source of that. Without that, getting an instance of
+  a matcher is ~20x faster. To see what changed between 2.14.3 and
+  the commit used for this benchmark, go to:
+  https://github.com/rspec/rspec-expectations/compare/v2.14.3...4c47e4c43ee6961c755d325e73181b1f5b6bf097#diff-a51020971ade2c87f1d5b93f20d711c7L6
+* With our new custom matcher DSL, using a matcher is approximately
+  the same perf. However, defining a matcher is a little bit faster,
+  and getting an instance of an already defined matcher is about 10x faster.
+
+Overall, this is definitely a net win.
+
+Results:
+
+3 runs of 1000 times for each example running rspec-expectations 2.14.3 -- ruby/2.0.0
+Defining a custom matcher
+   0.010000   0.000000   0.010000 (  0.004612)
+   0.000000   0.000000   0.000000 (  0.004674)
+   0.000000   0.000000   0.000000 (  0.004944)
+Getting an instance of a custom matcher
+   1.470000   0.010000   1.480000 (  1.472602)
+   1.420000   0.000000   1.420000 (  1.426760)
+   1.440000   0.000000   1.440000 (  1.442283)
+Using a previously gotten custom matcher instance -- positive match
+   0.000000   0.000000   0.000000 (  0.002213)
+   0.000000   0.000000   0.000000 (  0.002019)
+   0.000000   0.000000   0.000000 (  0.001884)
+Using a previously gotten custom matcher instance -- negative match
+   0.020000   0.000000   0.020000 (  0.019378)
+   0.030000   0.000000   0.030000 (  0.027001)
+   0.020000   0.010000   0.030000 (  0.022310)
+
+3 runs of 1000 times for each example running rspec-expectations 2.14.3 -- ruby/1.9.3
+Defining a custom matcher
+    0.000000   0.000000   0.000000 (  0.004455)
+   0.010000   0.000000   0.010000 (  0.004849)
+   0.010000   0.000000   0.010000 (  0.010495)
+Getting an instance of a custom matcher
+    1.690000   0.010000   1.700000 (  1.696415)
+   1.550000   0.000000   1.550000 (  1.556858)
+   1.550000   0.000000   1.550000 (  1.554830)
+Using a previously gotten custom matcher instance -- positive match
+    0.000000   0.000000   0.000000 (  0.002161)
+   0.000000   0.000000   0.000000 (  0.002038)
+   0.010000   0.000000   0.010000 (  0.002091)
+Using a previously gotten custom matcher instance -- negative match
+    0.050000   0.010000   0.060000 (  0.060512)
+   0.050000   0.000000   0.050000 (  0.064532)
+   0.060000   0.010000   0.070000 (  0.062206)
+
+3 runs of 1000 times for each example running rspec-expectations 2.14.3 -- jruby/1.9.3
+Defining a custom matcher
+    0.660000   0.010000   0.670000 (  0.299000)
+   0.280000   0.000000   0.280000 (  0.178000)
+   0.220000   0.010000   0.230000 (  0.143000)
+Getting an instance of a custom matcher
+    1.970000   0.030000   2.000000 (  1.389000)
+   1.340000   0.030000   1.370000 (  0.907000)
+   0.820000   0.030000   0.850000 (  0.795000)
+Using a previously gotten custom matcher instance -- positive match
+    0.110000   0.000000   0.110000 (  0.058000)
+   0.050000   0.000000   0.050000 (  0.036000)
+   0.030000   0.000000   0.030000 (  0.030000)
+Using a previously gotten custom matcher instance -- negative match
+    0.930000   0.010000   0.940000 (  0.474000)
+   0.620000   0.000000   0.620000 (  0.376000)
+   0.390000   0.000000   0.390000 (  0.279000)
+
+3 runs of 1000 times for each example running rspec-expectations 3.0.0.pre (before DSL rewrite) -- ruby/2.0.0
+Defining a custom matcher
+   0.010000   0.000000   0.010000 (  0.004719)
+   0.000000   0.000000   0.000000 (  0.004424)
+   0.010000   0.000000   0.010000 (  0.005562)
+Getting an instance of a custom matcher
+   0.050000   0.000000   0.050000 (  0.059949)
+   0.060000   0.000000   0.060000 (  0.058208)
+   0.060000   0.010000   0.070000 (  0.067402)
+Using a previously gotten custom matcher instance -- positive match
+   0.010000   0.000000   0.010000 (  0.001696)
+   0.000000   0.000000   0.000000 (  0.001558)
+   0.000000   0.000000   0.000000 (  0.001488)
+Using a previously gotten custom matcher instance -- negative match
+   0.020000   0.000000   0.020000 (  0.021522)
+   0.030000   0.000000   0.030000 (  0.027728)
+   0.020000   0.000000   0.020000 (  0.026185)
+
+3 runs of 1000 times for each example running rspec-expectations 3.0.0.pre (before DSL rewrite) -- ruby/1.9.3
+Defining a custom matcher
+    0.010000   0.000000   0.010000 (  0.004650)
+   0.000000   0.000000   0.000000 (  0.004658)
+   0.010000   0.000000   0.010000 (  0.011111)
+Getting an instance of a custom matcher
+    0.050000   0.010000   0.060000 (  0.047230)
+   0.060000   0.000000   0.060000 (  0.065500)
+   0.070000   0.000000   0.070000 (  0.073099)
+Using a previously gotten custom matcher instance -- positive match
+    0.000000   0.000000   0.000000 (  0.002007)
+   0.000000   0.000000   0.000000 (  0.002370)
+   0.010000   0.000000   0.010000 (  0.002121)
+Using a previously gotten custom matcher instance -- negative match
+    0.070000   0.010000   0.080000 (  0.078960)
+   0.060000   0.000000   0.060000 (  0.061351)
+   0.060000   0.000000   0.060000 (  0.069949)
+
+3 runs of 1000 times for each example running rspec-expectations 3.0.0.pre (before DSL rewrite) -- jruby/1.9.3
+Defining a custom matcher
+    0.730000   0.010000   0.740000 (  0.303000)
+   0.240000   0.010000   0.250000 (  0.153000)
+   0.210000   0.000000   0.210000 (  0.140000)
+Getting an instance of a custom matcher
+    0.940000   0.010000   0.950000 (  0.538000)
+   0.510000   0.000000   0.510000 (  0.174000)
+   0.160000   0.000000   0.160000 (  0.090000)
+Using a previously gotten custom matcher instance -- positive match
+    0.120000   0.000000   0.120000 (  0.053000)
+   0.040000   0.000000   0.040000 (  0.025000)
+   0.030000   0.000000   0.030000 (  0.026000)
+Using a previously gotten custom matcher instance -- negative match
+    0.970000   0.010000   0.980000 (  0.458000)
+   0.480000   0.010000   0.490000 (  0.314000)
+   0.360000   0.000000   0.360000 (  0.269000)
+
+3 runs of 1000 times for each example running rspec-expectations 3.0.0.pre -- ruby/2.0.0
+Defining a custom matcher
+   0.000000   0.000000   0.000000 (  0.003138)
+   0.000000   0.000000   0.000000 (  0.003083)
+   0.010000   0.000000   0.010000 (  0.003448)
+Getting an instance of a custom matcher
+   0.000000   0.000000   0.000000 (  0.007273)
+   0.010000   0.000000   0.010000 (  0.007096)
+   0.020000   0.000000   0.020000 (  0.021662)
+Using a previously gotten custom matcher instance -- positive match
+   0.000000   0.000000   0.000000 (  0.002582)
+   0.000000   0.000000   0.000000 (  0.001832)
+   0.010000   0.000000   0.010000 (  0.001588)
+Using a previously gotten custom matcher instance -- negative match
+   0.010000   0.000000   0.010000 (  0.017756)
+   0.030000   0.000000   0.030000 (  0.021225)
+   0.020000   0.010000   0.030000 (  0.021281)
+
+3 runs of 1000 times for each example running rspec-expectations 3.0.0.pre -- ruby/1.9.3
+Defining a custom matcher
+    0.000000   0.000000   0.000000 (  0.002903)
+   0.000000   0.000000   0.000000 (  0.002919)
+   0.010000   0.000000   0.010000 (  0.008956)
+Getting an instance of a custom matcher
+    0.010000   0.000000   0.010000 (  0.006640)
+   0.000000   0.000000   0.000000 (  0.006557)
+   0.010000   0.000000   0.010000 (  0.007869)
+Using a previously gotten custom matcher instance -- positive match
+    0.010000   0.000000   0.010000 (  0.003332)
+   0.000000   0.000000   0.000000 (  0.003288)
+   0.000000   0.000000   0.000000 (  0.002769)
+Using a previously gotten custom matcher instance -- negative match
+    0.070000   0.010000   0.080000 (  0.075547)
+   0.050000   0.000000   0.050000 (  0.053149)
+   0.060000   0.010000   0.070000 (  0.062583)
+
+3 runs of 1000 times for each example running rspec-expectations 3.0.0.pre -- jruby/1.9.3
+Defining a custom matcher
+    0.780000   0.020000   0.800000 (  0.316000)
+   0.170000   0.010000   0.180000 (  0.139000)
+   0.220000   0.000000   0.220000 (  0.135000)
+Getting an instance of a custom matcher
+    0.340000   0.000000   0.340000 (  0.183000)
+   0.230000   0.010000   0.240000 (  0.131000)
+   0.180000   0.000000   0.180000 (  0.104000)
+Using a previously gotten custom matcher instance -- positive match
+    0.170000   0.000000   0.170000 (  0.076000)
+   0.070000   0.000000   0.070000 (  0.049000)
+   0.110000   0.000000   0.110000 (  0.047000)
+Using a previously gotten custom matcher instance -- negative match
+    0.970000   0.010000   0.980000 (  0.461000)
+   0.410000   0.000000   0.410000 (  0.316000)
+   0.350000   0.010000   0.360000 (  0.256000)
+
+=end
+

data/rspec-expectations/upstream/benchmarks/autoload_v_require.rb

@@ -0,0 +1,25 @@
+require 'benchmark'
+
+n = 10
+
+Benchmark.benchmark do |bm|
+  3.times do
+    bm.report do
+      n.times do
+        `bin/rspec benchmarks/example_spec.rb`
+      end
+    end
+  end
+end
+
+# Before autoloading matcher class files
+#    0.000000   0.010000   8.800000 (  8.906383)
+#    0.010000   0.010000   8.880000 (  8.980907)
+#    0.000000   0.010000   8.820000 (  8.918083)
+#
+# After autoloading matcher class files
+#    0.000000   0.010000   8.610000 (  8.701434)
+#    0.010000   0.010000   8.620000 (  8.741811)
+#    0.000000   0.000000   8.580000 (  8.677235)
+#
+# Roughly 2.5% improvement in load time (every bit counts!)

data/rspec-expectations/upstream/benchmarks/cloning_matchers.rb

@@ -0,0 +1,19 @@
+require 'benchmark'
+require 'rspec/expectations'
+include RSpec::Matchers
+
+n = 1_000_000
+matcher = eq(3)
+
+Benchmark.bm do |x|
+  x.report do
+    n.times { matcher.clone }
+  end
+end
+
+__END__
+
+We can do about 1000 clones per ms:
+
+      user     system      total        real
+  1.080000   0.030000   1.110000 (  1.120009)