rubocop-rspec 1.7.0 → 3.0.2

data/lib/rubocop/cop/rspec/example_wording.rb

@@ -3,58 +3,135 @@
 module RuboCop
   module Cop
     module RSpec
-      # Checks that example descriptions do not start with "should".
+      # Checks for common mistakes in example descriptions.
+      #
+      # This cop will correct docstrings that begin with 'should' and 'it'.
+      # This cop will also look for insufficient examples and call them out.
       #
       # @see http://betterspecs.org/#should
       #
       # The autocorrect is experimental - use with care! It can be configured
       # with CustomTransform (e.g. have => has) and IgnoredWords (e.g. only).
       #
+      # Use the DisallowedExamples setting to prevent unclear or insufficient
+      # descriptions. Please note that this config will not be treated as
+      # case sensitive.
+      #
       # @example
       #   # bad
       #   it 'should find nothing' do
       #   end
       #
+      #   it 'will find nothing' do
+      #   end
+      #
       #   # good
       #   it 'finds nothing' do
       #   end
-      class ExampleWording < Cop
-        include RuboCop::RSpec::SpecOnly
+      #
+      # @example
+      #   # bad
+      #   it 'it does things' do
+      #   end
+      #
+      #   # good
+      #   it 'does things' do
+      #   end
+      #
+      # @example `DisallowedExamples: ['works']` (default)
+      #   # bad
+      #   it 'works' do
+      #   end
+      #
+      #   # good
+      #   it 'marks the task as done' do
+      #   end
+      class ExampleWording < Base
+        extend AutoCorrector
+
+        MSG_SHOULD = 'Do not use should when describing your tests.'
+        MSG_WILL   = 'Do not use the future tense when describing your tests.'
+        MSG_IT     = "Do not repeat 'it' when describing your tests."
+        MSG_INSUFFICIENT_DESCRIPTION = 'Your example description is ' \
+                                       'insufficient.'
 
-        MSG = 'Do not use should when describing your tests.'.freeze
+        SHOULD_PREFIX = /\Ashould(?:n't)?\b/i.freeze
+        WILL_PREFIX   = /\A(?:will|won't)\b/i.freeze
+        IT_PREFIX     = /\Ait /i.freeze
 
-        def on_block(node) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength,Metrics/LineLength
-          method, = *node
-          _, method_name, *args = *method
+        # @!method it_description(node)
+        def_node_matcher :it_description, <<~PATTERN
+          (block (send _ :it ${
+            (str $_)
+            (dstr (str $_ ) ...)
+          } ...) ...)
+        PATTERN
 
-          return unless method_name.equal?(:it)
+        # rubocop:disable Metrics/MethodLength
+        def on_block(node) # rubocop:disable InternalAffairs/NumblockHandler
+          it_description(node) do |description_node, message|
+            if message.match?(SHOULD_PREFIX)
+              add_wording_offense(description_node, MSG_SHOULD)
+            elsif message.match?(WILL_PREFIX)
+              add_wording_offense(description_node, MSG_WILL)
+            elsif message.match?(IT_PREFIX)
+              add_wording_offense(description_node, MSG_IT)
+            elsif insufficient_docstring?(description_node)
+              add_offense(docstring(description_node),
+                          message: MSG_INSUFFICIENT_DESCRIPTION)
+            end
+          end
+        end
+        # rubocop:enable Metrics/MethodLength
 
-          arguments = args.first.to_a
-          message = arguments.first.to_s
-          return unless message.downcase.start_with?('should')
+        private
 
-          arg1 = args.first.loc.expression
-          message = Parser::Source::Range.new(arg1.source_buffer,
-                                              arg1.begin_pos + 1,
-                                              arg1.end_pos - 1)
+        def add_wording_offense(node, message)
+          docstring = docstring(node)
 
-          add_offense(message, message)
+          add_offense(docstring, message: message) do |corrector|
+            next if node.heredoc?
+
+            corrector.replace(docstring, replacement_text(node))
+          end
         end
 
-        def autocorrect(range)
-          lambda do |corrector|
-            corrector.replace(
-              range,
-              RuboCop::RSpec::Wording.new(
-                range.source,
-                ignore: ignored_words,
-                replace: custom_transform
-              ).rewrite
-            )
+        def docstring(node)
+          expr = node.source_range
+
+          Parser::Source::Range.new(
+            expr.source_buffer,
+            expr.begin_pos + 1,
+            expr.end_pos - 1
+          )
+        end
+
+        def replacement_text(node)
+          text = text(node)
+
+          if text.match?(SHOULD_PREFIX) || text.match?(WILL_PREFIX)
+            RuboCop::RSpec::Wording.new(
+              text,
+              ignore:  ignored_words,
+              replace: custom_transform
+            ).rewrite
+          else
+            text.sub(IT_PREFIX, '')
           end
         end
 
-        private
+        # Recursive processing is required to process nested dstr nodes
+        # that is the case for \-separated multiline strings with interpolation.
+        def text(node)
+          case node.type
+          when :dstr
+            node.node_parts.map { |child_node| text(child_node) }.join
+          when :str
+            node.value
+          when :begin
+            node.source
+          end
+        end
 
         def custom_transform
           cop_config.fetch('CustomTransform', {})
@@ -63,6 +140,19 @@ module RuboCop
         def ignored_words
           cop_config.fetch('IgnoredWords', [])
         end
+
+        def insufficient_docstring?(description_node)
+          insufficient_examples.include?(preprocess(text(description_node)))
+        end
+
+        def insufficient_examples
+          examples = cop_config.fetch('DisallowedExamples', [])
+          examples.map! { |example| preprocess(example) }
+        end
+
+        def preprocess(message)
+          message.strip.squeeze(' ').downcase
+        end
       end
     end
   end

data/lib/rubocop/cop/rspec/excessive_docstring_spacing.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module RSpec
+      # Checks for excessive whitespace in example descriptions.
+      #
+      # @example
+      #   # bad
+      #   it '  has  excessive   spacing  ' do
+      #   end
+      #
+      #   # good
+      #   it 'has excessive spacing' do
+      #   end
+      #
+      # @example
+      #   # bad
+      #   context '  when a condition   is met  ' do
+      #   end
+      #
+      #   # good
+      #   context 'when a condition is met' do
+      #   end
+      #
+      class ExcessiveDocstringSpacing < Base
+        extend AutoCorrector
+
+        MSG = 'Excessive whitespace.'
+
+        # @!method example_description(node)
+        def_node_matcher :example_description, <<~PATTERN
+          (send _ {#Examples.all #ExampleGroups.all} ${
+            $str
+            $(dstr ({str dstr `sym} ...) ...)
+          } ...)
+        PATTERN
+
+        def on_send(node)
+          example_description(node) do |description_node, message|
+            return if description_node.heredoc?
+
+            text = text(message)
+
+            return unless excessive_whitespace?(text)
+
+            add_whitespace_offense(description_node, text)
+          end
+        end
+
+        private
+
+        # @param text [String]
+        def excessive_whitespace?(text)
+          text.match?(/
+            # Leading space
+            \A[[:blank:]]
+            |
+            # Trailing space
+            [[:blank:]]\z
+            |
+            # Two or more consecutive spaces, except if they are leading spaces
+            [^[[:space:]]][[:blank:]]{2,}[^[[:blank:]]]
+          /x)
+        end
+
+        # @param text [String]
+        def strip_excessive_whitespace(text)
+          text
+            .gsub(/[[:blank:]]{2,}/, ' ')
+            .gsub(/\A[[:blank:]]|[[:blank:]]\z/, '')
+        end
+
+        # @param node [RuboCop::AST::Node]
+        # @param text [String]
+        def add_whitespace_offense(node, text)
+          docstring = docstring(node)
+          corrected = strip_excessive_whitespace(text)
+
+          add_offense(docstring) do |corrector|
+            corrector.replace(docstring, corrected)
+          end
+        end
+
+        def docstring(node)
+          expr = node.source_range
+
+          Parser::Source::Range.new(
+            expr.source_buffer,
+            expr.begin_pos + 1,
+            expr.end_pos - 1
+          )
+        end
+
+        # Recursive processing is required to process nested dstr nodes
+        # that is the case for \-separated multiline strings with interpolation.
+        def text(node)
+          case node.type
+          when :dstr
+            node.node_parts.map { |child_node| text(child_node) }.join
+          when :str, :sym
+            node.value
+          when :begin
+            node.source
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/rspec/expect_actual.rb

@@ -5,6 +5,8 @@ module RuboCop
     module RSpec
       # Checks for `expect(...)` calls containing literal values.
       #
+      # Autocorrection is performed when the expected is not a literal.
+      #
       # @example
       #   # bad
       #   expect(5).to eq(price)
@@ -16,12 +18,17 @@ module RuboCop
       #   expect(pattern).to eq(/foo/)
       #   expect(name).to eq("John")
       #
-      class ExpectActual < Cop
-        include RuboCop::RSpec::SpecOnly
+      #   # bad (not supported autocorrection)
+      #   expect(false).to eq(true)
+      #
+      class ExpectActual < Base
+        extend AutoCorrector
+
+        MSG = 'Provide the actual value you are testing to `expect(...)`.'
 
-        MSG = 'Provide the actual you are testing to `expect(...)`'.freeze
+        RESTRICT_ON_SEND = Runners.all
 
-        SIMPLE_LITERALS = %i(
+        SIMPLE_LITERALS = %i[
           true
           false
           nil
@@ -32,37 +39,56 @@ module RuboCop
           complex
           rational
           regopt
-        ).freeze
+        ].freeze
 
-        COMPLEX_LITERALS = %i(
+        COMPLEX_LITERALS = %i[
           array
           hash
           pair
           irange
           erange
           regexp
-        ).freeze
+        ].freeze
+
+        SKIPPED_MATCHERS = %i[route_to be_routable].freeze
+        CORRECTABLE_MATCHERS = %i[eq eql equal be].freeze
+
+        # @!method expect_literal(node)
+        def_node_matcher :expect_literal, <<~PATTERN
+          (send
+            (send nil? :expect $#literal?)
+            #Runners.all
+            ${
+              (send (send nil? $:be) :== $_)
+              (send nil? $_ $_ ...)
+            }
+          )
+        PATTERN
 
-        def_node_matcher :expect, '(send _ :expect $_)'
+        def on_send(node) # rubocop:disable Metrics/MethodLength
+          expect_literal(node) do |actual, send_node, matcher, expected|
+            next if SKIPPED_MATCHERS.include?(matcher)
 
-        def on_send(node)
-          expect_literal(node) do |argument|
-            add_offense(argument, :expression)
+            add_offense(actual.source_range) do |corrector|
+              next unless CORRECTABLE_MATCHERS.include?(matcher)
+              next if literal?(expected)
+
+              corrector.replace(actual, expected.source)
+              if matcher == :be
+                corrector.replace(expected, actual.source)
+              else
+                corrector.replace(send_node, "#{matcher}(#{actual.source})")
+              end
+            end
           end
         end
 
         private
 
-        # This is not implement using a NodePattern because it seems
+        # This is not implemented using a NodePattern because it seems
         # to not be able to match against an explicit (nil) sexp
-        def expect_literal(node)
-          return unless (argument = expect(node))
-
-          yield(argument) if literal?(argument)
-        end
-
         def literal?(node)
-          simple_literal?(node) || complex_literal?(node)
+          node && (simple_literal?(node) || complex_literal?(node))
         end
 
         def simple_literal?(node)
@@ -71,7 +97,7 @@ module RuboCop
 
         def complex_literal?(node)
           COMPLEX_LITERALS.include?(node.type) &&
-            node.each_child_node.all?(&method(:literal?))
+            node.each_child_node.all? { |child_node| literal?(child_node) }
         end
       end
     end

data/lib/rubocop/cop/rspec/expect_change.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module RSpec
+      # Checks for consistent style of change matcher.
+      #
+      # Enforces either passing object and attribute as arguments to the matcher
+      # or passing a block that reads the attribute value.
+      #
+      # This cop can be configured using the `EnforcedStyle` option.
+      #
+      # @example `EnforcedStyle: method_call` (default)
+      #   # bad
+      #   expect { run }.to change { Foo.bar }
+      #   expect { run }.to change { foo.baz }
+      #
+      #   # good
+      #   expect { run }.to change(Foo, :bar)
+      #   expect { run }.to change(foo, :baz)
+      #   # also good when there are arguments or chained method calls
+      #   expect { run }.to change { Foo.bar(:count) }
+      #   expect { run }.to change { user.reload.name }
+      #
+      # @example `EnforcedStyle: block`
+      #   # bad
+      #   expect { run }.to change(Foo, :bar)
+      #
+      #   # good
+      #   expect { run }.to change { Foo.bar }
+      #
+      class ExpectChange < Base
+        extend AutoCorrector
+        include ConfigurableEnforcedStyle
+
+        MSG_BLOCK = 'Prefer `change(%<obj>s, :%<attr>s)`.'
+        MSG_CALL = 'Prefer `change { %<obj>s.%<attr>s }`.'
+        RESTRICT_ON_SEND = %i[change].freeze
+
+        # @!method expect_change_with_arguments(node)
+        def_node_matcher :expect_change_with_arguments, <<~PATTERN
+          (send nil? :change $_ ({sym str} $_))
+        PATTERN
+
+        # @!method expect_change_with_block(node)
+        def_node_matcher :expect_change_with_block, <<~PATTERN
+          (block
+            (send nil? :change)
+            (args)
+            (send
+              ${
+                (send nil? _)  # change { user.name }
+                const          # change { User.count }
+              }
+              $_
+            )
+          )
+        PATTERN
+
+        def on_send(node)
+          return unless style == :block
+
+          expect_change_with_arguments(node) do |receiver, message|
+            msg = format(MSG_CALL, obj: receiver.source, attr: message)
+            add_offense(node, message: msg) do |corrector|
+              replacement = "change { #{receiver.source}.#{message} }"
+              corrector.replace(node, replacement)
+            end
+          end
+        end
+
+        def on_block(node) # rubocop:disable InternalAffairs/NumblockHandler
+          return unless style == :method_call
+
+          expect_change_with_block(node) do |receiver, message|
+            msg = format(MSG_BLOCK, obj: receiver.source, attr: message)
+            add_offense(node, message: msg) do |corrector|
+              replacement = "change(#{receiver.source}, :#{message})"
+              corrector.replace(node, replacement)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/rspec/expect_in_hook.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module RSpec
+      # Do not use `expect` in hooks such as `before`.
+      #
+      # @example
+      #   # bad
+      #   before do
+      #     expect(something).to eq 'foo'
+      #   end
+      #
+      #   # bad
+      #   after do
+      #     expect_any_instance_of(Something).to receive(:foo)
+      #   end
+      #
+      #   # good
+      #   it do
+      #     expect(something).to eq 'foo'
+      #   end
+      #
+      class ExpectInHook < Base
+        MSG = 'Do not use `%<expect>s` in `%<hook>s` hook'
+
+        # @!method expectation(node)
+        def_node_search :expectation, '(send nil? #Expectations.all ...)'
+
+        def on_block(node)
+          return unless hook?(node)
+          return if node.body.nil?
+
+          expectation(node.body) do |expect|
+            add_offense(expect.loc.selector,
+                        message: message(expect, node))
+          end
+        end
+
+        alias on_numblock on_block
+
+        private
+
+        def message(expect, hook)
+          format(MSG, expect: expect.method_name, hook: hook.method_name)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/rspec/expect_in_let.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module RSpec
+      # Do not use `expect` in let.
+      #
+      # @example
+      #   # bad
+      #   let(:foo) do
+      #     expect(something).to eq 'foo'
+      #   end
+      #
+      #   # good
+      #   it do
+      #     expect(something).to eq 'foo'
+      #   end
+      #
+      class ExpectInLet < Base
+        MSG = 'Do not use `%<expect>s` in let'
+
+        # @!method expectation(node)
+        def_node_search :expectation, '(send nil? #Expectations.all ...)'
+
+        def on_block(node) # rubocop:disable InternalAffairs/NumblockHandler
+          return unless let?(node)
+          return if node.body.nil?
+
+          expectation(node.body) do |expect|
+            add_offense(expect.loc.selector, message: message(expect))
+          end
+        end
+
+        private
+
+        def message(expect)
+          format(MSG, expect: expect.method_name)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/rspec/expect_output.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module RSpec
+      # Checks for opportunities to use `expect { ... }.to output`.
+      #
+      # @example
+      #   # bad
+      #   $stdout = StringIO.new
+      #   my_app.print_report
+      #   $stdout = STDOUT
+      #   expect($stdout.string).to eq('Hello World')
+      #
+      #   # good
+      #   expect { my_app.print_report }.to output('Hello World').to_stdout
+      #
+      class ExpectOutput < Base
+        MSG = 'Use `expect { ... }.to output(...).to_%<name>s` ' \
+              'instead of mutating $%<name>s.'
+
+        def on_gvasgn(node)
+          return unless inside_example_scope?(node)
+
+          name = node.name[1..]
+          return unless name.eql?('stdout') || name.eql?('stderr')
+
+          add_offense(node.loc.name, message: format(MSG, name: name))
+        end
+
+        private
+
+        # Detect if we are inside the scope of a single example
+        #
+        # We want to encourage using `expect { ... }.to output` so
+        # we only care about situations where you would replace with
+        # an expectation. Therefore, assignments to stderr or stdout
+        # within a `before(:all)` or otherwise outside of an example
+        # don't matter.
+        def inside_example_scope?(node)
+          return false if node.nil? || example_group?(node)
+          return true if example?(node)
+          return RuboCop::RSpec::Hook.new(node).example? if hook?(node)
+
+          inside_example_scope?(node.parent)
+        end
+      end
+    end
+  end
+end