{"record":{"id":"d059246c2f5f2c29","repo":"teamcapybara/capybara","slug":"invalid-option-match-inspect-for-match-should","errorCode":null,"errorMessage":"Invalid option #{match.inspect} for :match, should be one of #{VALID_MATCH.map(&:inspect).join(', ')}","messagePattern":"Invalid option #(.+?) for :match, should be one of #(.+?)","errorType":"exception","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"lib/capybara/queries/selector_query.rb","lineNumber":347,"sourceCode":"        filters\n      end\n\n      def ordered_results(results)\n        case @order\n        when :reverse\n          results.reverse\n        else\n          results\n        end\n      end\n\n      def custom_keys\n        @custom_keys ||= node_filters.keys + expression_filters.keys\n      end\n\n      def assert_valid_keys\n        unless VALID_MATCH.include?(match)\n          raise ArgumentError, \"Invalid option #{match.inspect} for :match, should be one of #{VALID_MATCH.map(&:inspect).join(', ')}\"\n        end\n\n        unhandled_options = @options.keys.reject do |option_name|\n          valid_keys.include?(option_name) ||\n            expression_filters.any? { |_name, ef| ef.handles_option? option_name } ||\n            node_filters.any? { |_name, nf| nf.handles_option? option_name }\n        end\n\n        return if unhandled_options.empty?\n\n        invalid_names = unhandled_options.map(&:inspect).join(', ')\n        valid_names = (valid_keys - [:allow_self]).map(&:inspect).join(', ')\n        raise ArgumentError, \"Invalid option(s) #{invalid_names}, should be one of #{valid_names}\"\n      end\n\n      def filtered_expression(expr)\n        conditions = {}\n        conditions[:id] = options[:id] if use_default_id_filter?","sourceCodeStart":329,"sourceCodeEnd":365,"githubUrl":"https://github.com/teamcapybara/capybara/blob/15b5fdb76e972e9623d5af2123ed3755594f9732/lib/capybara/queries/selector_query.rb#L329-L365","documentation":"Capybara::Queries::SelectorQuery#assert_valid_keys validates the :match option on every finder/matcher call. :match controls how Capybara resolves a locator that matches multiple elements (or exactly/inexactly), and only :first, :smart, :prefer_exact, :one are accepted (VALID_MATCH in lib/capybara/queries/selector_query.rb:13). Any other value raises ArgumentError before the DOM is searched, so this fails fast on the first query that uses it.","triggerScenarios":"Calling any query API that forwards options to SelectorQuery with a bad :match symbol: find('.item', match: :smartest), all('tr', match: :all), first('td', match: :any), have_selector('.x', match: :exact), find(:id, 'foo', match: :one_of) - all raise immediately in assert_valid_keys.","commonSituations":"Typos (:smartest instead of :smart), copying :match values from other libraries (RSpec's :any, minitest's :one!), or a shared helper/spec_support file hardcoding a value that a Capybara upgrade renamed. Also hit when interpolating a configurable match value from an environment variable without validating it.","solutions":["Change the value to one of the four accepted symbols: :first, :smart, :prefer_exact, or :one (most common fix is the :smartest -> :smart typo).","Drop the :match option entirely to use the default (:smart).","If you wanted 'any match is fine, take the first', use first('selector') or match: :first instead of inventing a value.","Set it globally with Capybara.match = :first in your setup instead of passing per-call values that drift from the allowed set."],"exampleFix":"# before\nfind('.item', match: :smartest)\n\n# after\nfind('.item', match: :smart)","handlingStrategy":"validation","validationCode":"VALID_MATCH = %i[first smart prefer_exact one].freeze\n\nmatch_value = :smart # from config/ENV\nraise ArgumentError, \"bad :match #{match_value}\" unless VALID_MATCH.include?(match_value)\nfind('.item', match: match_value)","typeGuard":"def valid_match?(value)\n  %i[first smart prefer_exact one].include?(value)\nend","tryCatchPattern":null,"preventionTips":["Keep :match values in a single constant in spec_support and validate it at boot when it comes from ENV/config.","Assert on the four allowed symbols in helper unit tests when the value is user-configurable."],"tags":["ruby","capybara","selector-query","option-validation"],"backgroundTag":"invalid-option-value","analyzedSha":"15b5fdb76e972e9623d5af2123ed3755594f9732","analyzedAt":"2026-08-21T16:53:45.588Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}