rubocop-capybara 3.0.0 → 3.1.0

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

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

@@ -8,6 +8,8 @@ module RuboCop
       module CssSelector
         module_function
 
+        ID_PATTERN = /\A#((?:[\w-]|\\[.>,+~])+)(?:\.|\z)/.freeze
+
         # @param selector [String]
         # @return [String]
         # @example
@@ -15,9 +17,7 @@ module RuboCop
         #   id('.some-cls') # => nil
         #   id('#some-id.cls') # => some-id
         def id(selector)
-          return unless id?(selector)
-
-          selector.delete('#').gsub(selector.scan(/[^\\]([>,+~.].*)/).join, '')
+          selector[ID_PATTERN, 1]
         end
 
         # @param selector [String]
@@ -26,18 +26,21 @@ module RuboCop
         #   id?('#some-id') # => true
         #   id?('.some-cls') # => false
         def id?(selector)
-          selector.start_with?('#')
+          !id(selector).nil?
         end
 
         # @param selector [String]
-        # @return [Array<String>]
+        # @return [Hash<String, String, Boolean, nil>]
         # @example
         #   classes('#some-id') # => []
         #   classes('.some-cls') # => ['some-cls']
         #   classes('#some-id.some-cls') # => ['some-cls']
         #   classes('#some-id.cls1.cls2') # => ['cls1', 'cls2']
+        #   classes('.some-cls\.with-dot') # => ['some-cls.with-dot']
         def classes(selector)
-          selector.scan(/\.([\w-]*)/).flatten
+          selector.scan(/(?<!\\)\.((?:\\.|[\w-])+)/).flatten.map do |class_name|
+            class_name.gsub('\\.', '.')
+          end
         end
 
         # @param selector [String]
@@ -50,12 +53,12 @@ module RuboCop
         end
 
         # @param selector [String]
-        # @return [Array<String>]
+        # @return [Hash<String, String, Boolean, nil>]
         # @example
         #   attributes('a[foo-bar_baz]') # => {"foo-bar_baz=>nil}
-        #   attributes('button[foo][bar=baz]') # => {"foo"=>nil, "bar"=>"'baz'"}
-        #   attributes('table[foo=bar]') # => {"foo"=>"'bar'"}
-        #   attributes('[foo="bar[baz][qux]"]') # => {"foo"=>"'bar[baz][qux]'"}
+        #   attributes('button[foo][bar=baz]') # => {"foo"=>nil, "bar"=>"baz"}
+        #   attributes('table[foo=bar]') # => {"foo"=>"bar"}
+        #   attributes('[foo="bar[baz][qux]"]') # => {"foo"=>"bar[baz][qux]"}
         def attributes(selector)
           CssAttributesParser.new(selector).parse
         end

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

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Capybara
+      # Classification of Capybara's public query methods.
+      # @api private
+      module QueryMethods
+        BUILT_IN_SELECTORS = %i[
+          button checkbox css datalist_input datalist_option element field
+          fieldset file_field fillable_field frame id label link link_or_button
+          option radio_button select table table_row xpath
+        ].freeze
+
+        # Each entry contains the query type and its selector. `:selector`
+        # means the selector is an argument; nil means it is not applicable.
+        METHODS = begin
+          methods = {
+            find: %i[finder selector],
+            ancestor: %i[finder selector],
+            sibling: %i[finder selector],
+            find_button: %i[finder button],
+            find_by_id: %i[finder id],
+            find_field: %i[finder field],
+            find_link: %i[finder link],
+            within: %i[finder selector]
+          }
+          %i[all find_all first].each do |name|
+            methods[name] = %i[collection selector]
+          end
+
+          %w[
+            ancestor button checked_field css element field link select
+            selector sibling table unchecked_field xpath
+          ].each do |selector|
+            kind = case selector
+                   when 'ancestor', 'sibling' then :selector
+                   when 'checked_field', 'unchecked_field' then :field
+                   else selector.to_sym
+                   end
+            prefixes = %w[assert assert_no refute has has_no have have_no]
+            prefixes += %w[must_have wont_have] unless selector == 'element'
+            prefixes.each do |prefix|
+              name = "#{prefix}_#{selector}"
+              name += '?' if prefix.start_with?('has')
+              methods[name.to_sym] = [:selector, kind]
+            end
+          end
+
+          %w[css selector xpath].each do |selector|
+            %W[
+              assert_matches_#{selector} assert_not_matches_#{selector}
+              refute_matches_#{selector} matches_#{selector}?
+              not_matches_#{selector}? match_#{selector} not_match_#{selector}
+              must_match_#{selector} wont_match_#{selector}
+            ].each { |name| methods[name.to_sym] = [:match, selector.to_sym] }
+          end
+
+          %w[text content].each do |kind|
+            %W[
+              assert_#{kind} assert_no_#{kind} refute_#{kind}
+              has_#{kind}? has_no_#{kind}? have_#{kind} have_no_#{kind}
+              must_have_#{kind} wont_have_#{kind}
+            ].each { |name| methods[name.to_sym] = [:text, nil] }
+          end
+
+          %i[
+            attach_file check choose click_button click_link
+            click_link_or_button click_on fill_in select uncheck unselect
+          ].each { |name| methods[name] = [:action, nil] }
+
+          %w[assert have must_have].product(%w[all any none]) do |prefix, count|
+            methods[:"#{prefix}_#{count}_of_selectors"] = %i[grouped selector]
+          end
+
+          methods.transform_values(&:freeze).freeze
+        end
+        private_constant :METHODS, :BUILT_IN_SELECTORS
+
+        module_function
+
+        # @param types [Array<Symbol>]
+        # @return [Array<Symbol>]
+        # @example
+        #   names(:collection) # => [:all, :find_all, :first]
+        def names(*types)
+          METHODS.filter_map { |name, (type, _)| name if types.include?(type) }
+        end
+
+        # @param method_name [Symbol]
+        # @return [Symbol, nil]
+        # @example
+        #   type(:find) # => :finder
+        #   type(:unknown) # => nil
+        def type(method_name)
+          METHODS[method_name]&.first
+        end
+
+        # @param method_name [Symbol]
+        # @return [Symbol, nil]
+        # @example
+        #   selector(:find_button) # => :button
+        #   selector(:find) # => :selector
+        #   selector(:have_text) # => nil
+        def selector(method_name)
+          METHODS[method_name]&.last
+        end
+
+        # @param selector [Symbol]
+        # @return [Boolean]
+        # @example
+        #   built_in_selector?(:css) # => true
+        #   built_in_selector?(:custom) # => false
+        def built_in_selector?(selector)
+          BUILT_IN_SELECTORS.include?(selector)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Capybara
+      # Shared visibility query checks and offense handling.
+      # @api private
+      module Visibility
+        extend RuboCop::AST::NodePattern::Macros
+
+        # @!method custom_filters?(node)
+        def_node_matcher :custom_filters?, <<~PATTERN
+          (hash <{(pair (sym :filter_set) _) (pair !sym _) kwsplat} ...>)
+        PATTERN
+
+        private
+
+        def supported_visibility_query?(node, options)
+          return false if options.braces? || custom_filters?(options)
+          return true if QueryMethods.selector(node.method_name) != :selector
+
+          QueryMethods.built_in_selector?(query_selector(node))
+        end
+
+        def query_selector(node)
+          selector = node.first_argument
+          return selector.value if selector&.sym_type?
+
+          positional = node.arguments.reject do |arg|
+            arg.type?(:hash, :block_pass)
+          end
+          return if positional.length > 1 && !selector.str_type?
+
+          cop_config['DefaultSelector'].to_s.to_sym
+        end
+
+        def check_visibility(pair)
+          if pair.value.false_type?
+            return add_offense(pair, message: CapybaraHelp::VISIBILITY_FALSE_MESSAGE)
+          end
+
+          add_offense(
+            pair, message: CapybaraHelp::VISIBILITY_TRUE_MESSAGE
+          ) do |corrector|
+            next if block_given? && !yield
+
+            corrector.replace(pair.value, ':visible')
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Capybara
+      # Checks that modal handling methods are called with a block.
+      #
+      # @example
+      #   # bad
+      #   accept_confirm
+      #   page.accept_prompt(with: 'answer')
+      #
+      #   # good
+      #   accept_confirm { click_button 'Delete' }
+      #   page.accept_prompt(with: 'answer', &trigger_modal)
+      #
+      class ModalMethodWithoutBlock < RuboCop::Cop::Base
+        MSG = 'Call `%<method>s` with a block.'
+        RESTRICT_ON_SEND = %i[
+          accept_alert
+          accept_confirm
+          accept_prompt
+          dismiss_confirm
+          dismiss_prompt
+        ].freeze
+
+        def on_send(node)
+          return if node.block_literal? || node.block_argument?
+          return if node.last_argument&.forwarded_args_type?
+
+          add_offense(node, message: format(MSG, method: node.method_name))
+        end
+        alias on_csend on_send
+      end
+    end
+  end
+end