{"record":{"id":"a3a1355a4f547ead","repo":"teamcapybara/capybara","slug":"locator-locator-class-locator-inspect-for-se","errorCode":null,"errorMessage":"Locator #{locator.class}:#{locator.inspect} for selector #{name.inspect} must #{locator_description}. This will raise an error in a future version of Capybara. Called from: #{Capybara::Helpers.filter_backtrace(caller)}","messagePattern":"Locator #(.+?):#(.+?) for selector #(.+?) must #(.+?)\\. This will raise an error in a future version of Capybara\\. Called from: #(.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"lib/capybara/selector/selector.rb","lineNumber":69,"sourceCode":"    def enable_aria_role\n      @config[:enable_aria_role]\n    end\n\n    def test_id\n      @config[:test_id]\n    end\n\n    def call(locator, **options)\n      if format\n        raise ArgumentError, \"Selector #{@name} does not support #{format}\" unless expressions.key?(format)\n\n        instance_exec(locator, **options, &expressions[format])\n      else\n        warn 'Selector has no format'\n      end\n    ensure\n      unless locator_valid?(locator)\n        Capybara::Helpers.warn(\n          \"Locator #{locator.class}:#{locator.inspect} for selector #{name.inspect} must #{locator_description}. \" \\\n          'This will raise an error in a future version of Capybara. ' \\\n          \"Called from: #{Capybara::Helpers.filter_backtrace(caller)}\"\n        )\n      end\n    end\n\n    def add_error(error_msg)\n      errors << error_msg\n    end\n\n    def expression_for(name, locator, config: @config, format: current_format, **options)\n      Selector.new(name, config: config, format: format).call(locator, **options)\n    end\n\n    # @api private\n    def with_filter_errors(errors)\n      old_errors = @errors","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/teamcapybara/capybara/blob/15b5fdb76e972e9623d5af2123ed3755594f9732/lib/capybara/selector/selector.rb#L51-L87","documentation":"Every Capybara selector declares the locator types it accepts (its locator_types, e.g. String for :css, :xpath, :field). After generating the expression, Selector#call verifies locator_valid?; when the locator is non-nil and does not match the declared types (or does not respond to a required method), Capybara warns with this message, including the caller's backtrace, and states it will raise in a future version. nil locators are allowed.","triggerScenarios":"page.find(:css, 5) or find(:xpath, some_integer); fill_in(user.id, with: 'x') where the numeric ID is passed instead of the field's label/name string; passing a model object, Symbol, or Hash to a selector whose expression expects a String.","commonSituations":"Numeric IDs from factories/sequences flowing into locators (user.id instead of user.name or user.id.to_s); passing ActiveRecord objects instead of their string attributes; custom selectors whose declared expression parameter type differs from what callers actually send; forward-porting code to a Capybara version that added this validation.","solutions":["Convert the locator to the selector's expected type, usually String: fill_in(user.id.to_s, with: 'x') or find(:css, selector.to_s).","Pass the human-readable attribute the selector matches (label text, name, placeholder) instead of a numeric identifier.","For custom selectors, declare locator types matching what callers send (e.g. expression parameter :String vs accepting objects that respond_to :to_str)."],"exampleFix":"# before\nfill_in(user.id, with: 'comment') # locator is Integer -> warning\n\n# after\nfill_in(user.id.to_s, with: 'comment')","handlingStrategy":"type-guard","validationCode":"# Coerce numeric/odd-typed locators before calling selectors\nlocator = locator.to_s unless locator.is_a?(String) || locator.nil?\npage.find(:field, locator, **options)","typeGuard":"def valid_locator?(locator)\n  locator.nil? || locator.is_a?(String) || locator.respond_to?(:to_str)\nend","tryCatchPattern":null,"preventionTips":["Always stringify dynamic locators: fill_in(record.id.to_s, ...), find(:css, class_name.to_s).","Prefer matching on stable human-readable attributes (label text, name, data-test-id) over database IDs.","For custom selectors, declare the expression parameter type explicitly so this validation warns early during development, not in CI.","Run the suite with warnings not suppressed; these warnings become hard errors in future Capybara versions."],"tags":["capybara","locator","type-validation","deprecation","ruby"],"backgroundTag":"wrong-argument-type","analyzedSha":"15b5fdb76e972e9623d5af2123ed3755594f9732","analyzedAt":"2026-08-21T16:53:45.588Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}