diff --git a/lib/capybara.rb b/lib/capybara.rb
index 211818a0..0710b399 100644
--- a/lib/capybara.rb
+++ b/lib/capybara.rb
@@ -83,6 +83,7 @@ module Capybara
# [threadsafe = Boolean] Whether sessions can be configured individually (Default: false)
# [server = Symbol] The name of the registered server to use when running the app under test (Default: :webrick)
# [default_set_options = Hash] The default options passed to Node::set (Default: {})
+ # [test_id = Symbol/String/nil] Optional attribute to match locator aginst with builtin selectors along with id (Default: 'data-test-id')
#
# === DSL Options
#
@@ -483,6 +484,7 @@ Capybara.configure do |config|
config.enable_aria_label = false
config.reuse_server = true
config.default_set_options = {}
+ config.test_id = 'data-test-id'
end
Capybara.register_driver :rack_test do |app|
diff --git a/lib/capybara/config.rb b/lib/capybara/config.rb
index d10542c9..d3a5a329 100644
--- a/lib/capybara/config.rb
+++ b/lib/capybara/config.rb
@@ -7,11 +7,12 @@ module Capybara
class Config
extend Forwardable
- OPTIONS = %i[app reuse_server threadsafe default_wait_time server default_driver javascript_driver].freeze
+ OPTIONS = %i[app reuse_server threadsafe default_wait_time server default_driver javascript_driver test_id].freeze
attr_accessor :app
attr_reader :reuse_server, :threadsafe
attr_reader :session_options
+ attr_reader :test_id
attr_writer :default_driver, :javascript_driver
SessionConfig::OPTIONS.each do |method|
@@ -79,6 +80,18 @@ module Capybara
@javascript_driver || :selenium
end
+ ##
+ #
+ # Set an attribue to be optionally matched against the locator for builtin selector types.
+ # This attribute will be checked by builtin selector types whenever id would normally be checked.
+ # If `nil` then it will be ignored.
+ #
+ # @params [String, Symbol, nil] id Name of the attribute to use as the test id
+ #
+ def test_id=(id)
+ @test_id = id&.to_sym
+ end
+
def deprecate(method, alternate_method, once = false)
@deprecation_notified ||= {}
warn "DEPRECATED: ##{method} is deprecated, please use ##{alternate_method} instead" unless once && @deprecation_notified[method]
diff --git a/lib/capybara/node/actions.rb b/lib/capybara/node/actions.rb
index 8d3d9a7e..86ab9af5 100644
--- a/lib/capybara/node/actions.rb
+++ b/lib/capybara/node/actions.rb
@@ -27,13 +27,13 @@ module Capybara
##
#
- # Finds a link by id, text or title and clicks it. Also looks at image
+ # Finds a link by id, Capybara.test_id attribute, text or title and clicks it. Also looks at image
# alt text inside the link.
#
# @macro waiting_behavior
#
# @overload click_link([locator], options)
- # @param [String] locator text, id, title or nested image's alt attribute
+ # @param [String] locator text, id, Capybara.test_id attribute, title or nested image's alt attribute
# @param options See {Capybara::Node::Finders#find_link}
#
# @return [Capybara::Node::Element] The element clicked
@@ -45,7 +45,7 @@ module Capybara
#
# Finds a button on the page and clicks it.
# This can be any \ element of type submit, reset, image, button or it can be a
- # \