teamcapybara/capybara · error · ArgumentError

Match queries don't support quantity options. Invalid keys -

Error message

Match queries don't support quantity options. Invalid keys - #{invalid_options.join(', ')}

What it means

MatchQuery (the query behind assert_matches_selector / matches_selector?) rejects any of COUNT_KEYS (count, minimum, maximum, between) with ArgumentError before running. Matching is about whether one specific element satisfies a selector; quantity options are meaningless there because the candidate set is the single node. The check intersects @options.keys with COUNT_KEYS and reports exactly which keys were illegal, then (if none) falls back to the normal valid-keys check.

Source

Thrown at lib/capybara/queries/match_query.rb:15

# frozen_string_literal: true

module Capybara
  module Queries
    class MatchQuery < Capybara::Queries::SelectorQuery
      def visible
        options.key?(:visible) ? super : :all
      end

    private

      def assert_valid_keys
        invalid_options = @options.keys & COUNT_KEYS
        unless invalid_options.empty?
          raise ArgumentError, "Match queries don't support quantity options. Invalid keys - #{invalid_options.join(', ')}"
        end

        super
      end

      def valid_keys
        super - COUNT_KEYS
      end
    end
  end
end

View on GitHub (pinned to 15b5fdb76e)

Solutions

1. Remove the quantity option: el.assert_matches_selector('li')
2. If you need to assert quantity, do it at the collection level: element.assert_selector('li', count: 2) or expect(el).to have_selector('li', count: 2)
3. Strip count keys when forwarding shared option hashes into match APIs: opts.except(*%i[count minimum maximum between])

Example fix

# before
el.assert_matches_selector('li', count: 2)

# after
el.assert_matches_selector('li')
el.assert_selector('li', count: 2)  # quantity belongs here

count_keys = %i[count minimum maximum between]
el.assert_matches_selector('li') if (opts.keys & count_keys).empty?

def match_query_opts?(opts)
  (opts.keys & %i[count minimum maximum between]).empty?
end

begin
  el.assert_matches_selector('li', **opts)
rescue ArgumentError => e
  raise unless e.message.include?('quantity options')
  el.assert_matches_selector('li', **opts.except(*%i[count minimum maximum between]))
end

When it happens

Trigger: el.assert_matches_selector('li', count: 2); el.matches_selector?('a', minimum: 1); has_selector?-style copy-paste carrying :count into a match assertion: el.assert_matches_selector('button', between: 1..2); also style/text queries don't accept counts, but this specific message is MatchQuery's.

Common situations: Refactoring an assert_selector('li', count: 2) into an element-level matches assertion without dropping the count option, helper methods forwarding a shared options hash into match queries, test templates that always add minimum: 1.

Related errors

• Invalid option(s) #{invalid_names}, should be one of #{valid
• You must specify both x: and y: for a click offset
• Item does not match the provided selector
• Item matched the provided selector
• Unused parameters passed to #{self.class.name} : #{args}

AI-assisted analysis of teamcapybara/capybara@15b5fdb76e (2026-08-21). Data as JSON: /api/errors/d627a65a8c5dc35d. Report an issue: GitHub.