{"record":{"id":"2e9459b34f7c4c77","repo":"teamcapybara/capybara","slug":"item-does-not-match-the-provided-selector","errorCode":null,"errorMessage":"Item does not match the provided selector","messagePattern":"Item does not match the provided selector","errorType":"exception","errorClass":"Capybara::ExpectationNotMet","httpStatus":null,"severity":"error","filePath":"lib/capybara/node/matchers.rb","lineNumber":590,"sourceCode":"      ##\n      #\n      # Asserts that the current node matches a given selector.\n      #\n      #     node.assert_matches_selector('p#foo')\n      #     node.assert_matches_selector(:xpath, '//p[@id=\"foo\"]')\n      #     node.assert_matches_selector(:foo)\n      #\n      # It also accepts all options that {Capybara::Node::Finders#all} accepts,\n      # such as `:text` and `:visible`.\n      #\n      #     node.assert_matches_selector('li', text: 'Horse', visible: true)\n      #\n      # @param (see Capybara::Node::Finders#all)\n      # @raise [Capybara::ExpectationNotMet]      If the selector does not match\n      #\n      def assert_matches_selector(*args, &optional_filter_block)\n        _verify_match_result(args, optional_filter_block) do |result|\n          raise Capybara::ExpectationNotMet, 'Item does not match the provided selector' unless result.include? self\n        end\n      end\n\n      ##\n      #\n      # Asserts that the current node does not match a given selector.\n      # Usage is identical to {#assert_matches_selector}.\n      #\n      # @param (see #assert_matches_selector)\n      # @raise [Capybara::ExpectationNotMet]      If the selector matches\n      #\n      def assert_not_matches_selector(*args, &optional_filter_block)\n        _verify_match_result(args, optional_filter_block) do |result|\n          raise Capybara::ExpectationNotMet, 'Item matched the provided selector' if result.include? self\n        end\n      end\n\n      ##","sourceCodeStart":572,"sourceCodeEnd":608,"githubUrl":"https://github.com/teamcapybara/capybara/blob/15b5fdb76e972e9623d5af2123ed3755594f9732/lib/capybara/node/matchers.rb#L572-L608","documentation":"assert_matches_selector verifies that the receiver element itself is among the nodes matching the given selector plus filters; _verify_match_result resolves the MatchQuery and raises ExpectationNotMet 'Item does not match the provided selector' when self is not in the result set. Unlike assert_selector it checks identity of this specific node, not just that some node matches.","triggerScenarios":"el.assert_matches_selector('li', text: 'Horse') when el is a li but its text is 'Cow'; el.assert_matches_selector('input[type=checkbox]', checked: true) when the box is unchecked; el.assert_matches_selector(:field, 'Email') on an element labelled differently; matching on tag/class that the node does not have.","commonSituations":"Verifying a located element still satisfies a contract after page updates (element went stale or attributes changed between find and assert), wrong filter values (text with different whitespace), asserting on attributes that toggle dynamically (checked/disabled/active class) before the state settles.","solutions":["Inspect the element (el.text, el[:class], el[:type]) and align the selector/filters with its real state","For dynamic states add wait: el.assert_matches_selector('input', checked: true, wait: 5)","Use the right selector type (:field/:link/:css) whose built-in filters match what you assert","If you only care that the page contains such nodes, use assert_selector instead of the element-matching form"],"exampleFix":"# before\nel.assert_matches_selector('li', text: 'Horse')  # el.text == 'Horse '\n\n# after\nel.assert_matches_selector('li', text: /Horse/)\n# or normalize whitespace\nel.assert_matches_selector('li', text: 'Horse', normalize_ws: true)","handlingStrategy":"validation","validationCode":"return unless el.matches_selector?('li', text: /Horse/)\nel.assert_matches_selector('li', text: /Horse/)","typeGuard":"def node_matches?(node, *args, **opts, &block)\n  node.matches_selector?(*args, **opts, &block)\nend","tryCatchPattern":"begin\n  el.assert_matches_selector('input', checked: true, wait: 3)\nrescue Capybara::ExpectationNotMet => e\n  raise unless el.matches_selector?('input') # node exists; state differs — re-drive UI\n  raise\nend","preventionTips":["Use matches_selector? when you need a boolean branch instead of an exception","Assert dynamic states (checked/disabled/class) with wait: >= app update time","Re-find elements after actions that re-render their subtree"],"tags":["capybara","assertion","match-query","element","selector"],"backgroundTag":"element-selector-mismatch","analyzedSha":"15b5fdb76e972e9623d5af2123ed3755594f9732","analyzedAt":"2026-08-21T16:53:45.588Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}