upgrade_to_version_2.adoc

Upgrade to Version 2.x

Configuration File Update

In version 2.x:

• RSpec/InvalidPredicateMatcher cop is removed

• CustomIncludeMethods configuration option for RSpec/EmptyExampleGroup is removed

• cop departments are nested for cops with a department that doesn’t match the extension name (Capybara, FactoryBot, Rails)

Adjust the configuration of RSpec/EmptyExampleGroup

# .rubocop.yml

# Before
RSpec/EmptyExampleGroup:
  CustomIncludeMethods:
  - include_tests

# After
AllCops:
  RSpec:
    Language:
      Includes:
        Example:
        - include_tests

Add a top-level RSpec department

RuboCop extensions had cops with clashing names and departments, e.g. both rspec-rails and rubocop-rspec had Rails::HttpStatus cops. To avoid issues, e.g. inability to disable just one of the cops, each extension now has its own uber-department. Expectedly, RuboCop RSpec’s uber-department name is RSpec. Changes are only applied to cops that don’t already have the department set to RSpec, i.e. Capybara, FactoryBot and Rails.

# .rubocop.yml

# Before
Capybara/CurrentPathExpectation:
  Enabled: false

FactoryBot/AttributeDefinedStatically:
  Enabled: false

# remains the same
RSpec/EmptyExampleGroup:
  Enabled: false

# After
RSpec/Capybara/CurrentPathExpectation:
  Enabled: false

RSpec/FactoryBot/AttributeDefinedStatically:
  Enabled: false

# remains the same
RSpec/EmptyExampleGroup:
  Enabled: false

Learn more about this change.

Custom Cop Update Guide

Due to significant API changes, custom cops may 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 such as 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.

# Before
module RuboCop
  module Cop
    module RSpec
      class FightPowerty < Cop

# After
module RuboCop
  module Cop
    module RSpec
      class FightPowerty < Base

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 [1, 2, 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 function call feature of RuboCop AST is used.

# Before
def_node_matcher :shared_context,
                 SharedGroups::CONTEXT.block_pattern

# After
def_node_matcher :shared_context,
                 block_pattern('#rspec(:SharedGroups, :Context)')

# Before
def_node_search :examples?,
                (Includes::EXAMPLES + Examples::ALL).send_pattern

# After
def_node_search :examples?,
                send_pattern('{#rspec(:Includes, :Example) #rspec(:Examples)}')

# Before
def_node_search :find_rspec_blocks,
                ExampleGroups::ALL.block_pattern

# After
def_node_search :find_rspec_blocks,
                block_pattern('#rspec(:ExampleGroups)')

Pull request with more examples.

Conform with RuboCop API Changes

The parent project, RuboCop, has API changes. While they won’t result in cop breakages, it is recommended to update cops to use new API’s. Follow the RuboCop v1 update guide to adjust custom cops’ use of RuboCop’s auto-correction API.