rubocop-capybara 2.23.0 → 3.1.0

data/lib/rubocop/cop/capybara/chained_find.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Capybara
+      # Avoid chaining `find` methods and combine selectors.
+      #
+      # Combining selectors into a single `find` call is more efficient than
+      # chaining multiple `find` calls, as it reduces the number of DOM queries.
+      # Only recognizable Capybara finder chains with string locators are
+      # checked.
+      # Set `DefaultSelector` to match `Capybara.default_selector`, or to
+      # `null` if it varies at runtime. Autocorrection requires `css` and
+      # literal strings.
+      #
+      # @example
+      #   # bad
+      #   page.find('#foo').find('.bar')
+      #   page.find('#foo').find('.bar').find('.baz')
+      #
+      #   # good
+      #   page.find('#foo .bar')
+      #   page.find('#foo .bar .baz')
+      #   find('#form').find(:button, 'Save')
+      #
+      class ChainedFind < RuboCop::Cop::Base # rubocop:disable Metrics/ClassLength
+        extend AutoCorrector
+        include CapybaraHelp
+
+        MSG = 'Avoid chaining `find` methods. ' \
+              'Combine the selectors into a single `find` call.'
+        MSG_WITH_COMBINED = 'Use `find(%<combined>s)` instead of ' \
+                            'chaining `find` methods.'
+        RESTRICT_ON_SEND = %i[find].freeze
+
+        # @!method single_string_find?(node)
+        def_node_matcher :single_string_find?, <<~PATTERN
+          (call _ :find (str $_))
+        PATTERN
+
+        def on_send(node)
+          return unless chained_find?(node)
+
+          find_receiver = find_receiver(node.receiver)
+          return unless find_receiver
+          return unless string_locators?(node, find_receiver)
+          return unless capybara_receiver?(find_receiver.receiver)
+
+          register_offense(node, find_receiver)
+        end
+        alias on_csend on_send
+
+        private
+
+        def chained_find?(node)
+          node.method?(:find) && node.receiver
+        end
+
+        def string_locators?(node, receiver)
+          node.first_argument&.type?(:str, :dstr) &&
+            receiver.first_argument&.type?(:str, :dstr)
+        end
+
+        def find_receiver(receiver)
+          return unwrapped_receiver(receiver) if receiver.block_type?
+
+          receiver if receiver.call_type? && receiver.method?(:find)
+        end
+
+        def unwrapped_receiver(block_node)
+          send_node = block_node.send_node
+          send_node if send_node.method?(:find)
+        end
+
+        def register_offense(node, find_receiver)
+          if safe_to_autocorrect?(node, find_receiver)
+            add_correctable_offense(node, find_receiver)
+          else
+            add_offense(node)
+          end
+        end
+
+        def add_correctable_offense(node, find_receiver)
+          combined = combined_selector(node, find_receiver)
+          message = format(
+            MSG_WITH_COMBINED,
+            combined: selector_literal(combined)
+          )
+          return add_offense(node, message: message) if nested_find?(node)
+
+          add_offense(node, message: message) do |corrector|
+            corrector.replace(node, replacement(node, combined))
+          end
+        end
+
+        def nested_find?(node)
+          node.parent&.call_type? &&
+            node.parent.method?(:find) &&
+            node.parent.receiver == node
+        end
+
+        def safe_to_autocorrect?(node, receiver)
+          cop_config['DefaultSelector'].to_s == 'css' &&
+            single_string_argument?(node) &&
+            single_string_argument?(receiver) &&
+            node.type == receiver.type &&
+            safe_selectors?(node)
+        end
+
+        def safe_selectors?(node)
+          current = node
+          while current&.call_type? && current.method?(:find)
+            return false unless single_string_argument?(current)
+
+            return false if unsafe_selector?(current.first_argument.value)
+
+            current = current.receiver
+          end
+
+          true
+        end
+
+        def unsafe_selector?(selector)
+          selector.match?(/(?<!\\),/) || selector.start_with?('//', './/')
+        end
+
+        def single_string_argument?(node)
+          node.arguments.one? &&
+            !node.block_node &&
+            single_string_find?(node)
+        end
+
+        def combined_selector(node, receiver)
+          selectors = collect_selectors(receiver)
+          current = node.first_argument.value
+
+          "#{selectors} #{current}"
+        end
+
+        def collect_selectors(node)
+          [].tap do |selectors|
+            current = node
+            while (selector = single_string_find?(current))
+              selectors.unshift(selector)
+              current = current.receiver
+              break unless current&.call_type? && current.method?(:find)
+            end
+          end.join(' ')
+        end
+
+        def replacement(node, combined_selector)
+          root = chain_root(node)
+          receiver_source = root.receiver&.source
+          find_call = "find(#{selector_literal(combined_selector)})"
+
+          [receiver_source, find_call].compact.join(root.loc.dot&.source || '.')
+        end
+
+        def selector_literal(selector)
+          return selector.inspect if selector.match?(/['\\]/)
+
+          "'#{selector}'"
+        end
+
+        def chain_root(node)
+          root = node
+          while root.receiver&.call_type? && root.receiver.method?(:find)
+            root = root.receiver
+          end
+          root
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/capybara/find_all_first.rb

@@ -6,29 +6,25 @@ module RuboCop
       # Enforces use of `first` instead of `all` with `first` or `[0]`.
       #
       # @safety
-      #   This cop's autocorrection is unsafe because `all` returns a
-      #   `Capybara::Result` (an enumerable collection), while `first`
-      #   returns a single `Capybara::Node::Element`. Replacing `all`
-      #   with `first` may break code that depends on the return value
-      #   being a collection (e.g. calling `.each` on the result).
+      #   With default options, `all(...).first` and `all(...)[0]` return
+      #   `nil` when no element matches, while `first(...)` raises an
+      #   exception. Autocorrection can break code that depends on `nil`.
       #
       # @example
       #
       #   # bad
       #   all('a').first
       #   all('a')[0]
-      #   find('a', match: :first)
-      #   all('a', match: :first)
       #
       #   # good
       #   first('a')
       #
-      class FindAllFirst < ::RuboCop::Cop::Base
+      class FindAllFirst < RuboCop::Cop::Base
         extend AutoCorrector
         include RangeHelp
 
         MSG = 'Use `first(%<selector>s)`.'
-        RESTRICT_ON_SEND = %i[all find].freeze
+        RESTRICT_ON_SEND = %i[all].freeze
 
         # @!method find_all_first?(node)
         def_node_matcher :find_all_first?, <<~PATTERN
@@ -38,22 +34,10 @@ module RuboCop
           }
         PATTERN
 
-        # @!method include_match_first?(node)
-        def_node_matcher :include_match_first?, <<~PATTERN
-          (send _ {:find :all} _ $(hash <(pair (sym :match) (sym :first)) ...>))
-        PATTERN
-
         def on_send(node)
-          on_all_first(node)
-          on_match_first(node)
-        end
-
-        private
-
-        def on_all_first(node)
           return unless (parent = node.parent)
           return unless find_all_first?(parent)
-          return if part_of_logical_operator?(parent)
+          return if nil_sensitive_use?(parent)
 
           range = range_between(node.loc.selector.begin_pos,
                                 parent.loc.selector.end_pos)
@@ -64,27 +48,15 @@ module RuboCop
           end
         end
 
-        def on_match_first(node)
-          include_match_first?(node) do |hash|
-            selector = ([node.first_argument.source] + replaced_hash(hash))
-              .join(', ')
-            range = range_between(node.loc.selector.begin_pos,
-                                  node.source_range.end_pos)
-            add_offense(range,
-                        message: format(MSG, selector: selector)) do |corrector|
-              corrector.replace(range, "first(#{selector})")
-            end
-          end
-        end
+        private
 
-        def replaced_hash(hash)
-          hash.child_nodes.flat_map(&:source).reject do |arg|
-            arg == 'match: :first'
-          end
-        end
+        def nil_sensitive_use?(node)
+          return true if node.ancestors.any?(&:operator_keyword?)
 
-        def part_of_logical_operator?(node)
-          node.ancestors.any?(&:operator_keyword?)
+          parent = node.parent
+          (parent&.csend_type? && parent.receiver == node) ||
+            (parent&.type?(:if, :while, :until) &&
+             parent.condition == node)
         end
       end
     end

data/lib/rubocop/cop/capybara/ignored_query_option.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Capybara
+      # Checks for query options that have no effect in Capybara.
+      #
+      # Count options passed to singular finders are not autocorrected because
+      # removing them may conceal the author's intent.
+      #
+      # This cop targets Capybara's built-in selectors. Set `DefaultSelector`
+      # to match `Capybara.default_selector`, or to `null` if it varies at
+      # runtime. Queries using custom or unknown selectors are skipped.
+      #
+      # @example
+      #   # bad
+      #   find('.row', count: 3)
+      #   find(:css, '.item', exact: true)
+      #   find('.item', text: /foo/, exact_text: true)
+      #   all(:css, '.item', match: :first)
+      #   expect(page).to have_css('.item', count: 3, minimum: 1)
+      #
+      #   # good
+      #   all('.row', count: 3)
+      #   find(:css, '.item')
+      #   find('.item', text: /foo/)
+      #   all(:css, '.item')
+      #   expect(page).to have_css('.item', count: 3)
+      #
+      # @example DefaultSelector: custom
+      #   # bad
+      #   find(:css, '.item', text: /foo/, exact_text: true)
+      #
+      #   # good
+      #   find('.item', text: /foo/, exact_text: true)
+      #
+      class IgnoredQueryOption < RuboCop::Cop::Base # rubocop:disable Metrics/ClassLength
+        extend AutoCorrector
+        include RangeHelp
+        include CapybaraHelp
+
+        RESTRICT_ON_SEND = QueryMethods.names(
+          :finder, :collection, :selector, :match, :text
+        ).freeze
+        COUNT_OPTIONS = %i[count minimum maximum between].freeze
+        MATCH_STRATEGIES = %i[first smart prefer_exact one].freeze
+
+        FIND_COUNT_MSG =
+          '`%<option>s` has no effect when passed to `%<method>s`.'
+        EXACT_MSG = '`exact` has no effect on CSS queries.'
+        EXACT_TEXT_MSG =
+          '`exact_text` has no effect when `text` is a regexp.'
+        MATCH_MSG =
+          '`match` has no effect when passed to `%<method>s`.'
+        SHADOWED_COUNT_MSG =
+          '`%<option>s` has no effect when `count` is specified.'
+
+        # @!method query_options(node)
+        def_node_matcher :query_options, <<~PATTERN
+          (call #capybara_receiver? _ <$(hash ...) ...>)
+        PATTERN
+
+        # @!method custom_filters?(node)
+        def_node_matcher :custom_filters?, <<~PATTERN
+          (hash <{(pair (sym {:filter_set :session_options}) _) (pair !sym _) kwsplat} ...>)
+        PATTERN
+
+        # @!method removable_value?(node)
+        def_node_matcher :removable_value?, <<~PATTERN
+          {basic_literal? (range {int nil?} {int nil?})}
+        PATTERN
+
+        def on_send(node)
+          return unless (options = query_options(node))
+          return if options.braces?
+          return if custom_filters?(options)
+
+          issues = options.pairs.filter_map do |pair|
+            issue_for(node, options, pair)
+          end
+          return if issues.empty?
+
+          register_issues(node, options, issues)
+        end
+        alias on_csend on_send
+
+        private
+
+        def register_issues(node, options, issues)
+          correction_pair = issues.find do |pair, _, correctable|
+            correctable && removable?(options, pair) && !comments_in?(node)
+          end
+          issues.each do |pair, message, _|
+            add_offense(pair, message: message) do |corrector|
+              next unless pair == correction_pair&.first
+
+              remove_option(corrector, node, options, pair)
+            end
+          end
+        end
+
+        def issue_for(node, options, pair)
+          option = pair.key.value
+          issue = find_count_issue(node, option) ||
+            exact_issue(node, option) ||
+            exact_text_issue(node, option, pair, options) ||
+            match_issue(node, option, pair) ||
+            shadowed_count_issue(node, option, options)
+
+          [pair, *issue] if issue
+        end
+
+        def find_count_issue(node, option)
+          return unless QueryMethods.type(node.method_name) == :finder
+          return unless COUNT_OPTIONS.include?(option)
+          return if custom_selector?(node)
+
+          [
+            format(FIND_COUNT_MSG,
+                   option: option,
+                   method: node.method_name),
+            false
+          ]
+        end
+
+        def shadowed_count_issue(node, option, options)
+          return if QueryMethods.type(node.method_name) == :match
+          return unless count_query_with_known_selector?(node)
+          return unless shadowed_count?(option, options)
+
+          [format(SHADOWED_COUNT_MSG, option: option), true]
+        end
+
+        def exact_issue(node, option)
+          [EXACT_MSG, true] if option == :exact && css_query?(node)
+        end
+
+        def exact_text_issue(node, option, pair, options)
+          return unless option == :exact_text
+          return unless ineffective_exact_text?(node, pair, options)
+
+          [EXACT_TEXT_MSG, true]
+        end
+
+        def match_issue(node, option, pair)
+          return unless option == :match && ineffective_match?(node, pair)
+
+          [format(MATCH_MSG, method: node.method_name), true]
+        end
+
+        def css_query?(node)
+          selector = QueryMethods.selector(node.method_name)
+          selector == :css ||
+            (selector == :selector && explicit_selector(node) == :css)
+        end
+
+        def explicit_selector(node)
+          argument = node.first_argument
+          argument.value if argument&.sym_type?
+        end
+
+        def ineffective_exact_text?(node, pair, options)
+          exact_text_supported_call?(node) &&
+            effective_option_pair(options, :exact_text) == pair &&
+            pair.value.type?(:boolean) &&
+            effective_option_pair(options, :text)&.value&.regexp_type?
+        end
+
+        def exact_text_supported_call?(node)
+          QueryMethods.type(node.method_name) != :text &&
+            !custom_selector?(node)
+        end
+
+        def ineffective_match?(node, pair)
+          QueryMethods.type(node.method_name) == :collection &&
+            QueryMethods.built_in_selector?(explicit_selector(node)) &&
+            pair.value.sym_type? &&
+            MATCH_STRATEGIES.include?(pair.value.value)
+        end
+
+        def shadowed_count?(option, options)
+          option != :count && COUNT_OPTIONS.include?(option) &&
+            count_specified?(options)
+        end
+
+        def count_query_with_known_selector?(node)
+          selector = QueryMethods.selector(node.method_name)
+          return true unless selector == :selector
+
+          QueryMethods.built_in_selector?(explicit_selector(node))
+        end
+
+        def custom_selector?(node)
+          QueryMethods.selector(node.method_name) == :selector &&
+            !QueryMethods.built_in_selector?(query_selector(node))
+        end
+
+        def query_selector(node)
+          selector = explicit_selector(node)
+          return selector if selector
+
+          positional = node.arguments.reject do |arg|
+            arg.type?(:hash, :block_pass)
+          end
+          return if positional.length > 1
+
+          cop_config['DefaultSelector'].to_s.to_sym
+        end
+
+        def count_specified?(options)
+          effective_option_pair(options, :count)&.value&.truthy_literal?
+        end
+
+        def effective_option_pair(options, name)
+          options.pairs.reverse_each.find { |pair| pair.key.value == name }
+        end
+
+        def comments_in?(node)
+          processed_source.comments.any? do |comment|
+            comment.loc.line.between?(node.first_line, node.last_line)
+          end
+        end
+
+        def removable?(options, pair)
+          return false unless removable_value?(pair.value)
+          return false if pair.value.str_type? && pair.value.heredoc?
+
+          options.pairs.one? { |other| other.key == pair.key }
+        end
+
+        def remove_option(corrector, node, options, pair)
+          first = node.first_argument == options &&
+            options.children.first == pair
+          side = first ? :right : :left
+          range = range_with_surrounding_space(pair.source_range, side: side)
+          range = range_with_surrounding_comma(range, side)
+          corrector.remove(range_with_surrounding_space(range, side: side))
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/capybara/mixin/capybara_help.rb

@@ -5,11 +5,13 @@ module RuboCop
     module Capybara
       # Help methods for capybara.
       # @api private
-      module CapybaraHelp
+      module CapybaraHelp # rubocop:disable Metrics/ModuleLength
+        extend RuboCop::AST::NodePattern::Macros
+
         CAPYBARA_MATCHERS = %w[
           selector css xpath text title current_path link button
           field checked_field unchecked_field select table
-          sibling ancestor content
+          sibling ancestor content element
         ].freeze
         POSITIVE_MATCHERS =
           Set.new(CAPYBARA_MATCHERS) { |element| :"have_#{element}" }.freeze
@@ -45,9 +47,91 @@ module RuboCop
         SPECIFIC_PSEUDO_CLASSES = %w[
           not() disabled enabled checked unchecked
         ].freeze
+        VISIBILITY_MATCHER_METHODS = %w[
+          button checked_field css field link select selector table
+          unchecked_field xpath
+        ].flat_map do |element|
+          [:"have_#{element}", :"have_no_#{element}"]
+        end.freeze
+        VISIBILITY_FALSE_MESSAGE = 'Use `:all` or `:hidden` instead of `false`.'
+        VISIBILITY_TRUE_MESSAGE = 'Use `:visible` instead of `true`.'
 
         module_function
 
+        # Recognize the Capybara DSL and finder chains, not arbitrary objects
+        # with methods such as Enumerable#find or ActiveRecord#first.
+        # Recursive references intentionally use the pattern-only matcher.
+        # Resolving local variables here would recurse forever for assignments
+        # such as `tr = tr.find(...)`.
+        # @!method capybara_receiver_pattern?(node)
+        def_node_matcher :capybara_receiver_pattern?, <<~PATTERN
+          {nil? self
+           (call {nil? self} :page)
+           (call (const {nil? cbase} :Capybara) :current_session)
+           (call #capybara_receiver_pattern?
+             {:all :ancestor :find :find_all :find_button :find_by_id
+              :find_field :find_link :first :sibling} ...)
+           (any_block #capybara_receiver_pattern? ...)
+           (begin #capybara_receiver_pattern?) }
+        PATTERN
+        module_function :capybara_receiver_pattern?
+
+        # @param node [RuboCop::AST::Node]
+        # @return [Boolean]
+        def capybara_receiver?(node)
+          capybara_receiver_pattern?(node) ||
+            local_variable_capybara_receiver?(node)
+        end
+        module_function :capybara_receiver?
+
+        # ponytail: Only preceding direct assignments in visible lexical scopes;
+        # use data-flow analysis if coverage grows.
+        def local_variable_capybara_receiver?(node)
+          value = local_variable_value(node)
+          value && capybara_receiver_pattern?(value)
+        end
+        module_function :local_variable_capybara_receiver?
+
+        def local_variable_value(node)
+          return unless node.lvar_type?
+
+          name = node.children.first
+          scopes = node.each_ancestor.take_while do |scope|
+            outer_assignment_visible_through?(scope, name)
+          end
+          assignment = scopes.filter_map do |scope|
+            local_variable_assignment(node, scope) if scope.begin_type?
+          end.first
+          assignment && assignment.children[1]
+        end
+        module_function :local_variable_value
+
+        def outer_assignment_visible_through?(scope, name)
+          return false if scope.type?(:any_def, :class, :module, :sclass)
+
+          !scope.block_type? ||
+            !shadowed_block_variable?(scope.arguments, name)
+        end
+        module_function :outer_assignment_visible_through?
+
+        def shadowed_block_variable?(arguments, name)
+          args = arguments.each_node(
+            :arg, :optarg, :restarg, :kwarg,
+            :kwoptarg, :kwrestarg, :blockarg, :shadowarg
+          )
+          args.any? { |arg| arg.children.first == name }
+        end
+        module_function :shadowed_block_variable?
+
+        def local_variable_assignment(node, scope)
+          scope.children.reverse.find do |child|
+            child.lvasgn_type? &&
+              child.children.first == node.children.first &&
+              child.source_range.end_pos <= node.source_range.begin_pos
+          end
+        end
+        module_function :local_variable_assignment
+
         # @param node [RuboCop::AST::SendNode]
         # @param locator [String]
         # @param element [String]

data/lib/rubocop/cop/capybara/mixin/css_attributes_parser.rb

@@ -6,6 +6,8 @@ module RuboCop
       # Css selector parser.
       # @api private
       class CssAttributesParser
+        QUOTE_CHARS = ['"', "'"].freeze
+
         def initialize(selector)
           @selector = selector
           @state = :initial
@@ -14,7 +16,7 @@ module RuboCop
           @bracket_count = 0
         end
 
-        # @return [Array<String>]
+        # @return [Hash<String, String, Boolean, nil>]
         def parse # rubocop:disable Metrics/MethodLength
           @selector.each_char do |char|
             if char == '['
@@ -43,7 +45,7 @@ module RuboCop
           @bracket_count -= 1
           if @bracket_count.zero?
             @state = :initial
-            key, value = @temp.split('=')
+            key, value = @temp.split('=', 2)
             @results[key] = normalize_value(value)
             @temp.clear
           else
@@ -52,20 +54,36 @@ module RuboCop
         end
 
         # @param value [String]
-        # @return [Boolean, String]
+        # @return [Boolean, String, nil]
         # @example
         #   normalize_value('true') # => true
         #   normalize_value('false') # => false
         #   normalize_value(nil) # => nil
-        #   normalize_value("foo") # => "'foo'"
+        #   normalize_value("foo") # => "foo"
+        #   normalize_value("'foo'") # => "foo"
         def normalize_value(value)
+          return if value&.match?(/\s+[is]\s*\z/i)
+
           case value
           when 'true' then true
           when 'false' then false
           when nil then nil
-          else "'#{value.gsub(/"|'/, '')}'"
+          else strip_outer_quotes(value)
           end
         end
+
+        def strip_outer_quotes(value)
+          return value unless quoted?(value)
+
+          value[1...-1]
+        end
+
+        def quoted?(value)
+          return false if value.length < 2
+
+          quote = value[0]
+          QUOTE_CHARS.include?(quote) && value.end_with?(quote)
+        end
       end
     end
   end