Merge pull request #99 from rubocop/to_ambiguous_click

Add `Capybara/AmbiguousClick` cop and make soft-deprecated `Capybara/ClickLinkOrButtonStyle` cop. If you want to use `EnforcedStyle: strict`, use `Capybara/AmbiguousClick` cop instead

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Edge (Unreleased)
 
+- Add `Capybara/AmbiguousClick` cop and make soft-deprecated `Capybara/ClickLinkOrButtonStyle` cop. If you want to use `EnforcedStyle: strict`, use `Capybara/AmbiguousClick` cop instead. ([@ydah])
+
 ## 2.21.0 (2024-06-08)
 
 - Fix a false negative for `Capybara/NegationMatcher` when using `to_not`. ([@ydah])

config/default.yml

@@ -9,11 +9,17 @@ Capybara:
     - "**/*_steps.rb"
     - "**/features/step_definitions/**/*"
 
+Capybara/AmbiguousClick:
+  Description: Specify the exact target to click on.
+  Enabled: false
+  VersionAdded: "<<next>>"
+  Reference: https://www.rubydoc.info/gems/rubocop-capybara/RuboCop/Cop/Capybara/AmbiguousClick
+
 Capybara/ClickLinkOrButtonStyle:
   Description: Checks for methods of button or link clicks.
-  Enabled: pending
+  Enabled: false
   VersionAdded: '2.19'
-  VersionChanged: '2.20'
+  VersionChanged: "<<next>>"
   EnforcedStyle: link_or_button
   SupportedStyles:
     - link_or_button

docs/modules/ROOT/pages/cops.adoc

@@ -2,6 +2,7 @@
 
 === Department xref:cops_capybara.adoc[Capybara]
 
+* xref:cops_capybara.adoc#capybaraambiguousclick[Capybara/AmbiguousClick]
 * xref:cops_capybara.adoc#capybaraclicklinkorbuttonstyle[Capybara/ClickLinkOrButtonStyle]
 * xref:cops_capybara.adoc#capybaracurrentpathexpectation[Capybara/CurrentPathExpectation]
 * xref:cops_capybara.adoc#capybaramatchstyle[Capybara/MatchStyle]

docs/modules/ROOT/pages/cops_capybara.adoc

@@ -6,20 +6,62 @@
 
 = Capybara
 
+== Capybara/AmbiguousClick
+
+|===
+| Enabled by default | Safe | Supports autocorrection | Version Added | Version Changed
+
+| Disabled
+| Yes
+| No
+| <<next>>
+| -
+|===
+
+Specify the exact target to click on.
+
+In projects where accessibility needs to be considered,
+it is crucial to specify the click target precisely.
+
+=== Examples
+
+[source,ruby]
+----
+# bad
+click_link_or_button('foo')
+click_on('foo')
+
+# good
+click_link('foo')
+click_button('foo')
+----
+
+=== References
+
+* https://www.rubydoc.info/gems/rubocop-capybara/RuboCop/Cop/Capybara/AmbiguousClick
+
 == Capybara/ClickLinkOrButtonStyle
 
 |===
 | Enabled by default | Safe | Supports autocorrection | Version Added | Version Changed
 
-| Pending
+| Disabled
 | Yes
 | No
 | 2.19
-| 2.20
+| <<next>>
 |===
 
 Checks for methods of button or link clicks.
 
+This cop is deprecated.
+We plan to remove this in the next major version update to 3.0.
+
+The migration target is `Capybara/AmbiguousClick`.
+It is only migration target when `EnforcedStyle: strict`.
+If you are using this cop, please plan for migration.
+There is no migration target when `EnforcedStyle: link_or_button`.
+
 By default, prefer to use `click_link_or_button` or `click_on`.
 These methods offer a weaker coupling between the test and HTML,
 allowing for a more faithful reflection of how the user behaves.

lib/rubocop/cop/capybara/ambiguous_click.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Capybara
+      # Specify the exact target to click on.
+      #
+      # In projects where accessibility needs to be considered,
+      # it is crucial to specify the click target precisely.
+      #
+      # @example
+      #   # bad
+      #   click_link_or_button('foo')
+      #   click_on('foo')
+      #
+      #   # good
+      #   click_link('foo')
+      #   click_button('foo')
+      #
+      class AmbiguousClick < ::RuboCop::Cop::Base
+        MSG = 'Use `click_link` or `click_button` instead of `%<method>s`.'
+        RESTRICT_ON_SEND = %i[click_link_or_button click_on].freeze
+
+        def on_send(node)
+          add_offense(node, message: format(MSG, method: node.method_name))
+        end
+      end
+    end
+  end
+end

lib/rubocop/cop/capybara/click_link_or_button_style.rb

@@ -5,6 +5,14 @@ module Cop
     module Capybara
       # Checks for methods of button or link clicks.
       #
+      # This cop is deprecated.
+      # We plan to remove this in the next major version update to 3.0.
+      #
+      # The migration target is `Capybara/AmbiguousClick`.
+      # It is only migration target when `EnforcedStyle: strict`.
+      # If you are using this cop, please plan for migration.
+      # There is no migration target when `EnforcedStyle: link_or_button`.
+      #
       # By default, prefer to use `click_link_or_button` or `click_on`.
       # These methods offer a weaker coupling between the test and HTML,
       # allowing for a more faithful reflection of how the user behaves.

lib/rubocop/cop/capybara_cops.rb

@@ -3,6 +3,7 @@
 require_relative 'capybara/rspec/have_selector'
 require_relative 'capybara/rspec/predicate_matcher'
 
+require_relative 'capybara/ambiguous_click'
 require_relative 'capybara/click_link_or_button_style'
 require_relative 'capybara/current_path_expectation'
 require_relative 'capybara/match_style'

spec/rubocop/cop/capybara/ambiguous_click_spec.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+RSpec.describe RuboCop::Cop::Capybara::AmbiguousClick do
+  it 'registers an offense when using `click_link_or_button`' do
+    expect_offense(<<~RUBY)
+      click_link_or_button('foo')
+      ^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use `click_link` or `click_button` instead of `click_link_or_button`.
+    RUBY
+  end
+
+  it 'registers an offense when using `click_on`' do
+    expect_offense(<<~RUBY)
+      click_on('foo')
+      ^^^^^^^^^^^^^^^ Use `click_link` or `click_button` instead of `click_on`.
+    RUBY
+  end
+
+  it 'does not register an offense when using `click_link`' do
+    expect_no_offenses(<<~RUBY)
+      click_link('foo')
+    RUBY
+  end
+
+  it 'does not register an offense when using `click_button`' do
+    expect_no_offenses(<<~RUBY)
+      click_button('foo')
+    RUBY
+  end
+end