transpec 1.5.1 → 1.6.0

data/README.md.erb

@@ -4,7 +4,7 @@
 
 **Transpec** is a tool for converting your specs to the latest [RSpec](http://rspec.info/) syntax with static and dynamic code analysis.
 
-This aims to facilitate smooth transition to RSpec 3, and it's now ready for RSpec 2.99 and 3.0 beta!
+This aims to facilitate a smooth transition to RSpec 3, and it's now ready for RSpec 2.99 and 3.0 beta!
 
 See the following pages for the new RSpec syntax and the plan for RSpec 3:
 
@@ -12,8 +12,8 @@ See the following pages for the new RSpec syntax and the plan for RSpec 3:
 * [RSpec's new message expectation syntax - Tea is awesome.](http://teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/)
 * [Myron Marston » The Plan for RSpec 3](http://myronmars.to/n/dev-blog/2013/07/the-plan-for-rspec-3)
 
-Transpec now supports almost all conversions for the RSpec changes,
-but the changes for RSpec 3 is not fixed and may vary in the future.
+Transpec now supports conversions for almost all of the RSpec 3 changes,
+but the changes are not fixed and may vary in the future.
 So it's recommended to follow updates of both RSpec and Transpec.
 
 ## Examples
@@ -88,7 +88,7 @@ Before converting your specs:
 
 * Make sure your project has `rspec` gem dependency **<%= Transpec.required_rspec_version %>** or later. If not, change your `*.gemspec` or `Gemfile` to do so.
 * Run `rspec` and check if all the specs pass.
-* Ensure the Git repository is clean. (You don't want to mix up your changes and Transpec's changes, right?)
+* Ensure the Git repository is clean. (You don't want to mix up your changes and Transpec's changes, do you?)
 
 Then, run `transpec` in the project root directory:
 
@@ -157,7 +157,7 @@ Skip dynamic analysis and convert with only static analysis. Note that specifyin
 Specify a command to run your specs that is used for dynamic analysis.
 
 Transpec needs to run your specs in a copied project directory for dynamic analysis.
-If your project requires some special setups or commands to run specs, use this option.
+If your project requires some special setup or commands to run specs, use this option.
 `bundle exec rspec` is used by default.
 
 ```bash
@@ -327,31 +327,39 @@ Then run `transpec` again.
 
 ### Standard expectations
 
+Targets:
+
 ```ruby
-# Targets
 obj.should matcher
 obj.should_not matcher
+```
+
+Will be converted to:
 
-# Converted
+```ruby
 expect(obj).to matcher
 expect(obj).not_to matcher
 expect(obj).to_not matcher # with `--negative-form to_not`
 ```
 
-* Conversion can be disabled by: `--keep should`
-* Deprecation: Deprecated since RSpec 3.0
+* This conversion can be disabled by: `--keep should`
+* Deprecation: deprecated since RSpec 3.0
 * See also: [Myron Marston » RSpec's New Expectation Syntax](http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax)
 
 ### One-liner expectations
 
-**This conversion is available only if your project has `rspec` gem dependency `<%= Transpec::RSpecVersion.one_liner_is_expected_available_version %>` or later.**
+**This conversion is available only if your project's RSpec is `<%= Transpec::RSpecVersion.oneliner_is_expected_available_version %>` (not yet released) or later.**
+
+Targets:
 
 ```ruby
-# Targets
 it { should matcher }
 it { should_not matcher }
+```
 
-# Converted
+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`
@@ -363,21 +371,25 @@ and available even if the `should` syntax is disabled with `RSpec.configure`.
 So if you think `is_expected.to` is verbose,
 feel free to disable this conversion and continue using the one-liner `should`.
 
-* Conversion can be disabled by: `--keep oneliner`
+* This conversion can be disabled by: `--keep oneliner`
 * 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
 
+Targets:
+
 ```ruby
-# Targets
 1.should == 1
 1.should < 2
 Integer.should === 1
 'string'.should =~ /^str/
 [1, 2, 3].should =~ [2, 1, 3]
+```
+
+Will be converted to:
 
-# Converted
+```ruby
 expect(1).to eq(1)
 expect(1).to be < 2
 expect(Integer).to be === 1
@@ -391,14 +403,18 @@ This conversion is combined with the conversion of [standard expectations](#stan
 
 ### Boolean matchers
 
-**This conversion is available only if your project has `rspec` gem dependency `<%= Transpec::RSpecVersion.be_truthy_available_version %>` or later.**
+**This conversion is available only if your project's RSpec is `<%= Transpec::RSpecVersion.be_truthy_available_version %>` or later.**
+
+Targets:
 
 ```ruby
-# Targets
 expect(obj).to be_true
 expect(obj).to be_false
+```
 
-# Converted
+Will be converted to:
+
+```ruby
 expect(obj).to be_truthy
 expect(obj).to be_falsey
 
@@ -417,34 +433,39 @@ expect(obj).to be false
 * `be_truthy` and `be_falsey` matchers are renamed version of `be_true` and `be_false` and their behaviors are same.
 * `be true` and `be false` are not new things. These are combinations of `be` matcher and boolean literals. These pass if expectation subject is exactly equal to boolean value.
 
-So, converting `be_true`/`be_false` to `be_truthy`/`be_falsey` never breaks your specs and this is the Transpec's default. If you are willing to test boolean values strictly, you can convert them to `be true`/`be false` with `--boolean-matcher true,false` option. Note that this may break your specs if your application codes don't return exact boolean values.
+So, converting `be_true`/`be_false` to `be_truthy`/`be_falsey` never breaks your specs and this is Transpec's default. If you are willing to test boolean values strictly, you can convert them to `be true`/`be false` with `--boolean-matcher true,false` option. Note that this may break your specs if your application code don't return exact boolean values.
 
 ---
 
-* Conversion can be disabled by: `--keep deprecated`
-* Deprecation: Deprecated since RSpec 2.99, removed in RSpec 3.0
+* This conversion can be disabled by: `--keep deprecated`
+* Deprecation: deprecated since RSpec 2.99, removed in RSpec 3.0
 * See also: [Consider renaming `be_true` and `be_false` to `be_truthy` and `be_falsey` · rspec/rspec-expectations](https://github.com/rspec/rspec-expectations/issues/283)
 
 ### `be_close` matcher
 
+Targets:
+
 ```ruby
-# Targets
 expect(1.0 / 3.0).to be_close(0.333, 0.001)
+```
+
+Will be converted to:
 
-# Converted
+```ruby
 expect(1.0 / 3.0).to be_within(0.001).of(0.333)
 ```
 
-* Conversion can be disabled by: `--keep deprecated`
-* Deprecation: Deprecated since RSpec 2.1, removed in RSpec 3.0
+* This conversion can be disabled by: `--keep deprecated`
+* Deprecation: deprecated since RSpec 2.1, removed in RSpec 3.0
 * See also: [New be within matcher and RSpec.deprecate fix · rspec/rspec-expectations](https://github.com/rspec/rspec-expectations/pull/32)
 
 ### `have(n).items` matcher
 
 **This conversion will be disabled automatically if `rspec-collection_matchers` or `rspec-rails` is loaded in your spec.**
 
+Targets:
+
 ```ruby
-# Targets
 expect(collection).to have(3).items
 expect(collection).to have_exactly(3).items
 expect(collection).to have_at_least(3).items
@@ -456,8 +477,11 @@ expect(team).to have(3).players
 
 # Assume #players is a private method.
 expect(team).to have(3).players
+```
 
-# Converted
+Will be converted to:
+
+```ruby
 expect(collection.size).to eq(3)
 expect(collection.size).to be >= 3
 expect(collection.size).to be <= 3
@@ -469,8 +493,8 @@ expect(team.players.size).to eq(3)
 expect(team.send(:players).size).to eq(3)
 ```
 
-There's an option to continue using `have(n).items` matcher with [rspec-collection_matchers](https://github.com/rspec/rspec-collection_matchers) that is a gem extracted from `rspec-expectations`.
-If you choose so, disable this conversion by either:
+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`.
+If you choose to do so, disable this conversion by either:
 
 * Specify `--keep have_items` option manually.
 * Require `rspec-collection_matchers` or `rspec-rails` in your spec so that Transpec automatically disables this conversion.
@@ -479,20 +503,24 @@ Note: `rspec-rails` 3.0 [still uses `have(n).items` matcher with `rspec-collecti
 
 ---
 
-* Conversion can be disabled by: `--keep have_items`
-* Deprecation: Deprecated since RSpec 2.99, removed in RSpec 3.0
+* This conversion can be disabled by: `--keep have_items`
+* Deprecation: deprecated since RSpec 2.99, removed in RSpec 3.0
 * See also: [Expectations: have(x).items matchers will be moved into an external gem - The Plan for RSpec 3](http://myronmars.to/n/dev-blog/2013/07/the-plan-for-rspec-3#expectations__matchers_will_be_moved_into_an_external_gem)
 
 ### One-liner expectations with `have(n).items` matcher
 
 **This conversion will be disabled automatically if `rspec-collection_matchers` or `rspec-rails` is loaded in your spec.**
 
+Targets:
+
 ```ruby
-# Targets
 it { should have(3).items }
 it { should have_at_least(3).players }
+```
+
+Will be converted to:
 
-# Converted
+```ruby
 it 'has 3 items' do
   expect(subject.size).to eq(3)
 end
@@ -507,69 +535,85 @@ it 'has at least 3 players' do
 end
 ```
 
-* Conversion can be disabled by: `--keep have_items`
+* This conversion can be disabled by: `--keep have_items`
 
 ### Expectations on block
 
+Targets:
+
 ```ruby
-# Targets
 lambda { do_something }.should raise_error
 proc { do_something }.should raise_error
 -> { do_something }.should raise_error
+```
+
+Will be converted to:
 
-# Converted
+```ruby
 expect { do_something }.to raise_error
 ```
 
-* Conversion can be disabled by: `--keep should`
-* Deprecation: Deprecated since RSpec 3.0
+* This conversion can be disabled by: `--keep should`
+* Deprecation: deprecated since RSpec 3.0
 * See also: [Unification of Block vs. Value Syntaxes - RSpec's New Expectation Syntax](http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax#unification_of_block_vs_value_syntaxes)
 
 ### Negative error expectations with specific error
 
+Targets:
+
 ```ruby
-# Targets
 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')
 lambda { do_something }.should_not raise_error(SomeErrorClass)
+```
+
+Will be converted to:
 
-# Converted
+```ruby
 expect { do_something }.not_to raise_error
 lambda { do_something }.should_not raise_error # with `--keep should`
 ```
 
-* Conversion can be disabled by: `--keep deprecated`
-* Deprecation: Deprecated since RSpec 2.14, removed in RSpec 3.0
+* This conversion can be disabled by: `--keep deprecated`
+* Deprecation: deprecated since RSpec 2.14, removed in RSpec 3.0
 * See also: [Consider deprecating `expect { }.not_to raise_error(SpecificErrorClass)` · rspec/rspec-expectations](https://github.com/rspec/rspec-expectations/issues/231)
 
 ### Message expectations
 
+Targets:
+
 ```ruby
-# Targets
 obj.should_receive(:foo)
 Klass.any_instance.should_receive(:foo)
+```
 
-# Converted
+Will be converted to:
+
+```ruby
 expect(obj).to receive(:foo)
 expect_any_instance_of(Klass).to receive(:foo)
 ```
 
-* Conversion can be disabled by: `--keep should_receive`
-* Deprecation: Deprecated since RSpec 3.0
+* This conversion can be disabled by: `--keep should_receive`
+* Deprecation: deprecated since RSpec 3.0
 * See also: [RSpec's new message expectation syntax - Tea is awesome.](http://teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/)
 
 ### Message expectations that are actually method stubs
 
+Targets:
+
 ```ruby
-# Targets
 obj.should_receive(:foo).any_number_of_times
 obj.should_receive(:foo).at_least(0)
 
 Klass.any_instance.should_receive(:foo).any_number_of_times
 Klass.any_instance.should_receive(:foo).at_least(0)
+```
+
+Will be converted to:
 
-# Converted
+```ruby
 allow(obj).to receive(:foo)
 obj.stub(:foo) # with `--keep stub`
 
@@ -577,14 +621,15 @@ allow_any_instance_of(Klass).to receive(:foo)
 Klass.any_instance.stub(:foo) # with `--keep stub`
 ```
 
-* Conversion can be disabled by: `--keep deprecated`
-* Deprecation: Deprecated since RSpec 2.14, removed in RSpec 3.0
+* This conversion can be disabled by: `--keep deprecated`
+* Deprecation: deprecated since RSpec 2.14, removed in RSpec 3.0
 * See also: [Don't allow at_least(0) · rspec/rspec-mocks](https://github.com/rspec/rspec-mocks/issues/133)
 
 ### Method stubs
 
+Targets:
+
 ```ruby
-# Targets
 obj.stub(:foo)
 obj.stub!(:foo)
 
@@ -593,19 +638,22 @@ obj.stub(:foo => 1, :bar => 2)
 obj.stub_chain(:foo, :bar, :baz)
 
 Klass.any_instance.stub(:foo)
+```
 
-# Converted
+Will be converted to:
+
+```ruby
 allow(obj).to receive(:foo)
 
-# If the target project's rspec gem dependency is prior to <%= Transpec::RSpecVersion.receive_messages_available_version %>
+# If the target project's RSpec is prior to <%= Transpec::RSpecVersion.receive_messages_available_version %>
 allow(obj).to receive(:foo).and_return(1)
 allow(obj).to receive(:bar).and_return(2)
 
-# If the target project's rspec gem dependency is <%= Transpec::RSpecVersion.receive_messages_available_version %> or later
+# If the target project's RSpec is <%= Transpec::RSpecVersion.receive_messages_available_version %> or later
 allow(obj).to receive_messages(:foo => 1, :bar => 2)
 
 # Conversion from `stub_chain` to `receive_message_chain` is available
-# only if the target project's rspec gem dependency is <%= Transpec::RSpecVersion.receive_message_chain_available_version %> or later
+# only if the target project's RSpec is <%= Transpec::RSpecVersion.receive_message_chain_available_version %> (not yet released) or later
 allow(obj).to receive_message_chain(:foo, :bar, :baz)
 
 allow_any_instance_of(Klass).to receive(:foo)
@@ -613,7 +661,7 @@ allow_any_instance_of(Klass).to receive(:foo)
 
 #### No replacement for `unstub`
 
-There's no replacement for `unstub` in the `expect` syntax. See [the discussion](https://github.com/rspec/rspec-mocks/issues/153#issuecomment-12208638) for more details.
+There's no replacement for `unstub` in the `expect` syntax. See [this discussion](https://github.com/rspec/rspec-mocks/issues/153#issuecomment-12208638) for more details.
 
 #### Steps to upgrade `obj.stub(:foo => 1, :bar => 2)`
 
@@ -628,8 +676,8 @@ Otherwise `obj.stub(:foo => 1, :bar => 2)` will be converted to two `allow(obj).
 
 ---
 
-* Conversion can be disabled by: `--keep stub`
-* Deprecation: Deprecated since RSpec 3.0
+* This conversion can be disabled by: `--keep stub`
+* Deprecation: deprecated since RSpec 3.0
 * See also:
     * [RSpec's new message expectation syntax - Tea is awesome.](http://teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/)
     * [allow receive with multiple methods · rspec/rspec-mocks](https://github.com/rspec/rspec-mocks/issues/368)
@@ -637,57 +685,70 @@ Otherwise `obj.stub(:foo => 1, :bar => 2)` will be converted to two `allow(obj).
 
 ### Deprecated method stub aliases
 
+Targets:
+
 ```ruby
-# Targets
 obj.stub!(:foo)
 obj.unstub!(:foo)
+```
+
+Will be converted to:
 
-# Converted
+```ruby
 obj.stub(:foo) # with `--keep stub`
 obj.unstub(:foo)
 ```
 
-* Conversion can be disabled by: `--keep deprecated`
-* Deprecation: Deprecated since RSpec 2.14, removed in RSpec 3.0
+* This conversion can be disabled by: `--keep deprecated`
+* Deprecation: deprecated since RSpec 2.14, removed in RSpec 3.0
 * See also: [Consider deprecating and/or removing #stub! and #unstub! at some point · rspec/rspec-mocks](https://github.com/rspec/rspec-mocks/issues/122)
 
 ### Method stubs with deprecated specification of number of times
 
+Targets:
+
 ```ruby
-# Targets
 obj.stub(:foo).any_number_of_times
 obj.stub(:foo).at_least(0)
+```
 
-# Converted
+Will be converted to:
+
+```ruby
 allow(obj).to receive(:foo)
 obj.stub(:foo) # with `--keep stub`
 ```
 
-* Conversion can be disabled by: `--keep deprecated`
-* Deprecation: Deprecated since RSpec 2.14, removed in RSpec 3.0
+* This conversion can be disabled by: `--keep deprecated`
+* Deprecation: deprecated since RSpec 2.14, removed in RSpec 3.0
 * See also: [Don't allow at_least(0) · rspec/rspec-mocks](https://github.com/rspec/rspec-mocks/issues/133)
 
 ### Deprecated test double aliases
 
+Targets:
+
 ```ruby
-# Targets
 stub('something')
 mock('something')
+```
+
+Will be converted to:
 
-# Converted
+```ruby
 double('something')
 ```
 
-* Conversion can be disabled by: `--keep deprecated`
-* Deprecation: Deprecated since RSpec 2.14, removed in RSpec 3.0
+* This conversion can be disabled by: `--keep deprecated`
+* Deprecation: deprecated since RSpec 2.14, removed in RSpec 3.0
 * See also: [myronmarston / why_double.md - Gist](https://gist.github.com/myronmarston/6576665)
 
 ### Expectations on attribute of subject with `its`
 
 **This conversion will be disabled automatically if `rspec-its` is loaded in your spec.**
 
+Targets:
+
 ```ruby
-# Targets
 <%=
 its_target = <<END
 describe 'example' do
@@ -698,29 +759,33 @@ describe 'example' do
 end
 END
 -%>
+```
 
-# Converted
+Will be converted to:
+
+```ruby
 <%= Transpec::Converter.new.convert(its_target) -%>
 ```
 
-There's an option to continue using `its` with [rspec-its](https://github.com/rspec/rspec-its) that is a gem extracted from `rspec-core`.
-If you choose so, disable this conversion by either:
+There's an option to continue using `its` with [rspec-its](https://github.com/rspec/rspec-its) which is a gem extracted from `rspec-core`.
+If you choose to do so, disable this conversion by either:
 
 * Specify `--keep its` option manually.
 * Require `rspec-its` in your spec so that Transpec automatically disables this conversion.
 
 ---
 
-* Conversion can be disabled by: `--keep its`
-* Deprecation: Deprecated since RSpec 2.99, removed in RSpec 3.0
+* This conversion can be disabled by: `--keep its`
+* Deprecation: deprecated since RSpec 2.99, removed in RSpec 3.0
 * See also: [Core: its will be moved into an external gem - The Plan for RSpec 3](http://myronmars.to/n/dev-blog/2013/07/the-plan-for-rspec-3#core__will_be_moved_into_an_external_gem)
 
 ### Current example object
 
-**This conversion is available only if your project has `rspec` gem dependency `<%= Transpec::RSpecVersion.yielded_example_available_version %>` or later.**
+**This conversion is available only if your project's RSpec is `<%= Transpec::RSpecVersion.yielded_example_available_version %>` or later.**
+
+Targets:
 
 ```ruby
-# Targets
 <%=
 example_target = <<END
 module ScreenshotHelper
@@ -738,8 +803,11 @@ describe 'example page' do
 end
 END
 -%>
+```
+
+Will be converted to:
 
-# Converted
+```ruby
 <%=
 rspec_version = Transpec::RSpecVersion.yielded_example_available_version
 Transpec::Converter.new(nil, rspec_version).convert(example_target)
@@ -748,24 +816,56 @@ Transpec::Converter.new(nil, rspec_version).convert(example_target)
 
 Here's an excerpt from [the warning for `RSpec::Core::ExampleGroup#example` and `#running_example` in RSpec 2.99](https://github.com/rspec/rspec-core/blob/7d6d2ca/lib/rspec/core/example_group.rb#L513-L527):
 
->`RSpec::Core::ExampleGroup#example` is deprecated and will be removed in RSpec 3. There are a few options for what you can use instead:
+> `RSpec::Core::ExampleGroup#example` is deprecated and will be removed in RSpec 3. There are a few options for what you can use instead:
 >
->- `rspec-core`'s DSL methods (`it`, `before`, `after`, `let`, `subject`, etc) now yield the example as a block argument, and that is the recommended way to access the current example from those contexts.
->- The current example is now exposed via `RSpec.current_example`, which is accessible from any context.
->- If you can't update the code at this call site (e.g. because it is in an extension gem), you can use this snippet to continue making this method available in RSpec 2.99 and RSpec 3:
+> - `rspec-core`'s DSL methods (`it`, `before`, `after`, `let`, `subject`, etc) now yield the example as a block argument, and that is the recommended way to access the current example from those contexts.
+> - The current example is now exposed via `RSpec.current_example`, which is accessible from any context.
+> - If you can't update the code at this call site (e.g. because it is in an extension gem), you can use this snippet to continue making this method available in RSpec 2.99 and RSpec 3:
 >
->```ruby
->RSpec.configure do |c|
->  c.expose_current_running_example_as :example
->end
->```
+> ```ruby
+> RSpec.configure do |c|
+>   c.expose_current_running_example_as :example
+> end
+> ```
 
 ---
 
-* Conversion can be disabled by: `--keep deprecated`
-* Deprecation: Deprecated since RSpec 2.99, removed in RSpec 3.0
+* This conversion can be disabled by: `--keep deprecated`
+* Deprecation: deprecated since RSpec 2.99, removed in RSpec 3.0
 * See also: [Core: DSL methods will yield the example - The Plan for RSpec 3](http://myronmars.to/n/dev-blog/2013/07/the-plan-for-rspec-3#core_dsl_methods_will_yield_the_example)
 
+### Custom matcher DSL
+
+**This conversion is available only if your project's RSpec is `<%= Transpec::RSpecVersion.non_should_matcher_protocol_available_version %>` (not yet released) or later.**
+
+Targets:
+
+```ruby
+<%=
+custom_matcher_dsl_target = <<END
+RSpec::Matchers.define :be_awesome do
+  match_for_should { }
+  match_for_should_not { }
+  failure_message_for_should { }
+  failure_message_for_should_not { }
+end
+END
+-%>
+```
+
+Will be converted to:
+
+```ruby
+<%=
+rspec_version = Transpec::RSpecVersion.non_should_matcher_protocol_available_version
+Transpec::Converter.new(nil, rspec_version).convert(custom_matcher_dsl_target)
+-%>
+```
+
+* 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)
+
 ## Compatibility
 
 Tested on MRI 1.9, MRI 2.0 and JRuby in 1.9 mode.