Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
2 changed files
with
130 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,129 @@ | ||
= Upgrade to Version 2.x | ||
:doctype: book | ||
|
||
== Configuration File Update | ||
|
||
In version 2.x: | ||
|
||
- `RSpec/InvalidPredicateMatcher` cop is removed | ||
- `CustomIncludeMethods` configuration option for `RSpec/EmptyExampleGroup` is removed | ||
|
||
[discrete] | ||
=== Adjust the configuration of `RSpec/EmptyExampleGroup` | ||
|
||
[source,yaml] | ||
---- | ||
# .rubocop.yml | ||
# Before | ||
RSpec/EmptyExampleGroup: | ||
CustomIncludeMethods: | ||
- include_tests | ||
# After | ||
AllCops: | ||
RSpec: | ||
Language: | ||
Includes: | ||
Example: | ||
- include_tests | ||
---- | ||
|
||
== Custom Cop Update Guide | ||
|
||
Due to significant API changes custom cops will break. | ||
Here is the summary of the changes: | ||
|
||
1) The base class for cops is now `RuboCop::Cop::RSpec::Base` instead of `RuboCop::Cop::RSpec::Cop`. | ||
|
||
2) `TopLevelDescribe` is replaced with a more generic `TopLevelGroup`. | ||
|
||
3) `RuboCop::RSpec::Language` has been completely rewritten to support dynamic RSpec DSL aliases and negated matchers to fully support third-party libraries e.g. RSpec Rails, Pundit, Action Policy and many others. | ||
|
||
4) RuboCop RSpec updated the dependency of RuboCop to 1.0+. | ||
|
||
Below are the necessary steps to update custom cops to work with `rubocop-rspec` version 2.x. | ||
|
||
|
||
=== Change the Parent Class | ||
|
||
Change the parent class of the custom cops from `RuboCop::Cop::RSpec::Cop` to `RuboCop::Cop::RSpec::Base`. | ||
|
||
[source,ruby] | ||
---- | ||
# Before | ||
module RuboCop | ||
module Cop | ||
module RSpec | ||
class FightPowerty < Cop | ||
# After | ||
module RuboCop | ||
module Cop | ||
module RSpec | ||
class FightPowerty < Base | ||
---- | ||
|
||
https://github.com/rubocop-hq/rubocop-rspec/pull/962[Example pull request]. | ||
|
||
|
||
=== Replace `TopLevelDescribe` | ||
|
||
`TopLevelDescribe` was incomplete, had poor performance and did not distinguish between example groups and shared example groups. | ||
|
||
`TopLevelGroup` provides a similar interface, but instead of a single `on_top_level_describe` hook there are two, `on_top_level_example_group` and `on_top_level_group`. | ||
There's no need yet for `on_top_level_shared_group` for RuboCop core cops, but if your custom cop needs such a hook, please feel free to send a pull request. | ||
|
||
Additionally, `single_top_level_describe?` is removed with no direct replacement. | ||
You may use `top_level_groups` query method instead, e.g. `top_level_groups.one?`. | ||
|
||
Example pull requests to replace `TopLevelDescribe` with `TopLevelGroup` [https://github.com/rubocop-hq/rubocop-rspec/pull/978[1], https://github.com/rubocop-hq/rubocop-rspec/pull/932[2], https://github.com/rubocop-hq/rubocop-rspec/pull/977[3]]. | ||
|
||
|
||
=== Change the `Language` Module Usages | ||
|
||
The `RuboCop::RSpec::Language` is completely different now. | ||
`Hooks::ALL` and alike, and their accompanying helpers work differently. | ||
To allow for lazy initialization, and for loading of the language configuration after the class are loaded, a https://docs.rubocop.org/rubocop-ast/node_pattern.html#to-call-functions[function call feature of RuboCop AST] is used. | ||
|
||
[source,ruby] | ||
---- | ||
# Before | ||
def_node_matcher :shared_context, | ||
SharedGroups::CONTEXT.block_pattern | ||
# After | ||
def_node_matcher :shared_context, | ||
block_pattern('#rspec(:SharedGroups, :Context)') | ||
---- | ||
|
||
[source,ruby] | ||
---- | ||
# Before | ||
def_node_search :examples?, | ||
(Includes::EXAMPLES + Examples::ALL).send_pattern | ||
# After | ||
def_node_search :examples?, | ||
send_pattern( | ||
'{#rspec(:Includes, :Example) #rspec(:Examples)}') | ||
---- | ||
|
||
[source,ruby] | ||
---- | ||
# Before | ||
def_node_search :find_rspec_blocks, | ||
ExampleGroups::ALL.block_pattern | ||
# After | ||
def_node_search :find_rspec_blocks, | ||
block_pattern('#rspec(:ExampleGroups)') | ||
---- | ||
|
||
https://github.com/rubocop-hq/rubocop-rspec/pull/956[Pull request with more examples]. | ||
|
||
=== Conform with RuboCop API Changes | ||
|
||
The parent project, RuboCop, have API changes. | ||
They won't result in cop breakages, however, it's recommended to update cops to use new APIs. | ||
Follow the https://docs.rubocop.org/rubocop/v1_upgrade_notes[RuboCop's core v1 update guide] to adjust custom cops' RuboCop Autocorrect API usage. |