transpec 1.12.0 → 1.13.0

data/README.md.erb

@@ -107,6 +107,8 @@ Running dynamic analysis with command "bundle exec rspec"...
 Finished in 13.07 seconds
 100 examples, 0 failures
 
+Aggregating spec suite data...
+
 Converting spec/spec_helper.rb
 Converting spec/support/cache_helper.rb
 Converting spec/support/file_helper.rb
@@ -258,6 +260,7 @@ Type             | Target Syntax                  | Converted Syntax
 <%=
 conversion_type_table = <<END
 `example_group`  | `describe 'something' { }`     | `RSpec.describe 'something' { }`
+`hook_scope`     | `before(:all) { }`             | `before(:context) { }`
 `stub_with_hash` | `obj.stub(:message => value)`  | `allow(obj).to receive(:message).and_return(value)`
 END
 
@@ -337,9 +340,7 @@ END
 <%= convert(example).gsub('original spec', 'converted spec') -%>
 
 <%=
-configuration = Transpec::Configuration.new
-configuration.parenthesize_matcher_arg = false
-convert(example, configuration)
+convert(example, cli: ['-p'])
   .gsub(
     'original spec',
     'converted spec with -p/--no-parentheses-matcher-arg option'
@@ -451,16 +452,24 @@ table_of_contents(supported_conversions_section, 3)
 Targets:
 
 ```ruby
+<%=
+positive_example = <<END
 obj.should matcher
+END
+-%>
+<%=
+negative_example = <<END
 obj.should_not matcher
+END
+-%>
 ```
 
 Will be converted to:
 
 ```ruby
-expect(obj).to matcher
-expect(obj).not_to matcher
-expect(obj).to_not matcher # with `--negative-form to_not`
+<%= convert(positive_example, wrap_with: :example) -%>
+<%= convert(negative_example, wrap_with: :example) -%>
+<%= convert(negative_example, wrap_with: :example, cli: ['--negative-form', 'to_not']).chomp -%> # with `--negative-form to_not`
 ```
 
 * This conversion can be disabled by: `--keep should`
@@ -469,21 +478,29 @@ expect(obj).to_not matcher # with `--negative-form to_not`
 
 ### One-liner expectations
 
-**This conversion is available only if your project's RSpec is `<%= Transpec::RSpecVersion.oneliner_is_expected_available_version %>` or later.**
+**This conversion is available only if your project's RSpec is `<%= rspec_version = Transpec::RSpecVersion.oneliner_is_expected_available_version %>` or later.**
 
 Targets:
 
 ```ruby
+<%=
+positive_example = <<END
 it { should matcher }
+END
+-%>
+<%=
+negative_example = <<END
 it { should_not matcher }
+END
+-%>
 ```
 
 Will be converted to:
 
 ```ruby
-it { is_expected.to matcher }
-it { is_expected.not_to matcher }
-it { is_expected.to_not matcher } # with `--negative-form to_not`
+<%= convert(positive_example, wrap_with: :example, rspec_version: rspec_version) -%>
+<%= convert(negative_example, wrap_with: :example, rspec_version: rspec_version) -%>
+<%= convert(negative_example, wrap_with: :example, rspec_version: rspec_version, cli: ['--negative-form', 'to_not']).chomp -%> # with `--negative-form to_not`
 ```
 
 `is_expected.to` is designed for the consistency with the `expect` syntax.
@@ -495,7 +512,7 @@ feel free to disable this conversion and continue using the one-liner `should`.
 See [Two Types of `should`](#two-types-of-should) also.
 
 * This conversion can be disabled by: `--keep oneliner`
-* Deprecation: Not deprecated
+* Deprecation: not deprecated
 * See also: [Add `is_expected` for expect-based one-liner syntax. by myronmarston · rspec/rspec-core](https://github.com/rspec/rspec-core/pull/1180)
 
 ### Operator matchers
@@ -503,21 +520,21 @@ See [Two Types of `should`](#two-types-of-should) also.
 Targets:
 
 ```ruby
+<%=
+example = <<END
 1.should == 1
 1.should < 2
 Integer.should === 1
 'string'.should =~ /^str/
 [1, 2, 3].should =~ [2, 1, 3]
+END
+-%>
 ```
 
 Will be converted to:
 
 ```ruby
-expect(1).to eq(1)
-expect(1).to be < 2
-expect(Integer).to be === 1
-expect('string').to match(/^str/)
-expect([1, 2, 3]).to match_array([2, 1, 3])
+<%= convert(example, wrap_with: :example) -%>
 ```
 
 This conversion is combined with the conversion of [standard expectations](#standard-expecatations) and cannot be disabled separately because the `expect` syntax does not directly support the operator matchers.
@@ -526,29 +543,30 @@ This conversion is combined with the conversion of [standard expectations](#stan
 
 ### Boolean matchers
 
-**This conversion is available only if your project's RSpec is `<%= Transpec::RSpecVersion.be_truthy_available_version %>` or later.**
+**This conversion is available only if your project's RSpec is `<%= rspec_version = Transpec::RSpecVersion.be_truthy_available_version %>` or later.**
 
 Targets:
 
 ```ruby
+<%=
+example = <<END
 expect(obj).to be_true
 expect(obj).to be_false
+END
+-%>
 ```
 
 Will be converted to:
 
 ```ruby
-expect(obj).to be_truthy
-expect(obj).to be_falsey
+<%= convert(example, rspec_version: rspec_version, wrap_with: :example) -%>
 
 # With `--boolean-matcher truthy,falsy`
 # be_falsy is just an alias of be_falsey.
-expect(obj).to be_truthy
-expect(obj).to be_falsy
+<%= convert(example, cli: ['--boolean-matcher', 'truthy,falsy'], rspec_version: rspec_version, wrap_with: :example) -%>
 
 # With `--boolean-matcher true,false`
-expect(obj).to be true
-expect(obj).to be false
+<%= convert(example, cli: ['--boolean-matcher', 'true,false'], rspec_version: rspec_version, wrap_with: :example) -%>
 ```
 
 * `be_true` matcher passes if expectation subject is _truthy_ in conditional semantics. (i.e. all objects except `false` and `nil`)
@@ -569,13 +587,17 @@ So, converting `be_true`/`be_false` to `be_truthy`/`be_falsey` never breaks your
 Targets:
 
 ```ruby
+<%=
+example = <<END
 expect(1.0 / 3.0).to be_close(0.333, 0.001)
+END
+-%>
 ```
 
 Will be converted to:
 
 ```ruby
-expect(1.0 / 3.0).to be_within(0.001).of(0.333)
+<%= convert(example, wrap_with: :example) -%>
 ```
 
 * This conversion can be disabled by: `--keep deprecated`
@@ -589,31 +611,74 @@ expect(1.0 / 3.0).to be_within(0.001).of(0.333)
 Targets:
 
 ```ruby
+<%=
+example = <<END
 expect(collection).to have(3).items
 expect(collection).to have_exactly(3).items
 expect(collection).to have_at_least(3).items
 expect(collection).to have_at_most(3).items
+END
+-%>
+
+<%=
+should_example = <<END
 collection.should have(3).items
+END
+-%>
 
 # Assume `team` responds to #players.
+<%=
+collection_owner_example = <<END
 expect(team).to have(3).players
+END
+-%>
 
 # Assume #players is a private method.
+<%=
+private_method_example = <<END
 expect(team).to have(3).players
+END
+-%>
 ```
 
 Will be converted to:
 
 ```ruby
-expect(collection.size).to eq(3)
-expect(collection.size).to be >= 3
-expect(collection.size).to be <= 3
-collection.size.should == 3  # with `--keep should`
+<%=
+convert(example, dynamic: true, wrap_with: :example, hidden: 'collection = [1, 2, 3]')
+-%>
+
+<%=
+" # With `--keep should`\n" +
+convert(should_example, cli: ['--keep', 'should'], dynamic: true, wrap_with: :example, hidden: 'collection = [1, 2, 3]')
+-%>
 
-expect(team.players.size).to eq(3)
+<%=
+convert(collection_owner_example, dynamic: true, wrap_with: :example, hidden: <<END)
+class Team
+  def players
+    [1, 2, 3]
+  end
+end
+
+team = Team.new
+END
+-%>
 
 # have(n).items matcher invokes #players even if it's a private method.
-expect(team.send(:players).size).to eq(3)
+<%=
+convert(private_method_example, dynamic: true, wrap_with: :example, hidden: <<END)
+class Team
+  private
+
+  def players
+    [1, 2, 3]
+  end
+end
+
+team = Team.new
+END
+-%>
 ```
 
 There's an option to continue using `have(n).items` matcher with [rspec-collection_matchers](https://github.com/rspec/rspec-collection_matchers) which is a gem extracted from `rspec-expectations`.
@@ -637,25 +702,39 @@ Note: `rspec-rails` 3.0 [still uses `have(n).items` matcher with `rspec-collecti
 Targets:
 
 ```ruby
+<%=
+example = <<END
 it { should have(3).items }
+END
+-%>
+<%=
+collection_owner_example = <<END
 it { should have_at_least(3).players }
+END
+-%>
 ```
 
 Will be converted to:
 
 ```ruby
-it 'has 3 items' do
-  expect(subject.size).to eq(3)
-end
+<%= convert(example, dynamic: true, wrap_with: :group, hidden: 'subject { [1, 2, 3] }') -%>
 
 # With `--keep should`
-it 'has 3 items' do
-  subject.size.should == 3
-end
+<%= convert(example, dynamic: true, wrap_with: :group, hidden: 'subject { [1, 2, 3] }', cli: ['--keep', 'should']) -%>
 
-it 'has at least 3 players' do
-  expect(subject.players.size).to be >= 3
+<%=
+convert(collection_owner_example, dynamic: true, wrap_with: :group, hidden: <<END)
+subject do
+  class Team
+    def players
+      [1, 2, 3]
+    end
+  end
+
+  Team.new
 end
+END
+-%>
 ```
 
 * This conversion can be disabled by: `--keep have_items`
@@ -665,15 +744,19 @@ end
 Targets:
 
 ```ruby
+<%=
+example = <<END
 lambda { do_something }.should raise_error
 proc { do_something }.should raise_error
 -> { do_something }.should raise_error
+END
+-%>
 ```
 
 Will be converted to:
 
 ```ruby
-expect { do_something }.to raise_error
+<%= convert(example, wrap_with: :example).lines.to_a.uniq.join("\n") -%>
 ```
 
 * This conversion can be disabled by: `--keep should`
@@ -722,17 +805,25 @@ If you choose to do so, disable this conversion by either:
 Targets:
 
 ```ruby
+<%=
+example = <<END
 expect { do_something }.not_to raise_error(SomeErrorClass)
 expect { do_something }.not_to raise_error('message')
 expect { do_something }.not_to raise_error(SomeErrorClass, 'message')
+END
+-%>
+<%=
+should_example = <<END
 lambda { do_something }.should_not raise_error(SomeErrorClass)
+END
+-%>
 ```
 
 Will be converted to:
 
 ```ruby
-expect { do_something }.not_to raise_error
-lambda { do_something }.should_not raise_error # with `--keep should`
+<%= convert(example, wrap_with: :example).lines.to_a.uniq.join("\n") -%>
+<%= convert(should_example, wrap_with: :example, cli: ['--keep', 'should']).chomp -%> # with `--keep should`
 ```
 
 * This conversion can be disabled by: `--keep deprecated`
@@ -744,15 +835,18 @@ lambda { do_something }.should_not raise_error # with `--keep should`
 Targets:
 
 ```ruby
+<%=
+example = <<END
 obj.should_receive(:message)
 Klass.any_instance.should_receive(:message)
+END
+-%>
 ```
 
 Will be converted to:
 
 ```ruby
-expect(obj).to receive(:message)
-expect_any_instance_of(Klass).to receive(:message)
+<%= convert(example, wrap_with: :example) -%>
 ```
 
 * This conversion can be disabled by: `--keep should_receive`
@@ -764,21 +858,29 @@ expect_any_instance_of(Klass).to receive(:message)
 Targets:
 
 ```ruby
+<%=
+example = <<END
 obj.should_receive(:message).any_number_of_times
 obj.should_receive(:message).at_least(0)
+END
+-%>
 
+<%=
+any_instance_example = <<END
 Klass.any_instance.should_receive(:message).any_number_of_times
 Klass.any_instance.should_receive(:message).at_least(0)
+END
+-%>
 ```
 
 Will be converted to:
 
 ```ruby
-allow(obj).to receive(:message)
-obj.stub(:message) # with `--keep stub`
+<%= convert(example, wrap_with: :example).lines.to_a.uniq.join("\n") -%>
+<%= convert(example, wrap_with: :example, cli: ['--keep', 'stub']).lines.to_a.uniq.join("\n").chomp -%> # with `--keep stub`
 
-allow_any_instance_of(Klass).to receive(:message)
-Klass.any_instance.stub(:message) # with `--keep stub`
+<%= convert(any_instance_example, wrap_with: :example).lines.to_a.uniq.join("\n") -%>
+<%= convert(any_instance_example, wrap_with: :example, cli: ['--keep', 'stub']).lines.to_a.uniq.join("\n").chomp -%> # with `--keep stub`
 ```
 
 * This conversion can be disabled by: `--keep deprecated`
@@ -790,29 +892,45 @@ Klass.any_instance.stub(:message) # with `--keep stub`
 Targets:
 
 ```ruby
+<%=
+example = <<END
 obj.stub(:message)
 obj.stub!(:message)
+END
+-%>
 
+<%=
+stub_chain_example = <<END
 obj.stub_chain(:foo, :bar, :baz)
+END
+-%>
 
+<%=
+any_instance_example = <<END
 Klass.any_instance.stub(:message)
+END
+-%>
 
+<%=
+unstub_example = <<END
 obj.unstub(:message)
 obj.unstub!(:message)
+END
+-%>
 ```
 
 Will be converted to:
 
 ```ruby
-allow(obj).to receive(:message)
+<%= convert(example, wrap_with: :example).lines.to_a.uniq.join("\n") -%>
 
 # Conversion from `stub_chain` to `receive_message_chain` is available
-# only if the target project's RSpec is <%= Transpec::RSpecVersion.receive_message_chain_available_version %> or later
-allow(obj).to receive_message_chain(:foo, :bar, :baz)
+# only if the target project's RSpec is <%= rspec_version = Transpec::RSpecVersion.receive_message_chain_available_version %> or later
+<%= convert(stub_chain_example, wrap_with: :example, rspec_version: rspec_version) -%>
 
-allow_any_instance_of(Klass).to receive(:message)
+<%= convert(any_instance_example, wrap_with: :example) -%>
 
-allow(obj).to receive(:message).and_call_original
+<%= convert(unstub_example, wrap_with: :example).lines.to_a.uniq.join("\n") -%>
 ```
 
 * This conversion can be disabled by: `--keep stub`
@@ -826,22 +944,25 @@ allow(obj).to receive(:message).and_call_original
 Targets:
 
 ```ruby
+<%=
+example = <<END
 obj.stub(:foo => 1, :bar => 2)
+END
+-%>
 ```
 
 Will be converted to:
 
 ```ruby
-# If the target project's RSpec is <%= Transpec::RSpecVersion.receive_messages_available_version %> or later
-allow(obj).to receive_messages(:foo => 1, :bar => 2)
+# If the target project's RSpec is <%= rspec_version = Transpec::RSpecVersion.receive_messages_available_version %> or later
+<%= convert(example, wrap_with: :example, rspec_version: rspec_version) -%>
 
 # If the target project's RSpec is prior to <%= Transpec::RSpecVersion.receive_messages_available_version %>
-obj.stub(:foo => 1, :bar => 2) # No conversion
+<%= convert(example, wrap_with: :example, rspec_version: Transpec.required_rspec_version).chomp -%> # No conversion
 
 # If the target project's RSpec is prior to <%= Transpec::RSpecVersion.receive_messages_available_version %>
-# and `--convert-stub-with-hash` is specified
-allow(obj).to receive(:foo).and_return(1)
-allow(obj).to receive(:bar).and_return(2)
+# and `--convert stub-with-hash` is specified
+<%= convert(example, wrap_with: :example, rspec_version: Transpec.required_rspec_version, cli: ['--convert', 'stub_with_hash']) -%>
 ```
 
 `allow(obj).to receive_messages(:foo => 1, :bar => 2)` which is designed to be the replacement for `obj.stub(:foo => 1, :bar => 2)` is available from RSpec 3.0.
@@ -864,15 +985,19 @@ Or if you're going to stay RSpec 2.14 for now but want to convert all `stub` to
 Targets:
 
 ```ruby
+<%=
+example = <<END
 obj.stub!(:message)
 obj.unstub!(:message)
+END
+-%>
 ```
 
 Will be converted to:
 
 ```ruby
-obj.stub(:message) # with `--keep stub`
-obj.unstub(:message) # with `--keep stub`
+# With `--keep stub`
+<%= convert(example, wrap_with: :example, cli: ['--keep', 'stub']) -%>
 ```
 
 * This conversion can be disabled by: `--keep deprecated`
@@ -884,15 +1009,19 @@ obj.unstub(:message) # with `--keep stub`
 Targets:
 
 ```ruby
+<%=
+example = <<END
 obj.stub(:message).any_number_of_times
 obj.stub(:message).at_least(0)
+END
+-%>
 ```
 
 Will be converted to:
 
 ```ruby
-allow(obj).to receive(:message)
-obj.stub(:message) # with `--keep stub`
+<%= convert(example, wrap_with: :example).lines.to_a.uniq.join("\n") -%>
+<%= convert(example, wrap_with: :example, cli: ['--keep', 'stub']).lines.to_a.uniq.join("\n").chomp -%> # with `--keep stub`
 ```
 
 * This conversion can be disabled by: `--keep deprecated`
@@ -918,7 +1047,7 @@ END
 Will be converted to:
 
 ```ruby
-<%= convert(example) -%>
+<%= convert(example, wrap_with: :example) -%>
 ```
 
 * This conversion can be disabled by: `--keep deprecated`
@@ -952,18 +1081,11 @@ END
 Will be converted to:
 
 ```ruby
-<%=
-rspec_version = Transpec::RSpecVersion.yielding_receiver_to_any_instance_implementation_block_available_version
-convert(example, nil, rspec_version)
--%>
+<% rspec_version = Transpec::RSpecVersion.yielding_receiver_to_any_instance_implementation_block_available_version -%>
+<%= convert(example, rspec_version: rspec_version) -%>
 
 # With `--no-yield-any-instance`
-<%=
-configuration = Transpec::Configuration.new
-configuration.add_receiver_arg_to_any_instance_implementation_block = false
-rspec_version = Transpec::RSpecVersion.yielding_receiver_to_any_instance_implementation_block_available_version
-convert(example, configuration, rspec_version)
--%>
+<%= convert(example, cli: ['--no-yield-any-instance'], rspec_version: rspec_version) -%>
 ```
 
 Here's an excerpt from [the warning](https://github.com/rspec/rspec-mocks/blob/aab8dc9/lib/rspec/mocks/message_expectation.rb#L478-L491) for `any_instance` implementation blocks in RSpec 2.99:
@@ -994,14 +1116,18 @@ Here's an excerpt from [the warning](https://github.com/rspec/rspec-mocks/blob/a
 Targets:
 
 ```ruby
+<%=
+example = <<END
 stub('something')
 mock('something')
+END
+-%>
 ```
 
 Will be converted to:
 
 ```ruby
-double('something')
+<%= convert(example, wrap_with: :example).lines.to_a.uniq.join("\n") -%>
 ```
 
 * This conversion can be disabled by: `--keep deprecated`
@@ -1045,8 +1171,7 @@ Will be converted to:
 
 ```ruby
 <%=
-rspec_version = Transpec::RSpecVersion.skip_available_version
-convert(example, nil, rspec_version)
+convert(example, rspec_version: Transpec::RSpecVersion.skip_available_version)
   .gsub('pending', 'pending # #pending with block is no longer supported')
 -%>
 ```
@@ -1069,7 +1194,7 @@ Here's an excerpt from [the warning](https://github.com/rspec/rspec-core/blob/v2
 
 ### Current example object
 
-**This conversion is available only if your project's RSpec is `<%= Transpec::RSpecVersion.yielded_example_available_version %>` or later.**
+**This conversion is available only if your project's RSpec is `<%= rspec_version = Transpec::RSpecVersion.yielded_example_available_version %>` or later.**
 
 Targets:
 
@@ -1096,10 +1221,7 @@ END
 Will be converted to:
 
 ```ruby
-<%=
-rspec_version = Transpec::RSpecVersion.yielded_example_available_version
-convert(example, nil, rspec_version)
--%>
+<%= convert(example, rspec_version: rspec_version) -%>
 ```
 
 Here's an excerpt from [the warning](https://github.com/rspec/rspec-core/blob/7d6d2ca/lib/rspec/core/example_group.rb#L513-L527) for `RSpec::Core::ExampleGroup#example` and `#running_example` in RSpec 2.99:
@@ -1124,7 +1246,7 @@ Here's an excerpt from [the warning](https://github.com/rspec/rspec-core/blob/7d
 
 ### Custom matcher DSL
 
-**This conversion is available only if your project's RSpec is `<%= Transpec::RSpecVersion.non_should_matcher_protocol_available_version %>` or later.**
+**This conversion is available only if your project's RSpec is `<%= rspec_version = Transpec::RSpecVersion.non_should_matcher_protocol_available_version %>` or later.**
 
 Targets:
 
@@ -1144,19 +1266,16 @@ END
 Will be converted to:
 
 ```ruby
-<%=
-rspec_version = Transpec::RSpecVersion.non_should_matcher_protocol_available_version
-convert(example, nil, rspec_version)
--%>
+<%= convert(example, rspec_version: rspec_version) -%>
 ```
 
 * This conversion can be disabled by: `--keep deprecated`
 * Deprecation: deprecated since RSpec 3.0
 * See also: [Expectations: Matcher protocol and custom matcher API changes - The Plan for RSpec 3](http://myronmars.to/n/dev-blog/2013/07/the-plan-for-rspec-3#expectations_matcher_protocol_and_custom_matcher_api_changes)
 
-### Example Groups
+### Example groups
 
-**This conversion is disabled by default and available only if your project's RSpec is `<%= Transpec::RSpecVersion.non_monkey_patch_example_group_available_version %>` or later.**
+**This conversion is disabled by default and available only if your project's RSpec is `<%= rspec_version = Transpec::RSpecVersion.non_monkey_patch_example_group_available_version %>` or later.**
 
 Targets:
 
@@ -1180,18 +1299,44 @@ END
 Will be converted to:
 
 ```ruby
-<%=
-configuration = Transpec::Configuration.new
-configuration.convert_example_group = true
-rspec_version = Transpec::RSpecVersion.non_monkey_patch_example_group_available_version
-convert(example, configuration, rspec_version)
--%>
+<%= convert(example, cli: ['--convert', 'example_group'], rspec_version: rspec_version) -%>
 ```
 
 * This conversion can be enabled by: `--convert example_group`
-* Deprecation: Not deprecated
+* Deprecation: not deprecated
 * See also: [Zero Monkey Patching Mode! - The Plan for RSpec 3](http://myronmars.to/n/dev-blog/2013/07/the-plan-for-rspec-3#zero_monkey_patching_mode)
 
+### Hook scope aliases
+
+**This conversion is disabled by default and available only if your project's RSpec is `<%= rspec_version = Transpec::RSpecVersion.hook_scope_alias_available_version %>` or later.**
+
+Targets:
+
+```ruby
+<%=
+example = <<END
+describe 'example' do
+  before { do_something }
+  before(:each) { do_something }
+  before(:all) { do_something }
+end
+
+RSpec.configure do |config|
+  before(:suite) { do_something }
+end
+END
+-%>
+```
+
+Will be converted to:
+
+```ruby
+<%= convert(example, cli: ['--convert', 'hook_scope'], rspec_version: rspec_version) -%>
+```
+
+* This conversion can be enabled by: `--convert hook_scope`
+* Deprecation: not deprecated
+* See also: [Adds hook scope aliases `example` and `context` · rspec/rspec-core](https://github.com/rspec/rspec-core/pull/1174)
 
 ## Compatibility